Renamed pwmd_get_fd2() to pwmd_get_async2_fd().
[libpwmd.git] / src / libpwmd.h.in
blob129fb7f9358c8feef833ea5c8401fdb542ea3448
1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
2 /*
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
22 * server.
25 /*! \section ssh SSH Details
27 * \todo
30 /*! \section pinentry Pinentry Details
32 * \todo
35 /*! \section example Example Client
37 * The following example will list the element tree of the data file specified
38 * in the first command line argument.
40 * \code
41 * #include <stdio.h>
42 * #include <libpwmd.h>
44 * int main()
45 * {
46 * pwm_t *pwm = pwmd_new(NULL);
47 * gpg_error_t rc = pwmd_connect(pwm, NULL);
48 * char *result;
50 * if (!rc) {
51 * rc = pwmd_open(pwm, argv[1]);
53 * if (!rc) {
54 * rc = pwmd_command(pwm, &result, "%s", "LIST");
56 * if (!rc) {
57 * printf("%s", result);
58 * pwmd_free(result);
59 * }
60 * }
61 * }
63 * pwmd_close(pwm);
65 * if (rc)
66 * fprintf(stderr, "ERR: %s\n", pwmd_strerror(rc));
68 * exit(rc ? 1 : 0);
69 * }
70 * \endcode
73 /*! \file */
74 #ifndef LIBPWMD_H
75 #define LIBPWMD_H
77 #include <gpg-error.h>
78 #include <stdarg.h>
80 #ifdef __cplusplus
81 extern "C" {
82 #endif
84 /*! \def LIBPWMD_VERSION
85 * \hideinitializer
87 * The version of this library.
89 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_COMPAT@@VER_PATCH@
92 struct pwm_s;
93 /*! \typedef pwm_t
95 * When a handle is mentioned in this documentation it is a pointer of this
96 * type. A new handle is created with \ref pwmd_new().
98 typedef struct pwm_s pwm_t;
101 /*! \typedef pwmd_async_t
103 * The return code of \ref pwmd_process() which is used for all asynchronous
104 * commands.
106 typedef enum {
107 /*! \internal */
108 ASYNC_INIT,
110 /*! \ref pwmd_process() should be called again. */
111 ASYNC_PROCESS,
113 /*! The command has completed. The result code should be checked for an
114 * error. */
115 ASYNC_DONE,
116 } pwmd_async_t;
119 /*! \typedef pwmd_ip_version_t
121 * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
122 * pwmd_setopt().
124 typedef enum {
125 /*! Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. */
126 PWMD_IP_ANY,
128 /*! Only try IPv4. */
129 PWMD_IPV4,
131 /*! Only try IPv6. */
132 PWMD_IPV6
133 } pwmd_ip_version_t;
136 /*! \typedef pwmd_passphrase_cb_t
138 * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
139 * \ref pwmd_setopt().
141 * \param user A user data pointer which is set with \ref
142 * PWMD_OPTION_PASSPHRASE_DATA.
143 * \param[out] passphrase The passphrase which may be an empty string or NULL.
144 * \return 0 on success or an error code which will cause a command to fail.
146 typedef gpg_error_t (*pwmd_passphrase_cb_t)(void *user, char **passphrase);
149 /*! \typedef pwmd_status_cb_t
151 * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
152 * pwmd_setopt().
154 * \param user A user data pointer which is set with \ref
155 * PWMD_OPTION_STATUS_DATA.
156 * \param line The status message line.
157 * \return 0 on success or an error code which will cause a command to fail.
159 typedef int (*pwmd_status_cb_t)(void *user, const char *line);
162 /*! \typedef pwmd_inquire_cb_t
164 * This is a callback function that gets passed to \ref pwmd_inquire(). It is
165 * used for sending data to the server for commands that return an INQUIRE
166 * response (STORE and IMPORT). The reason for this callback is to let the
167 * client send as many bytes as it wants rather than the entire chunk at once.
168 * It gets called during \ref assuan_transact() from an internal inquire
169 * callback function which in turn calls this function by looping over its
170 * return value.
172 * \param user The user data pointer passed to \ref pwmd_inquire().
173 * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
174 * \param rc The result of the last internal call to \ref assuan_send_data()
175 * which did the sending of the data to the pwmd server. On the first call to
176 * this callback it will always be 0 because no data has been sent yet.
177 * \param[out] data The next chunk of data to send or NULL.
178 * \param[out] len The length of \a data or 0.
180 * \retval 0 There is more data to be sent.
181 * \retval GPG_ERR_EOF No need to call this function again, the current
182 * \a line is the last to send.
183 * \retval code Any other error code which will terminate the INQUIRE.
185 * \note The sent data is processed line-per-line. The line is either newline
186 * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
187 * allocated. Any remaining bytes are sent after the INQUIRE has finished.
189 typedef gpg_error_t (*pwmd_inquire_cb_t)(void *user, const char *cmd,
190 gpg_error_t rc, char **data, size_t *len);
193 /*! \enum pwmd_option_t
195 * libpwmd options which are set with \ref pwmd_setopt().
197 typedef enum {
198 /*! A custom passphrase retrieval function which, when set, will be used
199 * instead of \ref pinentry(1). This function will not be used when the
200 * passphrase is cached on the server or the file is a new one. The value
201 * of this option should be a \ref pwmd_passphrase_cb_t function pointer.
203 PWMD_OPTION_PASSPHRASE_CB,
205 /*! User supplied data which is passed to the custom password function. */
206 PWMD_OPTION_PASSPHRASE_DATA,
208 /*! An integer value that specifies the specified the number of tries
209 * before \ref pinentry(1) will give up when opening a file with the wrong
210 * supplied passphrase. The default is 3.
212 * \note This option has no effect when trying to save a file. The user
213 * must either cancel the pinentry causing the save to fail or enter the
214 * correct passphrase during passphrase confirmation.
216 PWMD_OPTION_PINENTRY_TRIES,
218 /*! A character string value which specifies the full path of the \ref
219 * pinentry(1) binary. For the local \ref pinentry(1) method, the default
220 * is specified at compile time.
222 PWMD_OPTION_PINENTRY_PATH,
224 /*! A value which specifies the full path to the tty that \ref pinentry(1)
225 * will use. When set and no DISPLAY is available, \ref
226 * PWMD_OPTION_PINENTRY_TERM must also be set.
228 * \see \ref pinentry
230 PWMD_OPTION_PINENTRY_TTY,
232 /*! A value which specifies the X11 display that \ref pinentry(1) will
233 * use.
235 * \see \ref pinentry
237 PWMD_OPTION_PINENTRY_DISPLAY,
239 /*! A value which specifies the terminal type (e.g., vt100) that \ref
240 * pinentry(1) will use when no X11 display is available.
242 * \see \ref pinentry
244 PWMD_OPTION_PINENTRY_TERM,
246 /*! A string to use as the passphrase when doing an open or save. When not
247 * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
249 PWMD_OPTION_PASSPHRASE,
251 /*! A character string that \ref pinentry(1) will use in it's dialog
252 * window.
254 PWMD_OPTION_PINENTRY_TITLE,
256 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
257 PWMD_OPTION_PINENTRY_PROMPT,
259 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
260 PWMD_OPTION_PINENTRY_DESC,
262 /*! For \ref pinentry(1) localization. */
263 PWMD_OPTION_PINENTRY_LC_CTYPE,
265 /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
266 PWMD_OPTION_PINENTRY_LC_MESSAGES,
268 /*! An integer value that specifies the number of seconds \ref pinentry(1)
269 * will wait for input before timing out and aborting the current command.
270 * If 0, then no timeout will be used. The default is 30.
272 PWMD_OPTION_PINENTRY_TIMEOUT,
274 /*! A function pointer of type \ref pwmd_status_cb_t that will process
275 * status messages received from the pwmd server.
277 PWMD_OPTION_STATUS_CB,
279 /*! A user data pointer which is passed to the status message function. */
280 PWMD_OPTION_STATUS_DATA,
282 /*! The IP version of type \ref pwmd_ip_version_t that \ref
283 * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
284 * connecting to the remote pwmd server.
286 * \pre_conn_req
288 PWMD_OPTION_IP_VERSION,
289 } pwmd_option_t;
292 /*! \brief Initialize the library.
294 * This function must be the first function called in the library before any
295 * others. It sets up internationalization among other things.
297 * \return 0 Success.
299 gpg_error_t pwmd_init(void);
302 /*! \brief Creates a new handle.
304 * Creates a new handle for use with the other functions.
306 * \param name If not NULL, the name of the application. The application name
307 * is sent to the pwmd server after successfully connecting.
309 * \param name The application name or NULL.
310 * \return a new handle or NULL if there was not enough memory.
312 pwm_t *pwmd_new(const char *name)
313 __attribute__ ((warn_unused_result));
316 /*! \brief Connect to a local pwmd server.
318 * Connects to a local unix domain socket.
320 * \param pwm A handle.
321 * \param path The socket path to connect to. If NULL, then a default of
322 * \a "~/.pwmd/socket" will be used.
323 * \return 0 on success or an error code.
324 * \see pwmd_ssh_connect(), pwmd_ssh_connect_async()
326 gpg_error_t pwmd_connect(pwm_t *pwm, const char *path)
327 __attribute__ ((warn_unused_result));
330 /*! \brief Establish a remote connection to a pwmd server.
332 * Connects to a pwmd server over an SSH channel.
334 * \param pwm A handle.
335 * \param host The hostname to connect to.
336 * \param port The port or -1 for the default.
337 * \param identity The SSH identity to use for authentication.
338 * \param user The username on the SSH server to login as. If NULL then
339 * invoking user will be used.
340 * \param known_hosts A file containing the public SSH server key hash in SHA1
341 * format.
342 * \return 0 on success or an error code.
343 * \see pwmd_ssh_connect_async(), pwmd_process(), \ref ssh
344 * \todo X11 forwarding.
346 gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port,
347 const char *identity, const char *user, const char *known_hosts)
348 __attribute__ ((warn_unused_result));
351 /*! \brief Establish a remote connection to a pwmd server asynchronously.
353 * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
354 * DNS lookups or while connecting.
356 * \ref pwmd_process() should be called until the command completes.
358 * \param pwm A handle.
359 * \param host The hostname to connect to.
360 * \param port The port or -1 for the default.
361 * \param identity The SSH identity to use for authentication.
362 * \param user The username on the SSH server to login as. If NULL, the
363 * invoking username will be used.
364 * \param known_hosts A file containing the public SSH server key hash in SHA1
365 * format.
366 * \return 0 on success or an error code.
367 * \see pwmd_process(), \ref ssh
368 * \todo X11 forwarding.
370 gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host, int port,
371 const char *identity, const char *user, const char *known_hosts)
372 __attribute__ ((warn_unused_result));
375 /*! \brief Retrieve a remote SSH host key.
377 * This key is needed for host verification of the remote pwmd server.
379 * \param pwm A handle.
380 * \param host The hostname to connect to.
381 * \param port The port.
382 * \param[out] result The server host key which must be freed with \ref
383 * pwmd_free().
384 * \return 0 on success or an error code.
385 * \see pwmd_get_hostkey_async(), \ref ssh
387 gpg_error_t pwmd_get_hostkey(pwm_t *pwm, const char *host, int port,
388 char **result)
389 __attribute__ ((warn_unused_result));
392 /*! \brief Retrieve a remote SSH host key asynchronously.
394 * This key is needed for host verification of the remote pwmd server.
396 * \ref pwmd_process() should be called until the command completes.
398 * \param pwm A handle.
399 * \param host The hostname to connect to.
400 * \param port The port or a default if set to -1.
401 * \return 0 on success or an error code.
402 * \see pwmd_get_hostkey(), \ref ssh
404 gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host, int port)
405 __attribute__ ((warn_unused_result));
408 /*! \brief Get the socket file descriptor.
410 * This will allow polling of the file descriptor associated with the assuan
411 * context and in turn the pwmd server. It can be used to determine whether
412 * \ref pwmd_process() should be called to process status messages.
414 * \param pwm A handle.
415 * \param[out] fd Set to the file descriptor of the associated handle.
416 * \return 0 on success or an error code.
417 * \see pwmd_process()
419 gpg_error_t pwmd_get_fd(pwm_t *pwm, int *fd)
420 __attribute__ ((warn_unused_result));
423 /*! \brief Get the file descriptor of the local pinentry method.
425 * This will allow polling of the file descriptor associated with the pipe of
426 * the forked pinentry process from \ref pwmd_open_async2() and \ref
427 * pwmd_save_async2().
429 * \param pwm A handle.
430 * \param[out] fd Set to the file descriptor of the associated handle.
431 * \return 0 on success or an error code.
432 * \see pwmd_process(), pwmd_open_async2(), pwmd_save_async2()
434 gpg_error_t pwmd_get_async2_fd(pwm_t *pwm, int *fd)
435 __attribute__ ((warn_unused_result));
438 /*! \brief Check for a unparsed buffered line.
440 * A buffered line is a line that was read from the server but was not
441 * processed. This function determines if there is such a line.
443 * \param pwm A handle.
444 * \retval 0 if there is pending data.
445 * \retval GPG_ERR_NO_DATA if there is no pending data.
446 * \see pwmd_process()
448 gpg_error_t pwmd_pending_line(pwm_t *pwm)
449 __attribute__ ((warn_unused_result));
452 /*! \brief Set library options.
454 * See \ref pwmd_option_t for option specific details.
456 * \param pwm A handle.
457 * \param opt The option.
458 * \param ... The option value.
459 * \return 0 on success or an error code.
461 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...)
462 __attribute__ ((warn_unused_result));
465 /*! \brief Open a file on the pwmd server.
467 * This will send the OPEN command to the server.
469 * \param pwm A handle.
470 * \param filename The filename to open.
471 * \return 0 on success or an error code.
472 * \see \ref pinentry
474 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename)
475 __attribute__ ((warn_unused_result));
477 /*! \brief Open a file on the pwmd server using a local pinentry.
479 * This will send the OPEN command to the server like \ref pwmd_open() but
480 * will use the local pinentry and not pwmd's pinentry.
482 * \param pwm A handle.
483 * \param filename The filename to open.
484 * \return 0 on success or an error code.
485 * \see \ref pinentry
487 gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename)
488 __attribute__ ((warn_unused_result));
491 /*! \brief Open a file on the pwmd server asynchronously (fork method).
493 * This will send the OPEN command to the pwmd server. The difference from
494 * \ref pwmd_open() is that it will not block if a pinentry is needed for
495 * passphrase input.
497 * The difference from \ref pwmd_open_async() is that libpwmd will \ref fork()
498 * a pinentry process rather than have pwmd use it's pinentry method. This may
499 * be useful if the passphrase isn't cached on a remote pwmd server and a
500 * remote \ref pinentry(1) is not possible.
502 * \ref pwmd_process() should be called until the command completes.
504 * \param pwm A handle.
505 * \param filename The filename to open.
506 * \return 0 on success or an error code.
507 * \see pwmd_process(), \ref pinentry
509 gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename)
510 __attribute__ ((warn_unused_result));
513 /*! \brief Open a file on the pwmd server asynchronously.
515 * This will send the OPEN command to the pwmd server. The difference from
516 * \ref pwmd_open() is that it will not block if a pinentry is needed for
517 * passphrase input.
519 * \ref pwmd_process() should be called until the command completes.
521 * \param pwm A handle.
522 * \param filename The filename to open.
523 * \return 0 on success or an error code.
524 * \see pwmd_process(), \ref pinentry
526 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename)
527 __attribute__ ((warn_unused_result));
530 /*! \brief Process an asynchronous function.
532 * After an asynchronous function has been called and has returned
533 * successfully, this function must be called to process the command to
534 * retrieve the result or return value.
536 * This function may also be called when not in a command to check for pending
537 * status messages sent from the server or to process a pending line.
539 * \param pwm A handle.
540 * \param rc Set to the return code of the command after ASYNC_DONE is
541 * returned. This value must be checked to determine if the command succeeded.
542 * \param[out] result Set to the result of the command when \a rc is 0. Note
543 * that not all commands return a result.
544 * \retval ASYNC_DONE The command has completed. \a rc should be checked to
545 * determine if the command was successful or not.
546 * \retval ASYNC_PROCESS The command is still running and this function should
547 * be called again.
548 * \see pwmd_get_fd(), pwmd_get_fd2(), pwmd_pending_line()
550 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result)
551 __attribute__ ((warn_unused_result));
554 /*! \brief Save a file on the pwmd server.
556 * This will send the SAVE command.
558 * \param pwm A handle.
559 * \return 0 on success or an error code.
560 * \see \ref pinentry
562 gpg_error_t pwmd_save(pwm_t *pwm)
563 __attribute__ ((warn_unused_result));
566 /*! \brief Save a file on the pwmd server using the local pinentry.
568 * This will send the SAVE command like \ref pwmd_save() but will use a local
569 * pinentry and not pwmd's pinentry.
571 * \param pwm A handle.
572 * \return 0 on success or an error code.
573 * \see \ref pinentry
575 gpg_error_t pwmd_save2(pwm_t *pwm)
576 __attribute__ ((warn_unused_result));
579 /*! \brief Save a file on the pwmd server asynchronously (fork method).
581 * This will send the SAVE command to the pwmd server. The difference from
582 * \ref pwmd_save() is that it will not block if a pinentry is needed for
583 * passphrase input.
585 * The difference from \ref pwmd_save_async() is that libpwmd will \ref fork()
586 * a pinentry process rather than have pwmd use it's pinentry method. This may
587 * be useful if the passphrase isn't cached on a remote pwmd server and a
588 * remote \ref pinentry(1) is not possible.
590 * \ref pwmd_process() should be called until the command completes.
592 * \param pwm A handle.
593 * \return 0 on success or an error code.
594 * \see pwmd_process(), \ref pinentry
596 gpg_error_t pwmd_save_async2(pwm_t *pwm)
597 __attribute__ ((warn_unused_result));
600 /*! \brief Save changes to a file on the pwmd server asynchronously.
602 * This will send the SAVE command to the pwmd server. The difference from
603 * \ref pwmd_save() is that it will not block if a pinentry is needed for
604 * passphrase input.
606 * \ref pwmd_process() should be called until the command completes.
608 * \param pwm A handle.
609 * \return 0 on success or an error code.
610 * \see pwmd_process(), \ref pinentry
612 gpg_error_t pwmd_save_async(pwm_t *pwm)
613 __attribute__ ((warn_unused_result));
616 /*! \brief Send a command to the pwmd server.
618 * Sends a command to the pwmd server. You should avoid sending the BYE
619 * command here because the assuan context will be freed and bad things will
620 * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
621 * send data to the server (STORE and IMPORT), \ref pwmd_inquire() should be
622 * used and not this function.
624 * \param pwm A handle.
625 * \param[out] result The result of the command when successful and which must
626 * be freed with \ref pwmd_free(). Note that not all commands return a result.
627 * \param cmd The command to send.
628 * \param ... The arguments to \a cmd.
629 * \return 0 on success or an error code.
631 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...)
632 __attribute__ ((warn_unused_result));
635 /*! \brief Send a command to the pwmd server.
637 * Like \ref pwmd_command() but uses an argument pointer instead.
639 * \param pwm A handle.
640 * \param[out] result The result of the command when successful which must be
641 * freed with \ref pwmd_free(). Note that not all commands return a result.
642 * \param cmd The command to send.
643 * \param ap The arguments to \a cmd.
644 * \return 0 on success or an error code.
646 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
647 va_list ap)
648 __attribute__ ((warn_unused_result));
651 /*! \brief Send data to a pwmd server.
653 * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
654 * to the server. Use this function rather than \ref pwmd_command() for these
655 * commands.
657 * \param pwm A handle.
658 * \param cmd The command to send that uses an INQUIRE.
659 * \param func A callback function which sets the data to be sent.
660 * \param user A user data pointer passed to the callback function \a func.
661 * \return 0 on success or an error code.
663 * \see pwmd_inquire_cb_t
665 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_cb_t func,
666 void *user)
667 __attribute__ ((warn_unused_result));
670 /*! \brief Close a handle.
672 * This will close the connection to a pwmd server and free any resources
673 * associated with it.
675 * \param pwm A handle.
676 * \return Nothing.
678 void pwmd_close(pwm_t *pwm);
681 /*! \brief Free a previously allocated pointer.
683 * Use this function to free resources allocated by the other libpwmd memory
684 * functions. Do not use it to free your own allocations.
686 * The difference between the standard free() and this function is that
687 * this one will zero out the contents of the pointer before freeing it.
689 * \param ptr The pointer to deallocate.
690 * \return Nothing.
691 * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
692 * pwmd_process(), pwmd_command()
694 void pwmd_free(void *ptr);
697 /*! \brief A wrapper around malloc.
699 * Like malloc(), but lets libpwmd keep track of the pointer.
701 * \param size The number of bytes to allocate.
702 * \return A newly allocated pointer or NULL if there wasn't enough memory.
703 * \see malloc(3), pwmd_free()
705 void *pwmd_malloc(size_t size)
706 __attribute__ ((warn_unused_result));
709 /*! \brief A wrapper around calloc().
711 * Like calloc(), but lets libpwmd keep track of the pointer.
713 * \param nmemb The number of bytes to allocate.
714 * \param size The number of bytes to allocate.
715 * \return A newly allocated pointer or NULL if there wasn't enough memory.
716 * \see calloc(3), pwmd_free()
718 void *pwmd_calloc(size_t nmemb, size_t size)
719 __attribute__ ((warn_unused_result));
722 /*! \brief A wrapper around realloc().
724 * Like realloc(), but lets libpwmd keep track of the pointer. Note that this
725 * function will try and allocate the entire \a size before freeing the
726 * original pointer and returning the new one.
728 * \param ptr The pointer to reallocate.
729 * \param size The new number of bytes to allocate.
730 * \return A newly allocated pointer or NULL if there wasn't enough memory.
731 * \see realloc(3), pwmd_free()
733 void *pwmd_realloc(void *ptr, size_t size)
734 __attribute__ ((warn_unused_result));
737 /*! \brief A wrapper around strdup().
739 * Like strdup(), but lets libpwmd keep track of the pointer.
741 * \param str The string to duplicate.
742 * \return A newly allocated character pointer or NULL if there wasn't
743 * enough memory.
744 * \see strdup(3), pwmd_free()
746 char *pwmd_strdup(const char *str)
747 __attribute__ ((warn_unused_result));
750 /*! \def EPWMD_ERROR
751 * \hideinitializer
753 * A general pwmd error with no suitable description.
755 #define EPWMD_ERROR GPG_ERR_USER_1
758 /*! \def EPWMD_MAX_SLOTS
759 * \hideinitializer
761 * The maximum number of cache slots has been reached. There is no available
762 * slot for a new file.
764 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
767 /*! \def EPWMD_LOOP
768 * \hideinitializer
770 * A recursion loop was detected while processing a "target" attribute.
772 #define EPWMD_LOOP GPG_ERR_USER_3
775 /*! \def EPWMD_NO_FILE
776 * \hideinitializer
778 * A command required an open file, but no file has yet been opened.
780 #define EPWMD_NO_FILE GPG_ERR_USER_4
783 /*! \def EPWMD_LIBXML_ERROR
784 * \hideinitializer
786 * An XML parse or other libxml2 error occurred.
788 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_5
791 /*! \def EPWMD_FILE_MODIFIED
792 * \hideinitializer
794 * The data file was modified either externally or by another another client
795 * while trying to process a command.
797 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_6
800 /*! \def EPWMD_MAX
801 * \hideinitializer
802 * \if cond1
803 * \endif
805 #define EPWMD_MAX GPG_ERR_USER_7
808 /*! \brief Return a description of an error code.
810 * \param code The error code to describe.
811 * \return A character description of the error code.
812 * \see pwmd_strerror_r()
814 const char *pwmd_strerror(gpg_error_t code)
815 __attribute__ ((warn_unused_result));
818 /*! \brief Return a description of an error code (thread-safe).
820 * This is a thread-safe version of \ref pwmd_strerror().
822 * \param code The error code to describe.
823 * \param[out] buf An allocated buffer to hold the error description.
824 * \param size The size of the allocated buffer \a buf.
826 * \retval 0 Success.
827 * \retval ERANGE \a size was not large enough to hold the entire description
828 * and \a buf is set to the truncated error string.
830 int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size);
832 #ifdef __cplusplus
834 #endif
836 #endif