Another fix for commit 592815d. Don't close the SSH session when an OPEN

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "11 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libpwmd.h \- 
.SH "Detailed Description"
.PP 
libpwmd is a library making it easy for applications to use the pwmd server.
.SH "SSH Details"
.PP
A remote connection to a pwmd server is possible by using an SSH channel which spawns a shell and executes a proxy server that connects to the pwmd local UNIX domain socket. Authentication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local file containing SHA1 hashes of known hosts. It's a lot like how the standard OpenSSH does things only the known_hosts file is in a different format.
.PP
The server hash can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file. This file is then used as the \fIknown_hosts\fP argument to the SSH connection functions.
.PP
Here's an example \fBauthorized_keys(5)\fP entry. The hash portion should be the same as the contents of the \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions:
.PP
.PP
.nf
 command='socat gopen:$HOME/.pwmd/socket -' <hash> ...
.fi
.PP
.PP
\fBNote:\fP
.RS 4
Only an SSH identity without a passphrase is supported. For now anyway.
.RE
.PP
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display. 
.RE
.PP
.SH "Pinentry Details"
.PP
\fBpinentry(1)\fP is a program that prompts the user for input which is normally a passphrase or a confirmation. libpwmd can use this program either locally (X11 forwarding is not yet supported) or have the pwmd server use it's pinentry to retrieve a passphrase when needed. How this is done depends what function gets called.
.PP
There are a few options that tell pinentry how and where to prompt for a needed passphrase. See the \fBpwmd_option_t\fP section for details. These options are not sent (when using pwmd's pinentry, not the local one) until the pinentry is needed.
.PP
If using a local pinentry by calling \fBpwmd_open2()\fP, \fBpwmd_save2()\fP, \fBpwmd_open_async2()\fP or \fBpwmd_save_async2()\fP, libpwmd will send the command 'OPTION PINENTRY=0' to the pwmd server. This is needed so pwmd wont try to launch it's own pinentry on passphrase or confirmation failure. So you may need to reset this option manually depending on your needs.
.PP
Some pinentry options can also be specified in a local configuration file \fI'~/.pwmd/pinentry.conf'\fP. These options are initial values for each pinentry invokation and may be changed by setting the appropriate \fBpwmd_option_t\fP. Each option and value is separated with a '=' on a single line. Unrecognized options are ignored. Here are the recognized options:
.PP
\fBParameters:\fP
.RS 4
\fIPATH\fP The full path to the location of the pinentry binary. 
.br
\fIDISPLAY\fP The X11 display to use. 
.br
\fITTYNAME\fP The full path to the tty that pinentry should prompt on. 
.br
\fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set.
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
.PP
After establishing an SSH connection, the pwmd pinentry is disabled by sending the command 'OPTION PINENTRY=0'. This is needed because there currently isn't a way to have the remote pinentry use the local display. You must be careful to use either a local pinentry or set a passphrase manually with \fBpwmd_setopt()\fP when a passphrase is required or needed.
.RE
.PP
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBSSH Details\fP
.RE
.PP
.SH "Errors"
.PP
libpwmd uses libgpg-error for all error codes. Some are user defined GPG_ERR_USER_N codes, but most are reused from the existing ones. Error codes can be described by using \fBpwmd_strerror()\fP, or the thread-safe \fBpwmd_strerror_r()\fP.
.PP
\fBNote:\fP
.RS 4
Internally, some error codes are a bitmask of an error source. In order to simplify the result codes, libpwmd strips any error source from the error code before returning it.
.RE
.PP
.SH "Example Client"
.PP
The following example will list the element tree of the data file specified in the first command line argument.
.PP
.PP
.nf
 #include <stdio.h>
 #include <stdlib.h>
 #include <libpwmd.h>

 int main(int argc, char **argv)
 {
     pwm_t *pwm = pwmd_new(NULL);
     gpg_error_t rc = pwmd_connect(pwm, NULL);
     char *result;
     
     if (!rc) {
         rc = pwmd_open(pwm, argv[1]);

         if (!rc) {
             rc = pwmd_command(pwm, &result, '%s', 'LIST');

             if (!rc) {
                 printf('%s', result);
                 pwmd_free(result);
             }
         }
     }

     pwmd_close(pwm);
     
     if (rc)
         fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc));

     exit(rc ? 1 : 0);
 }
