1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
3 Copyright (C) 2006-2009 Ben Kibbey <bjk@luxsci.net>
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02110-1301 USA
19 /*! \headerfile libpwmd.h
21 * libpwmd is a library making it easy for applications to use the pwmd
25 /*! \section ssh SSH Details
27 * A remote connection to a pwmd server is possible by using an SSH channel
28 * which spawns a shell and executes a proxy server that connects to the pwmd
29 * local unix domain socket. Authenication is done by using SSH public key
30 * (see \ref ssh-keygen(1)) authentication and verifying the host key against
31 * a local file containing SHA1 hashes of known hosts. It's alot like how the
32 * standard OpenSSH does things only the known_hosts file is in a different
35 * The server hash can be had by using \ref pwmd_get_hostkey() and storing the
36 * result in a file. This file is then used as the \a known_hosts argument to
37 * the SSH connection functions.
39 * Here's an example \ref authorized_keys(5) entry. The hash portion should be
40 * the same as the contents of the \a identity.pub file which is passed as a
41 * parameter to the SSH connection functions:
44 * command="socat gopen:$HOME/.pwmd/socket -" <hash> ...
50 /*! \section pinentry Pinentry Details
52 * \ref pinentry(1) is a program that prompts the user for input which is
53 * normally a passphrase or a confirmation. libpwmd can use this program
54 * either locally (the connection is to a remote server not on this host) or
55 * have the pwmd server use it's pinentry to retrieve a passphrase when
58 * There are a few options that tell pinentry how and where to prompt for a
59 * passphrase. See the \ref pwmd_option_t section for details. These options
60 * are not sent (when using pwmd's pinentry) until the pinentry is needed.
62 * If using a local pinentry by calling \ref pwmd_open2(), \ref pwmd_save2(),
63 * \ref pwmd_open_async2() or pwmd_save_async2(), libpwmd will send the
64 * command "OPTION PINENTRY=0" to the server. This is needed for pinentry
65 * retries (passphrase or confirmation failure). So if you need to change
66 * pinentry methods, then set this option as needed.
68 * Some pinentry options can also be specified in a local configuration file
69 * \a "~/.pwmd/pinentry.conf". These options are initial values for each
70 * invokation and may be changed by setting the appropriate \ref
71 * pwmd_option_t. Each option and value is separated with a '=' on a single
72 * line. Unrecognized options are ignored. Here are the recognized options:
74 * \param PATH The full path to the location of the pinentry binary.
75 * \param DISPLAY The X11 display to use.
76 * \param TTYNAME The full path to the tty that pinentry should prompt on.
77 * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is
80 * \note After establishing an SSH connection, the pwmd pinentry is disabled
81 * because it doesn't currently have a way to use the local display. You must
82 * be careful to either use a local pinentry or set a passphrase manually with
90 /*! \section example Example Client
92 * The following example will list the element tree of the data file specified
93 * in the first command line argument.
97 * #include <libpwmd.h>
101 * pwm_t *pwm = pwmd_new(NULL);
102 * gpg_error_t rc = pwmd_connect(pwm, NULL);
106 * rc = pwmd_open(pwm, argv[1]);
109 * rc = pwmd_command(pwm, &result, "%s", "LIST");
112 * printf("%s", result);
121 * fprintf(stderr, "ERR: %s\n", pwmd_strerror(rc));
132 #include <gpg-error.h>
139 /*! \def LIBPWMD_VERSION
142 * The version of this library.
144 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_COMPAT@@VER_PATCH@
150 * When a handle is mentioned in this documentation it is a pointer of this
151 * type. A new handle is created with \ref pwmd_new().
153 typedef struct pwm_s pwm_t
;
156 /*! \typedef pwmd_async_t
158 * The return code of \ref pwmd_process() which is used for all asynchronous
165 /*! \ref pwmd_process() should be called again. */
168 /*! The command has completed. The result code should be checked for an
174 /*! \typedef pwmd_ip_version_t
176 * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
180 /*! Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. */
183 /*! Only try IPv4. */
186 /*! Only try IPv6. */
191 /*! \def PWMD_FD_READABLE
194 * Set when the file descriptor is readable.
196 #define PWMD_FD_READABLE 0x01
199 /*! \def PWMD_FD_WRITABLE
202 * Set when the file descriptor is writable.
204 #define PWMD_FD_WRITABLE 0x02
207 /*! \typedef pwmd_fd_t
209 * For use with \ref pwmd_get_fds().
212 /*! The file descriptor. */
215 /*! A bitmask of \ref PWMD_FD_READABLE and \ref PWMD_FD_WRITABLE. */
220 /*! \typedef pwmd_passphrase_cb_t
222 * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
223 * \ref pwmd_setopt().
225 * \param user A user data pointer which is set with \ref
226 * PWMD_OPTION_PASSPHRASE_DATA.
227 * \param[out] passphrase The passphrase which may be an empty string or NULL.
228 * \return 0 on success or an error code which will cause a command to fail.
230 typedef gpg_error_t (*pwmd_passphrase_cb_t
)(void *user
, char **passphrase
);
233 /*! \typedef pwmd_status_cb_t
235 * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
238 * \param user A user data pointer which is set with \ref
239 * PWMD_OPTION_STATUS_DATA.
240 * \param line The status message line.
241 * \return 0 on success or an error code which will cause a command to fail.
243 typedef int (*pwmd_status_cb_t
)(void *user
, const char *line
);
246 /*! \typedef pwmd_inquire_cb_t
248 * This is a callback function that gets passed to \ref pwmd_inquire(). It is
249 * used for sending data to the server for commands that return an INQUIRE
250 * response (STORE and IMPORT). The reason for this callback is to let the
251 * client send as many bytes as it wants rather than the entire chunk at once.
252 * It gets called during \ref assuan_transact() from an internal inquire
253 * callback function which in turn calls this function by looping over its
256 * \param user The user data pointer passed to \ref pwmd_inquire().
257 * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
258 * \param rc The result of the last internal call to \ref assuan_send_data()
259 * which did the sending of the data to the pwmd server. On the first call to
260 * this callback it will always be 0 because no data has been sent yet.
261 * \param[out] data The next chunk of data to send or NULL.
262 * \param[out] len The length of \a data or 0.
264 * \retval 0 There is more data to be sent.
265 * \retval GPG_ERR_EOF No need to call this function again, the current
266 * \a line is the last to send.
267 * \retval code Any other error code which will terminate the INQUIRE.
269 * \note The sent data is processed line-per-line. The line is either newline
270 * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
271 * allocated. Any remaining bytes are sent after the INQUIRE has finished.
273 typedef gpg_error_t (*pwmd_inquire_cb_t
)(void *user
, const char *cmd
,
274 gpg_error_t rc
, char **data
, size_t *len
);
277 /*! \enum pwmd_option_t
279 * libpwmd options which are set with \ref pwmd_setopt().
282 /*! A custom passphrase retrieval function which, when set, will be used
283 * instead of \ref pinentry(1). This function will not be used when the
284 * passphrase is cached on the server or the file is a new one. The value
285 * of this option should be a \ref pwmd_passphrase_cb_t function pointer.
287 PWMD_OPTION_PASSPHRASE_CB
,
289 /*! User supplied data which is passed to the custom password function. */
290 PWMD_OPTION_PASSPHRASE_DATA
,
292 /*! A string to use as the passphrase when doing an open or save. When not
293 * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
295 PWMD_OPTION_PASSPHRASE
,
297 /*! An integer value that specifies the specified the number of tries
298 * before \ref pinentry(1) will give up when opening a file with the wrong
299 * supplied passphrase. The default is 3.
301 * \note This option has no effect when trying to save a file. The user
302 * must either cancel the pinentry causing the save to fail or enter the
303 * correct passphrase during passphrase confirmation.
305 PWMD_OPTION_PINENTRY_TRIES
,
307 /*! A character string value which specifies the full path of the \ref
308 * pinentry(1) binary. For the local \ref pinentry(1) method, the default
309 * is specified at compile time.
313 PWMD_OPTION_PINENTRY_PATH
,
315 /*! A value which specifies the full path to the tty that \ref pinentry(1)
316 * will use. When set and no DISPLAY is available, \ref
317 * PWMD_OPTION_PINENTRY_TERM must also be set.
321 PWMD_OPTION_PINENTRY_TTY
,
323 /*! A value which specifies the terminal type (e.g., vt100) that \ref
324 * pinentry(1) will use when no X11 display is available.
328 PWMD_OPTION_PINENTRY_TERM
,
330 /*! A value which specifies the X11 display that \ref pinentry(1) will
335 PWMD_OPTION_PINENTRY_DISPLAY
,
337 /*! A character string that \ref pinentry(1) will use in it's dialog
340 PWMD_OPTION_PINENTRY_TITLE
,
342 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
343 PWMD_OPTION_PINENTRY_PROMPT
,
345 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
346 PWMD_OPTION_PINENTRY_DESC
,
348 /*! For \ref pinentry(1) localization. */
349 PWMD_OPTION_PINENTRY_LC_CTYPE
,
351 /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
352 PWMD_OPTION_PINENTRY_LC_MESSAGES
,
354 /*! An integer value that specifies the number of seconds \ref pinentry(1)
355 * will wait for input before timing out and aborting the current command.
356 * If 0, then no timeout will be used. The default is 30.
358 PWMD_OPTION_PINENTRY_TIMEOUT
,
360 /*! A function pointer of type \ref pwmd_status_cb_t that will process
361 * status messages received from the pwmd server.
363 PWMD_OPTION_STATUS_CB
,
365 /*! A user data pointer which is passed to the status message function. */
366 PWMD_OPTION_STATUS_DATA
,
368 /*! The IP version of type \ref pwmd_ip_version_t that \ref
369 * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
370 * connecting to the remote pwmd server.
374 PWMD_OPTION_IP_VERSION
,
378 /*! \brief Initialize the library.
380 * This function must be the first function called in the library before any
381 * others. It sets up internationalization among other things.
385 gpg_error_t
pwmd_init(void);
388 /*! \brief Creates a new handle.
390 * Creates a new handle for use with the other functions.
392 * \param name If not NULL, the name of the application. The application name
393 * is sent to the pwmd server after successfully connecting.
395 * \param name The application name or NULL.
396 * \return a new handle or NULL if there was not enough memory.
398 pwm_t
*pwmd_new(const char *name
)
399 __attribute__ ((warn_unused_result
));
402 /*! \brief Connect to a local pwmd server.
404 * Connects to a local unix domain socket.
406 * \param pwm A handle.
407 * \param path The socket path to connect to. If NULL, then a default of
408 * \a "~/.pwmd/socket" will be used.
409 * \return 0 on success or an error code.
410 * \see pwmd_ssh_connect(), pwmd_ssh_connect_async()
412 gpg_error_t
pwmd_connect(pwm_t
*pwm
, const char *path
)
413 __attribute__ ((warn_unused_result
));
416 /*! \brief Establish a remote connection to a pwmd server.
418 * Connects to a pwmd server over an SSH channel.
420 * \param pwm A handle.
421 * \param host The hostname to connect to.
422 * \param port The port or -1 for the default.
423 * \param identity The SSH identity file to use for authentication. This
424 * should specify the private key. The public key is assumed to be \a
426 * \param user The username on the SSH server to login as. If NULL then
427 * invoking user will be used.
428 * \param known_hosts A file containing the public SSH server key hash in SHA1
430 * \return 0 on success or an error code.
431 * \see pwmd_ssh_connect_async(), pwmd_process(), \ref ssh
433 gpg_error_t
pwmd_ssh_connect(pwm_t
*pwm
, const char *host
, int port
,
434 const char *identity
, const char *user
, const char *known_hosts
)
435 __attribute__ ((warn_unused_result
));
438 /*! \brief Establish a remote connection to a pwmd server asynchronously.
440 * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
441 * DNS lookups or while connecting.
445 * \param pwm A handle.
446 * \param host The hostname to connect to.
447 * \param port The port or -1 for the default.
448 * \param identity The SSH identity file to use for authentication. This
449 * should specify the private key. The public key is assumed to be \a
451 * \param user The username on the SSH server to login as. If NULL, the
452 * invoking username will be used.
453 * \param known_hosts A file containing the public SSH server key hash in SHA1
455 * \return 0 on success or an error code.
456 * \see pwmd_process(), \ref ssh
458 gpg_error_t
pwmd_ssh_connect_async(pwm_t
*pwm
, const char *host
, int port
,
459 const char *identity
, const char *user
, const char *known_hosts
)
460 __attribute__ ((warn_unused_result
));
463 /*! \brief Establish a connection by parsing a URL.
465 * This allows for connecting to a pwmd server by parsing the given URL
466 * string. Whether the connection is to a remote or local server depends on
470 * socket://[path/to/local/socket]
474 * ssh[46]://[username@]hostname[:port],identity,known_hosts
477 * The parameters in square brackets are optional and if not specified the
478 * defaults will be used.
480 * \param pwm A handle.
481 * \param url The string to parse.
482 * \return 0 on success or an error code.
484 gpg_error_t
pwmd_connect_url(pwm_t
*pwm
, const char *url
)
485 __attribute__ ((warn_unused_result
));
488 /*! \brief Establish a connection asynchronously by parsing a URL.
490 * This allows for connecting to a pwmd server by parsing the given URL
491 * string. Whether the connection is to a remote or local server depends on
495 * socket://[path/to/local/socket]
499 * ssh[46]://[username@]hostname[:port],identity,known_hosts
502 * The parameters in square brackets are optional and if not specified the
503 * defaults will be used.
507 * \param pwm A handle.
508 * \param url The string to parse.
509 * \return 0 on success or an error code.
511 gpg_error_t
pwmd_connect_url_async(pwm_t
*pwm
, const char *url
)
512 __attribute__ ((warn_unused_result
));
515 /*! \brief Retrieve a remote SSH host key.
517 * This key is needed for host verification of the remote pwmd server.
519 * \param pwm A handle.
520 * \param host The hostname to connect to.
521 * \param port The port.
522 * \param[out] result The server host key which must be freed with \ref
524 * \return 0 on success or an error code.
525 * \see pwmd_get_hostkey_async(), \ref ssh
527 gpg_error_t
pwmd_get_hostkey(pwm_t
*pwm
, const char *host
, int port
,
529 __attribute__ ((warn_unused_result
));
532 /*! \brief Retrieve a remote SSH host key asynchronously.
534 * This key is needed for host verification of the remote pwmd server.
538 * \param pwm A handle.
539 * \param host The hostname to connect to.
540 * \param port The port or a default if set to -1.
541 * \return 0 on success or an error code.
542 * \see pwmd_get_hostkey(), \ref pwmd_process(), \ref ssh
544 gpg_error_t
pwmd_get_hostkey_async(pwm_t
*pwm
, const char *host
, int port
)
545 __attribute__ ((warn_unused_result
));
548 /*! \brief Get the associated file descriptor(s) for a handle.
550 * This function lets the application poll the available file descriptors for
551 * the specified handle. It should be called after each asynchronous function
552 * and after each call to \ref pwmd_process() since the polled file
553 * descriptors may have been closed since the last call. It should also be
554 * called periodically to determine when to call \ref pwmd_process() to parse
555 * any pending status messages.
557 * After returning, \a n_fds is set to the number of available file
558 * descriptors which are stored in \a fds. The .flags member of \ref pwmd_fd_t
559 * specifies what can be monitored and is a bitmask of \ref PWMD_FD_READABLE
560 * and \ref PWMD_FD_WRITABLE. When ready, \ref pwmd_process() should be
563 * \param pwm A handle.
564 * \param[out] fds Set to the file descriptor(s) of the associated handle.
565 * \param[out] n_fds Initially the size of \a fds then updated to the number
566 * of available file descriptors which are stored in \a fds.
567 * \retval 0 on success or an error code.
568 * \retval GPG_ERR_ERANGE There are more file descriptors than the amount
569 * specified in \a n_fds. \a fds and \a n_fds are still usable though.
570 * \see pwmd_process()
572 gpg_error_t
pwmd_get_fds(pwm_t
*pwm
, pwmd_fd_t
*fds
, int *n_fds
)
573 __attribute__ ((warn_unused_result
));
576 /*! \brief Check for a unparsed buffered line.
578 * A buffered line is a line that was read from the server but was not
579 * processed. This function determines if there is such a line.
581 * \param pwm A handle.
582 * \retval 0 if there is pending data.
583 * \retval GPG_ERR_NO_DATA if there is no pending data.
584 * \see pwmd_process()
586 gpg_error_t
pwmd_pending_line(pwm_t
*pwm
)
587 __attribute__ ((warn_unused_result
));
590 /*! \brief Set library options.
592 * See \ref pwmd_option_t for option specific details.
594 * \param pwm A handle.
595 * \param opt The option.
596 * \param ... The option value.
597 * \return 0 on success or an error code.
599 gpg_error_t
pwmd_setopt(pwm_t
*pwm
, pwmd_option_t opt
, ...)
600 __attribute__ ((warn_unused_result
));
603 /*! \brief Open a file on the pwmd server.
605 * This will send the OPEN command to the server.
607 * \param pwm A handle.
608 * \param filename The filename to open.
609 * \return 0 on success or an error code.
612 gpg_error_t
pwmd_open(pwm_t
*pwm
, const char *filename
)
613 __attribute__ ((warn_unused_result
));
615 /*! \brief Open a file on the pwmd server using a local pinentry.
617 * This will send the OPEN command to the server like \ref pwmd_open() but
618 * will use the local pinentry and not pwmd's pinentry.
622 * \param pwm A handle.
623 * \param filename The filename to open.
624 * \return 0 on success or an error code.
627 gpg_error_t
pwmd_open2(pwm_t
*pwm
, const char *filename
)
628 __attribute__ ((warn_unused_result
));
631 /*! \brief Open a file on the pwmd server asynchronously (fork method).
633 * This will send the OPEN command to the pwmd server. The difference from
634 * \ref pwmd_open() is that it will not block if a pinentry is needed for
637 * The difference from \ref pwmd_open_async() is that libpwmd will \ref fork()
638 * a pinentry process rather than have pwmd use it's pinentry method. This may
639 * be useful if the passphrase isn't cached on a remote pwmd server and a
640 * remote \ref pinentry(1) is not possible.
646 * \param pwm A handle.
647 * \param filename The filename to open.
648 * \return 0 on success or an error code.
649 * \see pwmd_process(), \ref pinentry
651 gpg_error_t
pwmd_open_async2(pwm_t
*pwm
, const char *filename
)
652 __attribute__ ((warn_unused_result
));
655 /*! \brief Open a file on the pwmd server asynchronously.
657 * This will send the OPEN command to the pwmd server. The difference from
658 * \ref pwmd_open() is that it will not block if a pinentry is needed for
663 * \param pwm A handle.
664 * \param filename The filename to open.
665 * \return 0 on success or an error code.
666 * \see pwmd_process(), \ref pinentry
668 gpg_error_t
pwmd_open_async(pwm_t
*pwm
, const char *filename
)
669 __attribute__ ((warn_unused_result
));
672 /*! \brief Process an asynchronous function.
674 * After an asynchronous function has been called and has returned
675 * successfully, this function must be called to process the command to
676 * retrieve the result or return value.
678 * This function may also be called when not in a command to check for pending
679 * status messages sent from the server or to process a pending line.
681 * \param pwm A handle.
682 * \param rc Set to the return code of the command after ASYNC_DONE is
683 * returned. This value must be checked to determine if the command succeeded.
684 * \param[out] result Set to the result of the command when \a rc is 0. Note
685 * that not all commands return a result.
686 * \retval ASYNC_DONE The command has completed. \a rc should be checked to
687 * determine if the command was successful or not.
688 * \retval ASYNC_PROCESS The command is still running and this function should
690 * \see pwmd_get_fds(), pwmd_pending_line()
692 pwmd_async_t
pwmd_process(pwm_t
*pwm
, gpg_error_t
*rc
, char **result
)
693 __attribute__ ((warn_unused_result
));
696 /*! \brief Save a file on the pwmd server.
698 * This will send the SAVE command.
700 * \param pwm A handle.
701 * \return 0 on success or an error code.
704 gpg_error_t
pwmd_save(pwm_t
*pwm
)
705 __attribute__ ((warn_unused_result
));
708 /*! \brief Save a file on the pwmd server using the local pinentry.
710 * This will send the SAVE command like \ref pwmd_save() but will use a local
711 * pinentry and not pwmd's pinentry.
713 * \param pwm A handle.
714 * \return 0 on success or an error code.
717 gpg_error_t
pwmd_save2(pwm_t
*pwm
)
718 __attribute__ ((warn_unused_result
));
721 /*! \brief Save a file on the pwmd server asynchronously (fork method).
723 * This will send the SAVE command to the pwmd server. The difference from
724 * \ref pwmd_save() is that it will not block if a pinentry is needed for
727 * The difference from \ref pwmd_save_async() is that libpwmd will \ref fork()
728 * a pinentry process rather than have pwmd use it's pinentry method. This may
729 * be useful if the passphrase isn't cached on a remote pwmd server and a
730 * remote \ref pinentry(1) is not possible.
734 * \param pwm A handle.
735 * \return 0 on success or an error code.
736 * \see pwmd_process(), \ref pinentry
738 gpg_error_t
pwmd_save_async2(pwm_t
*pwm
)
739 __attribute__ ((warn_unused_result
));
742 /*! \brief Save changes to a file on the pwmd server asynchronously.
744 * This will send the SAVE command to the pwmd server. The difference from
745 * \ref pwmd_save() is that it will not block if a pinentry is needed for
750 * \param pwm A handle.
751 * \return 0 on success or an error code.
752 * \see pwmd_process(), \ref pinentry
754 gpg_error_t
pwmd_save_async(pwm_t
*pwm
)
755 __attribute__ ((warn_unused_result
));
758 /*! \brief Send a command to the pwmd server.
760 * Sends a command to the pwmd server. You should avoid sending the BYE
761 * command here because the assuan context will be freed and bad things will
762 * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
763 * send data to the server (STORE and IMPORT), \ref pwmd_inquire() should be
764 * used and not this function.
766 * \param pwm A handle.
767 * \param[out] result The result of the command when successful and which must
768 * be freed with \ref pwmd_free(). Note that not all commands return a result.
769 * \param cmd The command to send.
770 * \param ... The arguments to \a cmd.
771 * \return 0 on success or an error code.
773 gpg_error_t
pwmd_command(pwm_t
*pwm
, char **result
, const char *cmd
, ...)
774 __attribute__ ((warn_unused_result
));
777 /*! \brief Send a command to the pwmd server.
779 * Like \ref pwmd_command() but uses an argument pointer instead.
781 * \param pwm A handle.
782 * \param[out] result The result of the command when successful which must be
783 * freed with \ref pwmd_free(). Note that not all commands return a result.
784 * \param cmd The command to send.
785 * \param ap The arguments to \a cmd.
786 * \return 0 on success or an error code.
788 gpg_error_t
pwmd_command_ap(pwm_t
*pwm
, char **result
, const char *cmd
,
790 __attribute__ ((warn_unused_result
));
793 /*! \brief Send data to a pwmd server.
795 * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
796 * to the server. Use this function rather than \ref pwmd_command() for these
799 * \param pwm A handle.
800 * \param cmd The command to send that uses an INQUIRE.
801 * \param func A callback function which sets the data to be sent.
802 * \param user A user data pointer passed to the callback function \a func.
803 * \return 0 on success or an error code.
805 * \see pwmd_inquire_cb_t
807 gpg_error_t
pwmd_inquire(pwm_t
*pwm
, const char *cmd
, pwmd_inquire_cb_t func
,
809 __attribute__ ((warn_unused_result
));
812 /*! \brief Close a handle.
814 * This will close the connection to a pwmd server and free any resources
815 * associated with it.
817 * \param pwm A handle.
820 void pwmd_close(pwm_t
*pwm
);
823 /*! \brief Free a previously allocated pointer.
825 * Use this function to free resources allocated by the other libpwmd memory
826 * functions. Do not use it to free your own allocations.
828 * The difference between the standard free() and this function is that
829 * this one will zero out the contents of the pointer before freeing it.
831 * \param ptr The pointer to deallocate.
833 * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
834 * pwmd_process(), pwmd_command()
836 void pwmd_free(void *ptr
);
839 /*! \brief A wrapper around malloc.
841 * Like malloc(), but lets libpwmd keep track of the pointer.
843 * \param size The number of bytes to allocate.
844 * \return A newly allocated pointer or NULL if there wasn't enough memory.
845 * \see malloc(3), pwmd_free()
847 void *pwmd_malloc(size_t size
)
848 __attribute__ ((warn_unused_result
));
851 /*! \brief A wrapper around calloc().
853 * Like calloc(), but lets libpwmd keep track of the pointer.
855 * \param nmemb The number of bytes to allocate.
856 * \param size The number of bytes to allocate.
857 * \return A newly allocated pointer or NULL if there wasn't enough memory.
858 * \see calloc(3), pwmd_free()
860 void *pwmd_calloc(size_t nmemb
, size_t size
)
861 __attribute__ ((warn_unused_result
));
864 /*! \brief A wrapper around realloc().
866 * Like realloc(), but lets libpwmd keep track of the pointer. Note that this
867 * function will try and allocate the entire \a size before freeing the
868 * original pointer and returning the new one.
870 * \param ptr The pointer to reallocate.
871 * \param size The new number of bytes to allocate.
872 * \return A newly allocated pointer or NULL if there wasn't enough memory.
873 * \see realloc(3), pwmd_free()
875 void *pwmd_realloc(void *ptr
, size_t size
)
876 __attribute__ ((warn_unused_result
));
879 /*! \brief A wrapper around strdup().
881 * Like strdup(), but lets libpwmd keep track of the pointer.
883 * \param str The string to duplicate.
884 * \return A newly allocated character pointer or NULL if there wasn't
886 * \see strdup(3), pwmd_free()
888 char *pwmd_strdup(const char *str
)
889 __attribute__ ((warn_unused_result
));
891 /*! \brief Duplicate a formatted string.
893 * Like sprintf() but returns an allocated string.
895 * \param fmt The formatted string.
896 * \param ... Any format arguments to the string.
897 * \return A newly allocated character pointer or NULL if there wasn't
901 char *pwmd_strdup_printf(const char *fmt
, ...)
902 __attribute__ ((warn_unused_result
));
907 * A general pwmd error with no suitable description.
909 #define EPWMD_ERROR GPG_ERR_USER_1
912 /*! \def EPWMD_MAX_SLOTS
915 * The maximum number of cache slots has been reached. There is no available
916 * slot for a new file.
918 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
924 * A recursion loop was detected while processing a "target" attribute.
926 #define EPWMD_LOOP GPG_ERR_USER_3
929 /*! \def EPWMD_NO_FILE
932 * A command required an open file, but no file has yet been opened.
934 #define EPWMD_NO_FILE GPG_ERR_USER_4
937 /*! \def EPWMD_LIBXML_ERROR
940 * An XML parse or other libxml2 error occurred.
942 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_5
945 /*! \def EPWMD_FILE_MODIFIED
948 * The data file was modified either externally or by another another client
949 * while trying to process a command.
951 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_6
959 #define EPWMD_MAX GPG_ERR_USER_7
962 /*! \brief Return a description of an error code.
964 * \param code The error code to describe.
965 * \return A character description of the error code.
966 * \see pwmd_strerror_r()
968 const char *pwmd_strerror(gpg_error_t code
)
969 __attribute__ ((warn_unused_result
));
972 /*! \brief Return a description of an error code (thread-safe).
974 * This is a thread-safe version of \ref pwmd_strerror().
976 * \param code The error code to describe.
977 * \param[out] buf An allocated buffer to hold the error description.
978 * \param size The size of the allocated buffer \a buf.
981 * \retval ERANGE \a size was not large enough to hold the entire description
982 * and \a buf is set to the truncated error string.
984 int pwmd_strerror_r(gpg_error_t code
, char *buf
, size_t size
);