From 9ce7eafa8c0b448533a7165bbe18b1faa8ba713f Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Wed, 26 May 2010 18:36:47 -0400 Subject: [PATCH] Updated the manual page. --- doc/libpwmd.3 | 409 ++++++++++++++++++++++--------------------------------- src/libpwmd.h.in | 125 +++++++++-------- 2 files changed, 234 insertions(+), 300 deletions(-) diff --git a/doc/libpwmd.3 b/doc/libpwmd.3 index 43e549d4..6e7e5779 100644 --- a/doc/libpwmd.3 +++ b/doc/libpwmd.3 @@ -1,4 +1,4 @@ -.TH "libpwmd.h" 3 "5 Jul 2009" "Version 6.0.2" "libpwmd" \" -*- nroff -*- +.TH "libpwmd.h" 3 "26 May 2010" "Version 6.0.3" "libpwmd" \" -*- nroff -*- .ad l .nh .SH NAME @@ -81,48 +81,10 @@ libpwmd uses libgpg-error for all error codes. Some are user defined GPG_ERR_USE .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. +libgpg-error normally returns an error code as a bitmask of an error source and the actual error code. 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 - #include - #include - - 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 @@ -137,13 +99,25 @@ The following example will list the element tree of the data file specified in t .in +1c .ti -1c -.RI "#define \fBLIBPWMD_VERSION\fP 0x602" +.RI "#define \fBLIBPWMD_VERSION\fP 0x603" +.br +.ti -1c +.RI "#define \fBLIBPWMD_VERSION_MAJOR\fP 6" +.br +.ti -1c +.RI "#define \fBLIBPWMD_VERSION_MINOR\fP 0" +.br +.ti -1c +.RI "#define \fBLIBPWMD_VERSION_PATCH\fP 3" +.br +.ti -1c +.RI "#define \fBLIBPWMD_VERSION_STR\fP '6.0.3-git'" .br .ti -1c -.RI "#define \fBPWMD_FD_READABLE\fP" +.RI "#define \fBPWMD_FD_READABLE\fP 0x01" .br .ti -1c -.RI "#define \fBPWMD_FD_WRITABLE\fP" +.RI "#define \fBPWMD_FD_WRITABLE\fP 0x02" .br .ti -1c .RI "#define \fBEPWMD_NO_FILE\fP" @@ -200,142 +174,160 @@ The following example will list the element tree of the data file specified in t .in +1c .ti -1c -.RI "gpg_error_t \fBpwmd_init\fP (void)" +.RI "LIBPWMD_API const char * \fBpwmd_version\fP ()" .br .ti -1c -.RI "\fBpwm_t\fP * \fBpwmd_new\fP (const char *name)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_init\fP (void)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)" +.RI "LIBPWMD_API \fBpwm_t\fP * \fBpwmd_new\fP (const char *name)" .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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)" .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)" +.RI "LIBPWMD_API 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_connect_url\fP (\fBpwm_t\fP *pwm, const char *url)" +.RI "LIBPWMD_API 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_async\fP (\fBpwm_t\fP *pwm, const char *url)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect_url\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)" +.RI "LIBPWMD_API 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_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)" +.RI "LIBPWMD_API 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_fds\fP (\fBpwm_t\fP *pwm, \fBpwmd_fd_t\fP *fds, int *n_fds)" +.RI "LIBPWMD_API 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_pending_line\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_get_fds\fP (\fBpwm_t\fP *pwm, \fBpwmd_fd_t\fP *fds, int *n_fds)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,...)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, \fBpwmd_pinentry_t\fP which)" +.RI "LIBPWMD_API 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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, \fBpwmd_pinentry_t\fP which)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_open\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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_open2\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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_open_async2\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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API \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_save2\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)" .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)" +.RI "LIBPWMD_API 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_disconnect\fP (\fBpwm_t\fP *pwm)" +.RI "LIBPWMD_API 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)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\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)" +.RI "LIBPWMD_API void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)" .br .ti -1c -.RI "void \fBpwmd_free\fP (void *ptr)" +.RI "LIBPWMD_API gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)" .br .ti -1c -.RI "void * \fBpwmd_malloc\fP (size_t size)" +.RI "LIBPWMD_API void \fBpwmd_free\fP (void *ptr)" .br .ti -1c -.RI "void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)" +.RI "LIBPWMD_API void * \fBpwmd_malloc\fP (size_t size)" .br .ti -1c -.RI "void * \fBpwmd_realloc\fP (void *ptr, size_t size)" +.RI "LIBPWMD_API void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)" .br .ti -1c -.RI "char * \fBpwmd_strdup\fP (const char *str)" +.RI "LIBPWMD_API void * \fBpwmd_realloc\fP (void *ptr, size_t size)" .br .ti -1c -.RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)" +.RI "LIBPWMD_API char * \fBpwmd_strdup\fP (const char *str)" .br .ti -1c -.RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)" +.RI "LIBPWMD_API char * \fBpwmd_strdup_printf\fP (const char *fmt,...)" .br .ti -1c -.RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)" +.RI "LIBPWMD_API const char * \fBpwmd_strerror\fP (gpg_error_t code)" +.br +.ti -1c +.RI "LIBPWMD_API int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)" .br .in -1c .SH "Constant Details" .PP .SS "#define EPWMD_FILE_MODIFIED" .PP -The data file was modified either externally or by another client while trying to process a command. +The data file has been modified. Rather than process the next command this error is returned to prevent overwriting new data which may have been saved by another client. .SS "#define EPWMD_LIBXML_ERROR" .PP -An XML parse or other libxml2 error occurred. +libxml2 error. This can be a memory allocation error or a parse error. The details of the error cannot be obtained with libpwmd. You'd have to connect to the pwmd socket and do the command directly to get the actual error. +.SS "#define EPWMD_MAX" +.PP +libgpg-error error code offset. If you use your own libgpg-error codes then this should be the base of them. .SS "#define EPWMD_NO_FILE" .PP -A command required an open file but no file has yet been opened. -.SS "#define LIBPWMD_VERSION 0x602" +No data file has been opened. Some commands don't require an open data file but most do. +.SS "#define LIBPWMD_VERSION 0x603" +.PP +Version information. The version of this library. +.SS "#define LIBPWMD_VERSION_MAJOR 6" .PP -The version of this library. -.SS "#define PWMD_FD_READABLE" +Version information. The major release number of this library. +.SS "#define LIBPWMD_VERSION_MINOR 0" .PP -Set when the file descriptor is readable. -.SS "#define PWMD_FD_WRITABLE" +Version information. The minor release number of this library. +.SS "#define LIBPWMD_VERSION_PATCH 3" .PP -Set when the file descriptor is writable. +Version information. The patch level of this library. +.SS "#define LIBPWMD_VERSION_STR '6.0.3-git'" +.PP +Version information. A string representation of the version of this library. +.SS "#define PWMD_FD_READABLE 0x01" +.PP +For use with \fBpwmd_get_fds()\fP. Set when the file descriptor is readable. +.SS "#define PWMD_FD_WRITABLE 0x02" +.PP +For use with \fBpwmd_get_fds()\fP. Set when the file descriptor is writable. .SH "Typedef Details" .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. +libpwmd handle. 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 server 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. +Send data to the pwmd server. 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 server 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 @@ -367,7 +359,7 @@ The sent data is processed line-per-line. The line is either newline terminated .SS "\fBpwmd_knownhost_cb_t\fP" .PP -When \fBPWMD_OPTION_KNOWNHOST_CB\fP is set and a the current connections host key was not found in the known hosts file, then this callback function can be used to confirm the addition of the new host key to the known_hosts file. +Verify a remote SSH connection. When \fBPWMD_OPTION_KNOWNHOST_CB\fP is set and a the current connections host key was not found in the known hosts file, then this callback function can be used to confirm the addition of the new host key to the known_hosts file. .PP \fBParameters:\fP .RS 4 @@ -400,7 +392,7 @@ If the known hosts file cannot be modified do to filesystem restrictions when tr .SS "\fBpwmd_passphrase_cb_t\fP" .PP -The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwmd_setopt()\fP. +Custom passphrase retrieval function. The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwmd_setopt()\fP. .PP \fBParameters:\fP .RS 4 @@ -417,7 +409,7 @@ The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwm .SS "\fBpwmd_status_cb_t\fP" .PP -The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP. +Process status messages. The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP. .PP \fBParameters:\fP .RS 4 @@ -436,7 +428,7 @@ The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_se .PP .SS "enum \fBpwmd_async_t\fP" .PP -The return code of \fBpwmd_process()\fP which is used for all asynchronous commands. +Asynchronous return value. The return code of \fBpwmd_process()\fP which is used for all asynchronous commands. .PP \fBEnumerator: \fP .in +1c @@ -456,7 +448,7 @@ The return code of \fBpwmd_process()\fP which is used for all asynchronous comma 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. +IP protocol version for remote SSH connections. The value of the option \fBPWMD_OPTION_IP_VERSION\fP which is set with \fBpwmd_setopt()\fP. .PP \fBEnumerator: \fP .in +1c @@ -471,7 +463,7 @@ Only try IPv4. Only try IPv6. .SS "enum \fBpwmd_option_t\fP" .PP -libpwmd options which are set with \fBpwmd_setopt()\fP. +libpwmd options. Options are set with \fBpwmd_setopt()\fP. .PP \fBNote:\fP .RS 4 @@ -628,7 +620,7 @@ This is a libpwmd feature. pwmd itself does not send XFER status messages during .SS "enum \fBpwmd_pinentry_t\fP" .PP -For use with \fBpwmd_getpin()\fP. +Local pinentry commands and not pwmd pinentry. For use with \fBpwmd_getpin()\fP. .PP \fBEnumerator: \fP .in +1c @@ -655,7 +647,7 @@ For the default or user defined string set with \fBPWMD_OPTION_PINENTRY_DESC\fP. To terminate the pinentry process created with \fBpwmd_getpin()\fP. .SS "enum \fBpwmd_socket_t\fP" .PP -For use with \fBpwmd_socket_type()\fP. +The type of socket a handle is connected to. For use with \fBpwmd_socket_type()\fP. .PP \fBEnumerator: \fP .in +1c @@ -667,11 +659,9 @@ A local domain socket. An SSH connection over a TCP socket. .SH "Function Details" .PP -.SS "void* pwmd_calloc (size_t nmemb, size_t size)" -.PP -A wrapper around calloc(). +.SS "LIBPWMD_API void* pwmd_calloc (size_t nmemb, size_t size)" .PP -Like calloc(), but lets libpwmd keep track of the pointer. +A wrapper around calloc(). Like calloc(), but lets libpwmd keep track of the pointer. .PP \fBParameters:\fP .RS 4 @@ -691,11 +681,9 @@ calloc(3), \fBpwmd_free()\fP .RE .PP -.SS "void pwmd_close (\fBpwm_t\fP * pwm)" +.SS "LIBPWMD_API 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. +Close a handle. This will close the connection to a pwmd server and free any resources associated with it. .PP \fBParameters:\fP .RS 4 @@ -713,11 +701,9 @@ 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. +.SS "LIBPWMD_API gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, const char * cmd, ...)" .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 must be used and not this function. +Send a command to the pwmd server. 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 must be used and not this function. .PP \fBParameters:\fP .RS 4 @@ -739,11 +725,9 @@ Not all commands return a result. .RE .PP -.SS "gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, const char * cmd, va_list ap)" +.SS "LIBPWMD_API 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. +Send a command to the pwmd server. Like \fBpwmd_command()\fP but uses an argument pointer instead. .PP \fBParameters:\fP .RS 4 @@ -767,11 +751,9 @@ Not all commands return a result. .RE .PP -.SS "gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)" -.PP -Connect to a local pwmd server. +.SS "LIBPWMD_API gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)" .PP -Connects to a local unix domain socket. +Connect to a local pwmd server. Connects to a local unix domain socket. .PP \fBParameters:\fP .RS 4 @@ -796,11 +778,9 @@ When the first character of a filename parameter is a tilde (~), it will be expa .RE .PP -.SS "gpg_error_t pwmd_connect_url (\fBpwm_t\fP * pwm, const char * url)" +.SS "LIBPWMD_API 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: +Establish a connection by parsing a URL. 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 file://[path/to/local/socket] @@ -837,11 +817,9 @@ When the first character of a filename parameter is a tilde (~), it will be expa .RE .PP -.SS "gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * url)" -.PP -Establish a connection by parsing a URL (asynchronously). +.SS "LIBPWMD_API gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * 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: +Establish a connection by parsing a URL (asynchronously). 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 file://[path/to/local/socket] @@ -880,11 +858,9 @@ When the first character of a filename parameter is a tilde (~), it will be expa .RE .PP -.SS "gpg_error_t pwmd_disconnect (\fBpwm_t\fP * pwm)" -.PP -Close a connection to the pwmd server. +.SS "LIBPWMD_API gpg_error_t pwmd_disconnect (\fBpwm_t\fP * pwm)" .PP -This will close the connection but keep any previously set options for the specified handle. +Close a connection to the pwmd server. This will close the connection but keep any previously set options for the specified handle. .PP \fBParameters:\fP .RS 4 @@ -902,11 +878,9 @@ This will close the connection but keep any previously set options for the speci .RE .PP -.SS "void pwmd_free (void * ptr)" +.SS "LIBPWMD_API 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 made by other allocators. +Free a previously allocated pointer. Use this function to free resources allocated by the other libpwmd memory functions. Do not use it to free allocations made by other 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 @@ -926,11 +900,9 @@ Nothing. .RE .PP -.SS "gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, \fBpwmd_fd_t\fP * fds, int * n_fds)" -.PP -Get the associated file descriptor(s) for a handle. +.SS "LIBPWMD_API gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, \fBpwmd_fd_t\fP * fds, int * n_fds)" .PP -This function lets the application manually 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. +Get the associated file descriptor(s) for a handle. This function lets the application manually 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 @@ -956,11 +928,9 @@ After returning, \fIn_fds\fP is set to the number of available file descriptors .RE .PP -.SS "gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)" +.SS "LIBPWMD_API gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)" .PP -Retrieve a remote SSH public 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. +Retrieve a remote SSH public host key. 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 @@ -989,11 +959,9 @@ This key is needed for host verification of the remote pwmd server. You should b .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). +.SS "LIBPWMD_API gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)" .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. +Retrieve a remote SSH host key (asynchronously). 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 @@ -1022,11 +990,9 @@ This key is needed for host verification of the remote pwmd server. You should b .RE .PP -.SS "gpg_error_t pwmd_getpin (\fBpwm_t\fP * pwm, const char * filename, char ** result, \fBpwmd_pinentry_t\fP which)" +.SS "LIBPWMD_API gpg_error_t pwmd_getpin (\fBpwm_t\fP * pwm, const char * filename, char ** result, \fBpwmd_pinentry_t\fP which)" .PP -Launch a local pinentry. -.PP -Does not send any command to the server. Maybe useful if a passphrase is needed before opening a file over a remote connection. This passphrase can then be set with \fBpwmd_setopt()\fP. +Launch a local pinentry. Does not send any command to the server. Maybe useful if a passphrase is needed before opening a file over a remote connection. This passphrase can then be set with \fBpwmd_setopt()\fP. .PP This function may also be used to display a user confirmation dialog with pinentry when \fIwhich\fP is \fBPWMD_PINENTRY_CONFIRM\fP. The text to prompt with is set with \fBPWMD_OPTION_PINENTRY_TITLE\fP. .PP @@ -1047,11 +1013,9 @@ This function may also be used to display a user confirmation dialog with pinent .RE .PP -.SS "gpg_error_t pwmd_init (void)" -.PP -Initialize the library. +.SS "LIBPWMD_API gpg_error_t pwmd_init (void)" .PP -This function must be the first function called in the library before any others. It sets up the memory allocators and internationalization among other things. +Initialize the library. This function must be the first function called in the library before any others. It sets up the memory allocators and internationalization among other things. .PP \fBReturns:\fP .RS 4 @@ -1059,11 +1023,9 @@ This function must be the first function called in the library before any others .RE .PP -.SS "gpg_error_t pwmd_inquire (\fBpwm_t\fP * pwm, const char * cmd, \fBpwmd_inquire_cb_t\fP func, void * user)" +.SS "LIBPWMD_API 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. +Send data to a pwmd server. 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 @@ -1087,11 +1049,9 @@ This lets commands that use an INQUIRE (STORE and IMPORT) send the data to the s .RE .PP -.SS "void* pwmd_malloc (size_t size)" -.PP -A wrapper around malloc. +.SS "LIBPWMD_API void* pwmd_malloc (size_t size)" .PP -Like malloc(), but lets libpwmd keep track of the pointer. +A wrapper around malloc. Like malloc(), but lets libpwmd keep track of the pointer. .PP \fBParameters:\fP .RS 4 @@ -1109,11 +1069,9 @@ malloc(3), \fBpwmd_free()\fP .RE .PP -.SS "\fBpwm_t\fP* pwmd_new (const char * name)" +.SS "LIBPWMD_API \fBpwm_t\fP* pwmd_new (const char * name)" .PP -Creates a new handle. -.PP -Creates a new handle for use with the other functions. +Creates a new handle. Creates a new handle for use with the other functions. .PP \fBParameters:\fP .RS 4 @@ -1126,11 +1084,9 @@ 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. +.SS "LIBPWMD_API gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)" .PP -This will send the OPEN command to the server. +Open a file on the pwmd server. This will send the OPEN command to the server. .PP \fBParameters:\fP .RS 4 @@ -1150,11 +1106,9 @@ This will send the OPEN command to the server. .RE .PP -.SS "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)" +.SS "LIBPWMD_API 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. +Open a file on the pwmd server using a local pinentry. 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 @@ -1186,11 +1140,9 @@ This pinentry method is not thread safe. It needs to set a couple of global vari .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). +.SS "LIBPWMD_API gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)" .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. +Open a file on the pwmd server (asynchronously). 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 @@ -1212,11 +1164,9 @@ This will send the OPEN command to the pwmd server. The difference from \fBpwmd_ .RE .PP -.SS "gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)" +.SS "LIBPWMD_API 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 is kind of a hybrid of \fBpwmd_open2()\fP and \fBpwmd_open_async()\fP. It will use the local pinentry asynchronously and also do the OPEN command asynchronously. +Open a file on the pwmd server asynchronously (fork method). This is kind of a hybrid of \fBpwmd_open2()\fP and \fBpwmd_open_async()\fP. It will use the local pinentry asynchronously and also do the OPEN command asynchronously. .PP \fBpwmd_process()\fP should be called until the command completes. .PP @@ -1243,11 +1193,9 @@ This function will catch SIGALRM during the lifetime of the pinentry process and .RE .PP -.SS "gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)" -.PP -Check for a unparsed buffered line. +.SS "LIBPWMD_API gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)" .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. +Check for a unparsed buffered line. 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 @@ -1267,11 +1215,9 @@ A buffered line is a line that was read from the server but has not yet been pro .RE .PP -.SS "\fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)" -.PP -Process an asynchronous function. +.SS "LIBPWMD_API \fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)" .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 and return value. +Process an asynchronous function. After an asynchronous function has been called and has returned successfully, this function must be called to process the command and retrieve the result and 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 @@ -1297,11 +1243,9 @@ This function may also be called when not in a command to check for pending stat .RE .PP -.SS "void* pwmd_realloc (void * ptr, size_t size)" +.SS "LIBPWMD_API void* pwmd_realloc (void * ptr, size_t size)" .PP -A wrapper around realloc(). -.PP -Like realloc(), but lets libpwmd keep track of the pointer. +A wrapper around realloc(). Like realloc(), but lets libpwmd keep track of the pointer. .PP \fBNote:\fP .RS 4 @@ -1326,11 +1270,9 @@ 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. +.SS "LIBPWMD_API gpg_error_t pwmd_save (\fBpwm_t\fP * pwm)" .PP -This will send the SAVE command. +Save a file on the pwmd server. This will send the SAVE command. .PP \fBParameters:\fP .RS 4 @@ -1348,11 +1290,9 @@ This will send the SAVE command. .RE .PP -.SS "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)" +.SS "LIBPWMD_API 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. +Save a file on the pwmd server using the local pinentry. 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 @@ -1370,11 +1310,9 @@ This will send the SAVE command like \fBpwmd_save()\fP but will use a local pine .RE .PP -.SS "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)" -.PP -Save changes to a file on the pwmd server (asynchronously). +.SS "LIBPWMD_API gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)" .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. +Save changes to a file on the pwmd server (asynchronously). 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 @@ -1394,11 +1332,9 @@ This will send the SAVE command to the pwmd server. The difference from \fBpwmd_ .RE .PP -.SS "gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)" +.SS "LIBPWMD_API gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)" .PP -Save a file on the pwmd server asynchronously (fork method). -.PP -This is kind of a hybrid of \fBpwmd_save2()\fP and \fBpwmd_save_async()\fP. It will use the local pinentry asynchronously and also do the SAVE command asynchronously. +Save a file on the pwmd server asynchronously (fork method). This is kind of a hybrid of \fBpwmd_save2()\fP and \fBpwmd_save_async()\fP. It will use the local pinentry asynchronously and also do the SAVE command asynchronously. .PP \fBpwmd_process()\fP should be called until the command completes. .PP @@ -1418,11 +1354,9 @@ This is kind of a hybrid of \fBpwmd_save2()\fP and \fBpwmd_save_async()\fP. It w .RE .PP -.SS "gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt, ...)" -.PP -Set handle options. +.SS "LIBPWMD_API gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt, ...)" .PP -See \fBpwmd_option_t\fP for option specific details. +Set handle options. See \fBpwmd_option_t\fP for option specific details. .PP \fBParameters:\fP .RS 4 @@ -1437,11 +1371,9 @@ See \fBpwmd_option_t\fP for option specific details. .RE .PP -.SS "gpg_error_t pwmd_socket_type (\fBpwm_t\fP * pwm, \fBpwmd_socket_t\fP * type)" +.SS "LIBPWMD_API 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. +The type of connection a handle has. Useful when you want to know what kind of connection a handle has. .PP \fBParameters:\fP .RS 4 @@ -1461,11 +1393,9 @@ Useful when you want to know what kind of connection a handle has. .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. +.SS "LIBPWMD_API 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 -Connects to a pwmd server over an SSH channel. +Establish a remote connection to a pwmd server. Connects to a pwmd server over an SSH channel. .PP \fBParameters:\fP .RS 4 @@ -1498,11 +1428,9 @@ When the first character of a filename parameter is a tilde (~), it will be expa .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)" +.SS "LIBPWMD_API 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. +Establish a remote connection to a pwmd server (asynchronously). 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 @@ -1537,11 +1465,9 @@ When the first character of a filename parameter is a tilde (~), it will be expa .RE .PP -.SS "char* pwmd_strdup (const char * str)" -.PP -A wrapper around strdup(). +.SS "LIBPWMD_API char* pwmd_strdup (const char * str)" .PP -Like strdup(), but lets libpwmd keep track of the pointer. +A wrapper around strdup(). Like strdup(), but lets libpwmd keep track of the pointer. .PP \fBParameters:\fP .RS 4 @@ -1559,11 +1485,9 @@ strdup(3), \fBpwmd_free()\fP .RE .PP -.SS "char* pwmd_strdup_printf (const char * fmt, ...)" +.SS "LIBPWMD_API char* pwmd_strdup_printf (const char * fmt, ...)" .PP -Duplicate a formatted string. -.PP -Like \fBsprintf(3)\fP but returns an allocated string. +Duplicate a formatted string. Like \fBsprintf(3)\fP but returns an allocated string. .PP \fBParameters:\fP .RS 4 @@ -1581,11 +1505,9 @@ A newly allocated character pointer or NULL if there wasn't enough memory. .RE .PP -.SS "const char* pwmd_strerror (gpg_error_t code)" -.PP -Return a description of an error code. +.SS "LIBPWMD_API const char* pwmd_strerror (gpg_error_t code)" .PP -\fBParameters:\fP +Return a description of an error code. \fBParameters:\fP .RS 4 \fIcode\fP The error code to describe. .RE @@ -1601,11 +1523,9 @@ A character description of the error code. .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). +.SS "LIBPWMD_API int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)" .PP -This is a thread-safe version of \fBpwmd_strerror()\fP. +Return a description of an error code (thread-safe). This is a thread-safe version of \fBpwmd_strerror()\fP. .PP \fBParameters:\fP .RS 4 @@ -1624,6 +1544,9 @@ This is a thread-safe version of \fBpwmd_strerror()\fP. .RE .PP +.SS "LIBPWMD_API const char* pwmd_version ()" +.PP +Returns this version of libpwmd. As a string. .SH "Author" .PP Generated automatically by Doxygen for libpwmd from the source code. diff --git a/src/libpwmd.h.in b/src/libpwmd.h.in index 49bbb85e..ca61a412 100644 --- a/src/libpwmd.h.in +++ b/src/libpwmd.h.in @@ -118,48 +118,9 @@ * codes can be described by using \ref pwmd_strerror(), or the thread-safe * \ref pwmd_strerror_r(). * - * \note 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. - */ - -/*! \section example Example Client - * - * The following example will list the element tree of the data file specified - * in the first command line argument. - * - * \code - * #include - * #include - * #include - * - * 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); - * } - * \endcode + * \note libgpg-error normally returns an error code as a bitmask of an error + * source and the actual error code. In order to simplify the result codes, + * libpwmd strips any error source from the error code before returning it. */ /*! \file */ @@ -174,22 +135,55 @@ extern "C" { #endif /*! \def LIBPWMD_VERSION + * \brief Version information. * * The version of this library. */ #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_MINOR@@VER_PATCH@ + + +/*! \def LIBPWMD_VERSION_MAJOR + * \brief Version information. + * + * The major release number of this library. + */ #define LIBPWMD_VERSION_MAJOR @VER_MAJOR@ + + +/*! \def LIBPWMD_VERSION_MINOR + * \brief Version information. + * + * The minor release number of this library. + */ #define LIBPWMD_VERSION_MINOR @VER_MINOR@ + + +/*! \def LIBPWMD_VERSION_PATCH + * \brief Version information. + * + * The patch level of this library. + */ #define LIBPWMD_VERSION_PATCH @VER_PATCH@ + + +/*! \def LIBPWMD_VERSION_STR + * \brief Version information. + * + * A string representation of the version of this library. + */ #define LIBPWMD_VERSION_STR @VER_STRING@ -/*! \brief Returns the version of libpwmd. */ +/*! \brief Returns this version of libpwmd. + * + * As a string. + */ LIBPWMD_API const char *pwmd_version(); struct pwm_s; /*! \typedef pwm_t + * \brief libpwmd handle. * * When a handle is mentioned in this documentation it is a pointer of this * type. A new handle is created with \ref pwmd_new(). @@ -198,6 +192,7 @@ typedef struct pwm_s pwm_t; /*! \typedef pwmd_async_t + * \brief Asynchronous return value. * * The return code of \ref pwmd_process() which is used for all asynchronous * commands. @@ -216,6 +211,7 @@ typedef enum { /*! \typedef pwmd_ip_version_t + * \brief IP protocol version for remote SSH connections. * * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref * pwmd_setopt(). @@ -235,7 +231,7 @@ typedef enum { /*! \def PWMD_FD_READABLE - * \hideinitializer + * \brief For use with \ref pwmd_get_fds(). * * Set when the file descriptor is readable. */ @@ -243,16 +239,14 @@ typedef enum { /*! \def PWMD_FD_WRITABLE - * \hideinitializer + * \brief For use with \ref pwmd_get_fds(). * * Set when the file descriptor is writable. */ #define PWMD_FD_WRITABLE 0x02 -/*! - * For use with \ref pwmd_get_fds(). - */ +/*! For use with \ref pwmd_get_fds(). */ typedef struct { /*! The file descriptor. */ int fd; @@ -263,6 +257,7 @@ typedef struct { /*! \typedef pwmd_socket_t + * \brief The type of socket a handle is connected to. * * For use with \ref pwmd_socket_type(). */ @@ -276,6 +271,7 @@ typedef enum { /*! \typedef pwmd_pinentry_t + * \brief Local pinentry commands and not pwmd pinentry. * * For use with \ref pwmd_getpin(). */ @@ -305,6 +301,7 @@ typedef enum { /*! \typedef pwmd_passphrase_cb_t + * \brief Custom passphrase retrieval function. * * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with * \ref pwmd_setopt(). @@ -320,6 +317,7 @@ typedef gpg_error_t (*pwmd_passphrase_cb_t)(void *user, char **passphrase); /*! \typedef pwmd_status_cb_t + * \brief Process status messages. * * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref * pwmd_setopt(). @@ -333,6 +331,7 @@ typedef int (*pwmd_status_cb_t)(void *user, const char *line); /*! \typedef pwmd_inquire_cb_t + * \brief Send data to the pwmd server. * * This is a callback function that gets passed to \ref pwmd_inquire(). It is * used for sending data to the server for commands that need to reply to an @@ -363,6 +362,8 @@ typedef gpg_error_t (*pwmd_inquire_cb_t)(void *user, const char *cmd, gpg_error_t rc, char **data, size_t *len); /*! \typedef pwmd_knownhost_cb_t + * \brief Verify a remote SSH connection. + * * When \ref PWMD_OPTION_KNOWNHOST_CB is set and a the current connections * host key was not found in the known hosts file, then this callback function * can be used to confirm the addition of the new host key to the known_hosts @@ -388,8 +389,9 @@ typedef gpg_error_t (*pwmd_knownhost_cb_t)(void *user, const char *host, const char *key, size_t len); /*! \enum pwmd_option_t + * \brief libpwmd options. * - * libpwmd options which are set with \ref pwmd_setopt(). + * Options are set with \ref pwmd_setopt(). * * \filepath */ @@ -1116,35 +1118,44 @@ LIBPWMD_API char *pwmd_strdup_printf(const char *fmt, ...); /*! \def EPWMD_NO_FILE - * \hideinitializer + * \hideinitializer + * \brief No data file has been opened. * - * A command required an open file but no file has yet been opened. + * Some commands don't require an open data file but most do. */ #define EPWMD_NO_FILE GPG_ERR_USER_1 /*! \def EPWMD_LIBXML_ERROR - * \hideinitializer + * \hideinitializer + * \brief libxml2 error. * - * An XML parse or other libxml2 error occurred. + * This can be a memory allocation error or a parse error. The details of the + * error cannot be obtained with libpwmd. You'd have to connect to the pwmd + * socket and do the command directly to get the actual error. */ #define EPWMD_LIBXML_ERROR GPG_ERR_USER_2 /*! \def EPWMD_FILE_MODIFIED - * \hideinitializer + * \hideinitializer + * \brief The data file has been modified. * - * The data file was modified either externally or by another client while - * trying to process a command. + * Rather than process the next command this error is returned to prevent + * overwriting new data which may have been saved by another client. */ #define EPWMD_FILE_MODIFIED GPG_ERR_USER_3 /*! \def EPWMD_MAX - * \hideinitializer + * \hideinitializer * \if cond1 * \internal * \endif + * \brief libgpg-error error code offset. + * + * If you use your own libgpg-error codes then this should be the base of + * them. */ #define EPWMD_MAX GPG_ERR_USER_4 -- 2.11.4.GIT