.fi
.PP
 
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBpwmd_fd_t\fP"
.br
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBLIBPWMD_VERSION\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FD_READABLE\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FD_WRITABLE\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_ERROR\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_MAX_SLOTS\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_LOOP\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_NO_FILE\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_LIBXML_ERROR\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_FILE_MODIFIED\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_MAX\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct pwm_s \fBpwm_t\fP"
.br
.ti -1c
.RI "typedef gpg_error_t(* \fBpwmd_passphrase_cb_t\fP )(void *user, char **passphrase)"
.br
.ti -1c
.RI "typedef int(* \fBpwmd_status_cb_t\fP )(void *user, const char *line)"
.br
.ti -1c
.RI "typedef gpg_error_t(* \fBpwmd_inquire_cb_t\fP )(void *user, const char *cmd, gpg_error_t rc, char **data, size_t *len)"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBpwmd_async_t\fP { \fBASYNC_INIT\fP, \fBASYNC_PROCESS\fP, \fBASYNC_DONE\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_ip_version_t\fP { \fBPWMD_IP_ANY\fP, \fBPWMD_IPV4\fP, \fBPWMD_IPV6\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_socket_t\fP { \fBPWMD_SOCKET_UDS\fP, \fBPWMD_SOCKET_SSH\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PASSPHRASE\fP, \fBPWMD_OPTION_PINENTRY_TRIES\fP, \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_TITLE\fP, \fBPWMD_OPTION_PINENTRY_PROMPT\fP, \fBPWMD_OPTION_PINENTRY_DESC\fP, \fBPWMD_OPTION_PINENTRY_LC_CTYPE\fP, \fBPWMD_OPTION_PINENTRY_LC_MESSAGES\fP, \fBPWMD_OPTION_PINENTRY_TIMEOUT\fP, \fBPWMD_OPTION_STATUS_CB\fP, \fBPWMD_OPTION_STATUS_DATA\fP, \fBPWMD_OPTION_IP_VERSION\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "gpg_error_t \fBpwmd_init\fP (void)"
.br
.ti -1c
.RI "\fBpwm_t\fP * \fBpwmd_new\fP (const char *name)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_ssh_connect\fP (\fBpwm_t\fP *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_ssh_connect_async\fP (\fBpwm_t\fP *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_connect_url\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_connect_url_async\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_hostkey\fP (\fBpwm_t\fP *pwm, const char *host, int port, char **result)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_hostkey_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_fds\fP (\fBpwm_t\fP *pwm, pwmd_fd_t *fds, int *n_fds)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,...)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "\fBpwmd_async_t\fP \fBpwmd_process\fP (\fBpwm_t\fP *pwm, gpg_error_t *rc, char **result)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_inquire\fP (\fBpwm_t\fP *pwm, const char *cmd, \fBpwmd_inquire_cb_t\fP func, void *user)"
.br
.ti -1c
.RI "void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
.br
.ti -1c
.RI "void \fBpwmd_free\fP (void *ptr)"
.br
.ti -1c
.RI "void * \fBpwmd_malloc\fP (size_t size)"
.br
.ti -1c
.RI "void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
.br
.ti -1c
.RI "void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
.br
.ti -1c
.RI "char * \fBpwmd_strdup\fP (const char *str)"
.br
.ti -1c
.RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)"
.br
.ti -1c
.RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)"
.br
.ti -1c
.RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)"
.br
.in -1c
.SH "Define Documentation"
.PP 
.SS "#define EPWMD_ERROR"
.PP
A general pwmd error with no suitable description. 
.SS "#define EPWMD_FILE_MODIFIED"
.PP
The data file was modified either externally or by another client while trying to process a command. 
.SS "#define EPWMD_LIBXML_ERROR"
.PP
An XML parse or other libxml2 error occurred. 
.SS "#define EPWMD_LOOP"
.PP
A recursion loop was detected while processing a 'target' attribute. 
.SS "#define EPWMD_MAX_SLOTS"
.PP
The maximum number of cache slots has been reached. There is no available slot for a new file. 
.SS "#define EPWMD_NO_FILE"
.PP
A command required an open file but no file has yet been opened. 
.SS "#define LIBPWMD_VERSION"
.PP
The version of this library. 
.SS "#define PWMD_FD_READABLE"
.PP
Set when the file descriptor is readable. 
.SS "#define PWMD_FD_WRITABLE"
.PP
Set when the file descriptor is writable. 
.SH "Typedef Documentation"
.PP 
.SS "\fBpwm_t\fP"
.PP
When a handle is mentioned in this documentation it is a pointer of this type. A new handle is created with \fBpwmd_new()\fP. 
.SS "\fBpwmd_inquire_cb_t\fP"
.PP
This is a callback function that gets passed to \fBpwmd_inquire()\fP. It is used for sending data to the server for commands that need to reply to an INQUIRE response (STORE and IMPORT). The reason for this callback is to let the client send as many bytes as it wants rather than the entire chunk at once. It gets called during an internal \fBassuan_transact()\fP from an internal inquire callback function which in turn calls this function by looping over its return value.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP The user data pointer passed to \fBpwmd_inquire()\fP. 
.br
\fIcmd\fP The same as the \fIcmd\fP argument to \fBpwmd_inquire()\fP. 
.br
\fIrc\fP The result of the last internal call to \fBassuan_send_data()\fP which did the sending of the data to the pwmd server. On the first call to this callback it's value will always be 0 because no data has been sent yet. 
.br
\fIdata\fP The next chunk of data to send or NULL. 
.br
\fIlen\fP The length of \fIdata\fP or 0.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP There is more data to be sent. 
.br
\fIGPG_ERR_EOF\fP No need to call this function again, the current \fIline\fP is the last to send. 
.br
\fIcode\fP Any other error code which will terminate the INQUIRE.
.RE
.PP
\fBNote:\fP
.RS 4
The sent data is processed line-per-line. The line is either newline terminated or is buffered until ASSUAN_LINELENGTH bytes have been allocated. Any remaining bytes are sent after the INQUIRE has finished. 
.RE
.PP

