Use the new EXISTS protocol command to determine whether a file is new

[libpwmd.git] / libpwmd.3.in

.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH LIBPWMD 3 "12 Jul 2007" "Password Manager Daemon Library" "Password Manager Daemon Library"
.SH NAME

libpwmd \- pwmd client interface library
.SH SYNOPSIS
.nf
.B #include <libpwmd.h>
.sp
.BI "gpg_error_t pwmd_init(void);"
.BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
.BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
.BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
.BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
.BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
.BI "void pwmd_free_result(void *" result ");"
.BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
.BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
.BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
.BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
.BI "void pwmd_close(pwm_t *" pwm ");"
.BI "const char *pwmd_strerror(gpg_error_t " error ");"
.P
.BI "typedef int (*" pwmd_status_fn ")(void *" data ", const char *" line ");"
.BI "typedef char *(*" pwmd_password_fn ")(pwm_t *" pwm ", void *" data ");"
.fi
.SH DESCRIPTION
.B libpwmd
is an library making it easy for applications to use
.BR pwmd (1).
.P
.TP
.BI "gpg_error_t pwmd_init(void);"
Initializes \fBlibpwmd\fP, \fBlibassuan\fP, \fBlibgpg-error\fP and
internationalization. Be sure to call this before using the other functions.
If your application uses
.BR gettext(3)
be sure to call
.BR setlocale(3)
and
.BR textdomain(3)
before calling this function.
.P
.TP
.BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
Connects to the specified \fIsocket\fP. If \fIsocket\fP is NULL then a default
of \fI~/.pwmd/socket\fP will be used. If there is an error while connecting
\fIerror\fP is set to the error code of the failed function and NULL is
returned. When successful a handle is returned for use with the other library
functions.
.P
.TP
.BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
Set the library option \fIopt\fP to the value of the next argument. Returns 0
on success or an error code. \fIopt\fP is one of the following:
.RS
.TP
.B PWMD_OPTION_PASSWORD_FUNC
Specifies a function to use to get a password. The next argument should be of
type \fIpwmd_password_fn\fP. The function should return a \fIchar
*\fP string which is the password or NULL if there is an
error.
.TP
.B PWMD_OPTION_PASSWORD_DATA
A user data pointer passed to the password function.
.TP
.B PWMD_OPTION_PINENTRY
Whether to use 
.BR pinentry (1)
to obtain the password when opening and saving a file on the server. The
following argument is an \fIint\fP and is \fI1\fP to enable
.BR pinentry (1)
use, and \fI0\fP to use the password which is set with
\fBPWMD_OPTION_PASSWORD\fP or \fBPWMD_OPTION_PASSWORD_FUNC\fP.
.TP
.B PWMD_OPTION_PINENTRY_TRIES
The next argument if type \fIint\fP specifies the number of invalid password
tries before
.BR pinentry (1)
gives up. Only \fBpwmd_open\fP() and \fBpwmd_open_nb\fP() will use this
option. \fBpwmd_save\fP() and \fBpwmd_save_nb\fP() will continue to confirm a
password until either a match is entered or Cancel is selected.
.TP
.B PWMD_OPTION_PINENTRY_TTY
.TP
.B PWMD_OPTION_PINENTRY_TERM
.TP
.B PWMD_OPTION_PINENTRY_DISPLAY
Sets the
.BR pinentry (1)
command line options. The next argument should be of type \fIchar *\fP. If not
set, then the current DISPLAY, if set, or tty will be used.
.P
.RS
If the file \fI~/.pwmd/env\fP exists then values for the above settings will
read from this file. The format of the file is one NAME=VALUE per line where
NAME is one of TTY, TERM or DISPLAY. The value for an existing setting will be
updated to the value contained in the file.
.RE
.TP
.B PWMD_OPTION_PINENTRY_TITLE
.TP
.B PWMD_OPTION_PINENTRY_DESC
.TP
.B PWMD_OPTION_PINENTRY_PROMPT
Sets the strings used in the 
.BR pinentry (1)
program.
The next argument is of type \fIchar *\fP. If not defined then a default will
be used.
.TP
.B PWMD_OPTION_PASSWORD
Sets the password to use for opening and saving a file when
\fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
and is of type \fIchar *\fP.
.TP
.B PWMD_OPTION_STATUS_FUNC
.TP
.B PWMD_OPTION_STATUS_DATA
Function to be called when 
.BR pwmd (1)
sends a status message. This function should return \fB0\fP on success or a
\fBgpg_error_t\fP on failure. The data passed to the function can be set with
\fBPWMD_OPTION_STATUS_DATA\fP. Status message lines are prefixed with a
keyword followed by a space then the message. Read the \fBlibassuan\fP
documentation for more information. 
.RE
.RE
.P
.TP
.BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
Opens the specified \fIfilename\fP on the server. The password for the file is
gotten from one of the methods specified with \fBpwmd_setopt\fP().
An error code is returned on error or \fB0\fP on success.
.P
.TP
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
This is a nonblocking way of obtaining the password from
.BR pinentry (1)
when opening a file on the server. When successful, it returns a file
descriptor that
.BR select (2)
can use. When ready,
.BR read (2)
should read a \fIpwmd_nb_status_t\fP and then call
\fBpwmd_open_nb_finalize\fP() to update the handle. If there is an error,
\fB-1\fP is returned and \fIerror\fP is set. If \fIfilename\fP is already
cached on the server or doesn't exist on the filesystem and the open
succeeded, \fB-2\fP is returned. The \fItimeout\fP argument is the number of
seconds until the pinentry process will terminate. If \fB0\fP, the default, no
timeout will be used. Note that \fBPWMD_OPTION_PINENTRY\fP must be set and
that if a timeout is specified then the child process will modify it's
\fBSIGALRM\fP handler.
.P
.TP
.BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_open_nb\fP(); it updates the handle \fIpwm\fP and closes
the file descriptor. This should be called right after the successful
.BR read (2)
of \fIstatus\fP from the file descriptor returned by \fBpwmd_open_nb\fP(). If
there was a protocol or
.BR pinentry (1)
error, an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
Sends a protocol command to the server. The function returns \fB0\fP
when successful and stores the result of the command format string \fIcmd\fP
to \fIresult\fP. The result should be free'd with \fBpwmd_free_result\fP().
Protocol commands that don't have a result will set \fIresult\fP to NULL. If
an error occurs then an error code is returned. Note: the BYE protocol
command should not be sent here. Use \fBpwmd_close\fP() instead.
.P
.TP
.BI "void pwmd_free_result(void *" result ");"
Deallocates the memory of \fBpwmd_command\fP() result. It is important to use
this function because
.B libpwmd
not only keeps track of all allocated memory used by other
.B libpwmd
functions, but also clears the memory contents for better security. Don't use
this to free your own allocated memory though.
.P
.TP
.BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
Saves the changes to the file associated with the handle \fIpwm\fP. If not
called before \fBpwmd_close\fP() then any changes will be lost. If an error
occurs then an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
This is a nonblocking way of obtaining the password from
.BR pinentry (1)
when saving an opened file. When successful, a file descriptor is returned
that
.BR select (2)
can use. When ready
.BR read (2)
should read a \fIpwmd_nb_status_t\fP and then call
\fBpwmd_save_nb_finalize\fP() to update the handle. If there was an error,
\fB-1\fP is returned and \fIerror\fP is set. If the file is cached on the
server and the save succeeded, \fB-2\fP is returned. Note that
\fBPWMD_OPTION_PINENTRY\fP must be set.
.P
.TP
.BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_save_nb\fP(); it updates the handle \fIpwm\fP and closes
the file descriptor. This should be called right after the successful
.BR read (2)
of \fIstatus\fP from the file descriptor returned by \fBpwmd_save_nb\fP(). If
there was a protocol or
.BR pinentry (1)
error, an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
Terminates a
.BR pinentry (1)
process associated with the handle \fIpwm\fP. This may be useful if your
application wants to use a timeout for password entry but doesn't use
\fBpwmd_open_nb\fP(). Returns \fB0\fP on success or an error code on failure.
.P
.TP
.BI "void pwmd_close(pwm_t *" pwm ");"
Closes the server connection and free's resources used by the handle
\fIpwm\fP.
.P
.TP
.BI "const char *pwmd_strerror(gpg_error_t " error ");"
Returns a string describing the error code \fIerror\fP which was set from one
of the above functions.

.SH FILES
.TP
.B ~/.pwmd/socket
Default connecting socket.
.TP
.B ~/.pwmd/env
Optional file containing pinentry settings.
.TP
.B @prefix@/lib/pkgconfig/libpwmd.pc
A
.BR pkg-config (1)
metadata file.
.TP
.B @prefix@/include/libpwmd.h
Installed location of header file.

.SH AUTHOR
Ben Kibbey <bjk@luxsci.net>
.br
.URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .

.SH "SEE ALSO"
.BR pwmd (1),
.BR pinentry (1),
.BR pkg-config (1)

And the \fBlibassuan\fP
.BR info (1)
documentation.