Make the filename argument to pwmc optional. The command may be a

[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 "10 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 "pwmd_error_t pwmd_init(void);"
.BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
.BI "pwmd_error_t pwmd_setopt(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_option_t " opt ", ...);"
.BI "pwmd_error_t pwmd_open(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ");"
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ");"
.BI "pwmd_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_nb_status_t *" status ");"
.BI "pwmd_error_t pwmd_command(pwm_t *" pwm ", char **" result ", gpg_error_t *" error ", const char *" cmd ", " ... ");"
.BI "void pwmd_free_result(void *" result ");"
.BI "pwmd_error_t pwmd_save(pwm_t *" pwm ", gpg_error_t *" error ");"
.BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
.BI "pwmd_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_nb_status_t *" status ");"
.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 "pwmd_error_t pwmd_init(void);"
Initializes libassuan and libgpg-error stuff. Be sure to call this before
using the other functions.
.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 "pwmd_error_t pwmd_setopt(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_option_t " opt ", ...);"
Set the library option \fIopt\fP to the value of the next argument where
\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_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.
.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. At the moment,
.BR pwmd (1)
only send's status messages when opening or saving a file and configured to do
so.
.RE
.RE
.P
.TP
.BI "pwmd_error_t pwmd_open(pwm_t *" pwm ", gpg_error_t *" error ", 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().
\fBPWMD_ERROR\fP is returned on error with \fIerror\fP set to the error code
of the failed function. Otherwise \fBPWMD_OK\fP is returned.
.P
.TP
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ");"
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. Note that \fBPWMD_OPTION_PINENTRY\fP must be
set.
.P
.TP
.BI "pwmd_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_open_nb\fP(); it updates the handle \fIpwm\fP. 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, \fIerror\fP is set and \fBPWMD_ERROR\fP is returned. Otherwise
\fBPWMD_OK\fP is returned.
.P
.TP
.BI "pwmd_error_t pwmd_command(pwm_t *" pwm ", char **" result ", gpg_error_t *" error ", const char *" cmd ", " ... ");"
Sends a protocol command to the server. The function returns \fBPWMD_OK\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 \fBPWMD_ERROR\fP is returned and \fIerror\fP is set to
the error code. 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 "pwmd_error_t pwmd_save(pwm_t *" pwm ", gpg_error_t *" error ");"
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 \fBPWMD_ERROR\fP is returned and \fIerror\fP is set. Otherwise
\fBPWMD_OK\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 "pwmd_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", gpg_error_t *" error ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_save_nb\fP(); it updates the handle \fIpwm\fP. 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, \fIerror\fP is set and \fBPWMD_ERROR\fP is returned. Otherwise
\fBPWMD_OK\fP is returned.
.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 @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)