.SS "\fBpwmd_passphrase_cb_t\fP"
.PP
The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwmd_setopt()\fP.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_PASSPHRASE_DATA\fP. 
.br
\fIpassphrase\fP The passphrase which may be an empty string or NULL. It is not modified by libpwmd but must remain allocated for as long as it is needed. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code which will cause a command to fail. 
.RE
.PP

.SS "\fBpwmd_status_cb_t\fP"
.PP
The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_STATUS_DATA\fP. 
.br
\fIline\fP The status message line received from the server. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code which will cause a command to fail. 
.RE
.PP

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBpwmd_async_t\fP"
.PP
The return code of \fBpwmd_process()\fP which is used for all asynchronous commands. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIASYNC_INIT \fP\fP
.PP
\fBFor internal use only.\fP
.RS 4
.RE
.PP

.TP
\fB\fIASYNC_PROCESS \fP\fP
\fBpwmd_process()\fP should be called again. 
.TP
\fB\fIASYNC_DONE \fP\fP
The command has completed. The result code should be checked for an error. 
.SS "enum \fBpwmd_ip_version_t\fP"
.PP
The value of the option \fBPWMD_OPTION_IP_VERSION\fP which is set with \fBpwmd_setopt()\fP. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIPWMD_IP_ANY \fP\fP
Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. 
.TP
\fB\fIPWMD_IPV4 \fP\fP
Only try IPv4. 
.TP
\fB\fIPWMD_IPV6 \fP\fP
Only try IPv6. 
.SS "enum \fBpwmd_option_t\fP"
.PP
libpwmd options which are set with \fBpwmd_setopt()\fP.
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP

