Made the custom memory allocator symbols hidden. This prevents

[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 "4 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 "int pwmd_get_password(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
.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 "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 "void pwmd_close(pwm_t " *pwm ");"
.BI "const char *pwmd_strerror(gpg_error_t " error ");"
.P
.BI "typedef int (*" pwmd_status_func ")(void *" data ", const char *" line ");"
.BI "typedef char *(*" pwmd_password_func ")(void *" data ");"
.P
.BI "typedef struct {"
.BI "    char " password[ASSUAN_LINELENGTH] ";"
.BI "    gpg_error_t " error ";"
.BI "} " pwmd_password_t ";"
.fi
.SH DESCRIPTION
.B libpwmd
is an library making it easy for applications to use
.BR pwmd (1).
.P
.TP
.B "pwmd_error_t pwmd_init(void);"
Initializes libassuan and libgpg-error stuff. Be sure to call this before
using the other functions.
.P
.TP
.B "pwm_t *pwmd_connect(const char " *socket ", gpg_error_t " *error ");"
\fBpwmd_connect\fP() 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 in
the other library functions.
.P
.TP
.B "int pwmd_get_password(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
This is a non-blocking
.BR pinentry (1)
password retrieval function. When successful it returns a file descriptor that
.BR select (2)
can use to determine when a password can be read with
.BR read (2)
to open the file \fIfilename\fP.
.BR read (2)
should read a \fIpwmd_password_s\fP and check \fI.error\fP for an
error code returned by
.BR pinentry (1).
If there is an error during 
.BR pipe (2)
or
.BR fork (2),
the function returns -1 and \fIerror\fP is set to the error code of the failed
function. If the file is cached on the server or the file is nonexistant, a
password is not needed and -2 is returned. After the password has been gotten,
call \fBpwmd_setopt\fP() to set the password and make sure 
.B PWMD_OPTION_PINENTRY
is unset. Security note: it's up to the caller to clear the password; usually
with
.BR memset (3).
.P
.TP
.B "pwmd_error_t pwmd_setopt(pwm_t " *pwm ", gpg_error_t " *error ", pwmd_option_t " opt ", ...);"
\fBpwmd_setopt\fP() 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 \fBpwmd_password_func\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.
.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.
.RE
.RE
.P
.TP
.B "pwmd_error_t pwmd_open(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
\fBpwmd_open\fP() opens the specified \fIfilename\fP on the server. The
password for the file is gotten from either
.BR pinentry (1)
or the value set 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
.B "pwmd_error_t pwmd_command(pwm_t " *pwm ", char " **result ", gpg_error_t " *error ", const char " *cmd ", " ... ");"
\fBpwmd_command\fP() sends a protocol command to the server. The function
returns \fBPWMD_OK\fP when successful and stores the result of the command
\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. 
.P
.TP
.B "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.
.P
.TP
.B "pwmd_error_t pwmd_save(pwm_t " *pwm ", gpg_error_t " *error ");"
\fBpwmd_save\fP() saves the changes to the opened file. If not called before
disconnecting from the server then any changes will be lost. If an error
occurs then \fBPWMD_ERROR\fP is returned and \fIerror\fP is set to the error
code of the failed function. Otherwise \fBPWMD_OK\fP is returned.
.P
.TP
.B "void pwmd_close(pwm_t " *pwm ");"
\fBpwmd_close\fP() closes the connection to the server and frees resources
used by the handle \fIpwm\fP.
.P
.TP
.B "const char *pwmd_strerror(gpg_error_t " error ");"
\fBpwmd_strerror\fP() 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)