.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIPWMD_OPTION_PASSPHRASE_CB \fP\fP
A custom passphrase retrieval function which, when set, will be used instead of \fBpinentry(1)\fP. This function will not be used when the passphrase is cached on the server or the file is a new one. The value of this option should be a \fBpwmd_passphrase_cb_t\fP.
.PP
\fBNote:\fP
.RS 4
An empty string as the passphrase is allowed. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
User supplied data which is passed to the custom passphrase function. 
.TP
\fB\fIPWMD_OPTION_PASSPHRASE \fP\fP
A string to use as the passphrase when doing an open or save. When not NULL, this option has precedence over \fBPWMD_OPTION_PASSPHRASE_CB\fP.
.PP
\fBNote:\fP
.RS 4
An empty string as the passphrase is allowed. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
An integer value that specifies the number of tries before \fBpinentry(1)\fP will give up when opening a file with the wrong supplied passphrase. The default is 3.
.PP
\fBNote:\fP
.RS 4
This option has no effect when trying to save a file. The user must either cancel the pinentry causing the save to fail or enter the correct passphrase during passphrase confirmation. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
A character string value which specifies the full path of the \fBpinentry(1)\fP binary. For the local \fBpinentry(1)\fP method, the default is specified at compile time.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
A value which specifies the full path to the tty that \fBpinentry(1)\fP will use to prompt on. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TERM \fP\fP
A value which specifies the terminal type (e.g., vt100) that \fBpinentry(1)\fP will use when no X11 display is available.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP
A value which specifies the X11 display that \fBpinentry(1)\fP will use.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TITLE \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_PROMPT \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window.  
.TP
\fB\fIPWMD_OPTION_PINENTRY_DESC \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window.  
.TP
\fB\fIPWMD_OPTION_PINENTRY_LC_CTYPE \fP\fP
For \fBpinentry(1)\fP localization. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_LC_MESSAGES \fP\fP
For \fBpinentry(1)\fP localization.  
.TP
\fB\fIPWMD_OPTION_PINENTRY_TIMEOUT \fP\fP
An integer value that specifies the number of seconds \fBpinentry(1)\fP will wait for input before timing out and aborting the current command. If 0, then no timeout will be used. The default is 30. 
.TP
\fB\fIPWMD_OPTION_STATUS_CB \fP\fP
A function of type \fBpwmd_status_cb_t\fP that will process status messages received from the pwmd server. 
.TP
\fB\fIPWMD_OPTION_STATUS_DATA \fP\fP
A user data pointer which is passed to the status message function. 
.TP
\fB\fIPWMD_OPTION_IP_VERSION \fP\fP
The IP version of type \fBpwmd_ip_version_t\fP that \fBpwmd_ssh_connect()\fP and \fBpwmd_ssh_connect_async()\fP will use when connecting to the remote pwmd server.
.PP
\fBNote:\fP
.RS 4
This option must be set before a connection is made when not the default. 
.RE
.PP

.SS "enum \fBpwmd_socket_t\fP"
.PP
For use with \fBpwmd_socket_type()\fP. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIPWMD_SOCKET_UDS \fP\fP
A UNIX domain socket. 
.TP
\fB\fIPWMD_SOCKET_SSH \fP\fP
An SSH connection over a TCP socket. 
.SH "Function Documentation"
.PP 
.SS "void* pwmd_calloc (size_t nmemb, size_t size)"
.PP
A wrapper around calloc(). 
.PP
Like calloc(), but lets libpwmd keep track of the pointer.
.PP
\fBParameters:\fP
.RS 4
\fInmemb\fP The number of elements to allocate. 
.br
\fIsize\fP The number of bytes to allocate. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
calloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "void pwmd_close (\fBpwm_t\fP * pwm)"
.PP
Close a handle. 
.PP
This will close the connection to a pwmd server and free any resources associated with it.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturns:\fP
.RS 4
Nothing. 
.RE
.PP

.SS "gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, const char * cmd,  ...)"
.PP
Send a command to the pwmd server. 
.PP
Sends a command to the pwmd server. You should avoid sending the BYE command here because the assuan context will be freed and bad things will happen. Use \fBpwmd_close()\fP instead. For commands that use an INQUIRE to send data to the server (STORE and IMPORT), \fBpwmd_inquire()\fP should be used and not this function.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP. Note that not all commands return a result. 
.br
\fIcmd\fP The command to send. 
.br
\fI...\fP The arguments to \fIcmd\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, const char * cmd, va_list ap)"
.PP
Send a command to the pwmd server. 
.PP
Like \fBpwmd_command()\fP but uses an argument pointer instead.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP. Note that not all commands return a result. 
.br
\fIcmd\fP The command to send. 
.br
\fIap\fP The arguments to \fIcmd\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)"
.PP
Connect to a local pwmd server. 
.PP
Connects to a local unix domain socket.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIpath\fP The socket path to connect to. If NULL, then a default of \fI'~/.pwmd/socket'\fP will be used. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_ssh_connect()\fP, \fBpwmd_ssh_connect_async()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_connect_url (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection by parsing a URL. 
.PP
This allows for connecting to a pwmd server by parsing the given URL string. Whether the connection is to a remote or local server depends on the contents: 
.PP
.nf
 socket://[path/to/local/socket]

 or

 ssh[46]://[username@]hostname[:port],identity,known_hosts

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a socket://.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIurl\fP The string to parse. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_socket_type()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection asynchronously by parsing a URL. 
.PP
This allows for connecting to a pwmd server by parsing the given URL string. Whether the connection is to a remote or local server depends on the contents: 
.PP
.nf
 socket://[path/to/local/socket]

 or

 ssh[46]://[username@]hostname[:port],identity,known_hosts

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a socket://.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIurl\fP The string to parse. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_socket_type()\fP 
.RE
.PP

.SS "void pwmd_free (void * ptr)"
.PP
Free a previously allocated pointer. 
.PP
Use this function to free resources allocated by the other libpwmd memory functions. Do not use it to free allocations not made by the other libpwmd memory allocators.
.PP
The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it.
.PP
\fBParameters:\fP
.RS 4
\fIptr\fP The pointer to deallocate. 
.RE
.PP
\fBReturns:\fP
.RS 4
Nothing. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_process()\fP, \fBpwmd_command()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, pwmd_fd_t * fds, int * n_fds)"
.PP
Get the associated file descriptor(s) for a handle. 
.PP
This function lets the application poll the available file descriptors for the specified handle. It should be called after each asynchronous function call and after each call to \fBpwmd_process()\fP since the polled file descriptors may have been closed since the previous call.
.PP
After returning, \fIn_fds\fP is set to the number of available file descriptors which are stored in \fIfds\fP. The .flags member of \fBpwmd_fd_t\fP specifies what can be monitored and is a bitmask of \fBPWMD_FD_READABLE\fP and \fBPWMD_FD_WRITABLE\fP. When ready, \fBpwmd_process()\fP should be called.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfds\fP Set to the file descriptor(s) of the associated handle. 
.br
\fIn_fds\fP Initially the size of \fIfds\fP then updated to the number of available file descriptors which are stored in \fIfds\fP. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP on success or an error code. 
.br
\fIGPG_ERR_ERANGE\fP There are more file descriptors than the amount specified in \fIn_fds\fP. \fIfds\fP and \fIn_fds\fP are still usable though. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)"
.PP
Retrieve a remote SSH host key. 
.PP
This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to. 
.br
\fIport\fP The port or a default if set to -1. 
.br
\fIresult\fP The SHA1 sum of the server host key which must be freed with \fBpwmd_free()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey_async()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)"
.PP
Retrieve a remote SSH host key asynchronously. 
.PP
This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to. 
.br
\fIport\fP The port or a default if set to -1. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_init (void)"
.PP
Initialize the library. 
.PP
This function must be the first function called in the library before any others. It sets up internationalization among other things.
.PP
\fBReturns:\fP
.RS 4
0 Success. 
.RE
.PP

.SS "gpg_error_t pwmd_inquire (\fBpwm_t\fP * pwm, const char * cmd, \fBpwmd_inquire_cb_t\fP func, void * user)"
.PP
Send data to a pwmd server. 
.PP
This lets commands that use an INQUIRE (STORE and IMPORT) send the data to the server. Use this function rather than \fBpwmd_command()\fP for these pwmd commands.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIcmd\fP The command (without arguments) to send that uses an INQUIRE. 
.br
\fIfunc\fP A callback function which sets the data to be sent. 
.br
\fIuser\fP A user data pointer passed to the callback function \fIfunc\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_inquire_cb_t\fP 
.RE
.PP

.SS "void* pwmd_malloc (size_t size)"
.PP
A wrapper around malloc. 
.PP
Like malloc(), but lets libpwmd keep track of the pointer.
.PP
\fBParameters:\fP
.RS 4
\fIsize\fP The number of bytes to allocate. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
malloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "\fBpwm_t\fP* pwmd_new (const char * name)"
.PP
Creates a new handle. 
.PP
Creates a new handle for use with the other functions.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP If not NULL, the name of the application. The application name is sent to the pwmd server after successfully connecting.
.br
\fIname\fP The application name or NULL. 
.RE
.PP
\fBReturns:\fP
.RS 4
a new handle or NULL if there was not enough memory. 
.RE
.PP

.SS "gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server. 
.PP
This will send the OPEN command to the server.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server using a local pinentry. 
.PP
This will send the OPEN command to the server like \fBpwmd_open()\fP but will use the local pinentry and not pwmd's pinentry.
.PP
\fBNote:\fP
.RS 4
This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server asynchronously. 
.PP
This will send the OPEN command to the pwmd server. The difference from \fBpwmd_open()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server asynchronously (fork method). 
.PP
This will send the OPEN command to the pwmd server. The difference from \fBpwmd_open()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
The difference from \fBpwmd_open_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBNote:\fP
.RS 4
This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)"
.PP
Check for a unparsed buffered line. 
.PP
A buffered line is a line that was read from the server but has not yet been processed. This function determines if there is such a line.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP if there is a pending line. 
.br
\fIGPG_ERR_NO_DATA\fP if there is no pending line. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP 
.RE
.PP

.SS "\fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)"
.PP
Process an asynchronous function. 
.PP
After an asynchronous function has been called and has returned successfully, this function must be called to process the command and retrieve the result or return value.
.PP
This function may also be called when not in a command to check for pending status messages sent from the server or to process a pending line.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIrc\fP Set to the return code of the original command after ASYNC_DONE has been returned. This value must be checked to determine if the command succeeded. 
.br
\fIresult\fP Set to the result of the command when \fIrc\fP is 0. Note that not all commands return a result. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIASYNC_DONE\fP The command has completed. \fIrc\fP should be checked to determine if the command was successful or not. 
.br
\fIASYNC_PROCESS\fP The command is still running and this function should be called again. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_fds()\fP, \fBpwmd_pending_line()\fP 
.RE
.PP

.SS "void* pwmd_realloc (void * ptr, size_t size)"
.PP
A wrapper around realloc(). 
.PP
Like realloc(), but lets libpwmd keep track of the pointer. Note that this function will try and allocate the entire \fIsize\fP before freeing the original pointer and returning the new one.
.PP
\fBParameters:\fP
.RS 4
\fIptr\fP The pointer to reallocate. 
.br
\fIsize\fP The new number of bytes to allocate. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
realloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_save (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server. 
.PP
This will send the SAVE command.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server using the local pinentry. 
.PP
This will send the SAVE command like \fBpwmd_save()\fP but will use a local pinentry and not pwmd's pinentry.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)"
.PP
Save changes to a file on the pwmd server asynchronously. 
.PP
This will send the SAVE command to the pwmd server. The difference from \fBpwmd_save()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server asynchronously (fork method). 
.PP
This will send the SAVE command to the pwmd server. The difference from \fBpwmd_save()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
The difference from \fBpwmd_save_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt,  ...)"
.PP
Set handle options. 
.PP
See \fBpwmd_option_t\fP for option specific details.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIopt\fP The option. 
.br
\fI...\fP The option value. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "gpg_error_t pwmd_socket_type (\fBpwm_t\fP * pwm, \fBpwmd_socket_t\fP * type)"
.PP
The type of connection a handle has. 
.PP
Useful when you want to know what kind of connection a handle has.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fItype\fP The type of socket. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_connect_url()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_ssh_connect (\fBpwm_t\fP * pwm, const char * host, int port, const char * identity, const char * user, const char * known_hosts)"
.PP
Establish a remote connection to a pwmd server. 
.PP
Connects to a pwmd server over an SSH channel.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to. 
.br
\fIport\fP The port or -1 for the default. 
.br
\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL then invoking username will be used. 
.br
\fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format which may be obtained with \fBpwmd_get_hostkey()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_ssh_connect_async()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBSSH Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_ssh_connect_async (\fBpwm_t\fP * pwm, const char * host, int port, const char * identity, const char * user, const char * known_hosts)"
.PP
Establish a remote connection to a pwmd server asynchronously. 
.PP
This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DNS lookups or while connecting.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to. 
.br
\fIport\fP The port or -1 for the default. 
.br
\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used. 
.br
\fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format which may be obtained with \fBpwmd_get_hostkey()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBSSH Details\fP 
.RE
.PP

.SS "char* pwmd_strdup (const char * str)"
.PP
A wrapper around strdup(). 
.PP
Like strdup(), but lets libpwmd keep track of the pointer.
.PP
\fBParameters:\fP
.RS 4
\fIstr\fP The string to duplicate. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated character pointer or NULL if there wasn't enough memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
strdup(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "char* pwmd_strdup_printf (const char * fmt,  ...)"
.PP
Duplicate a formatted string. 
.PP
Like sprintf() but returns an allocated string.
.PP
\fBParameters:\fP
.RS 4
\fIfmt\fP The formatted string. 
.br
\fI...\fP Any format arguments to the string. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated character pointer or NULL if there wasn't enough memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_free()\fP 
.RE
.PP

.SS "const char* pwmd_strerror (gpg_error_t code)"
.PP
Return a description of an error code. 
.PP
\fBParameters:\fP
.RS 4
\fIcode\fP The error code to describe. 
.RE
.PP
\fBReturns:\fP
.RS 4
A character description of the error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_strerror_r()\fP 
.RE
.PP

.SS "int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)"
.PP
Return a description of an error code (thread-safe). 
.PP
This is a thread-safe version of \fBpwmd_strerror()\fP.
.PP
\fBParameters:\fP
.RS 4
\fIcode\fP The error code to describe. 
.br
\fIbuf\fP An allocated buffer to hold the error description. 
.br
\fIsize\fP The size of the allocated buffer \fIbuf\fP.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP Success. 
.br
\fIERANGE\fP \fIsize\fP was not large enough to hold the entire description and \fIbuf\fP is set to the truncated error string. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libpwmd from the source code.