Fixed PWMD_OPTION_PINENTRY_TIMEOUT when used with pwmd_open2().
[libpwmd.git] / doc / libpwmd.3
blob53452d90ef74cf512728e788a0a1428259a5e44e
1 .TH "libpwmd.h" 3 "4 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 libpwmd.h \- 
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Defines"
11 .in +1c
12 .ti -1c
13 .RI "#define \fBLIBPWMD_VERSION\fP"
14 .br
15 .ti -1c
16 .RI "#define \fBEPWMD_ERROR\fP"
17 .br
18 .ti -1c
19 .RI "#define \fBEPWMD_MAX_SLOTS\fP"
20 .br
21 .ti -1c
22 .RI "#define \fBEPWMD_LOOP\fP"
23 .br
24 .ti -1c
25 .RI "#define \fBEPWMD_NO_FILE\fP"
26 .br
27 .ti -1c
28 .RI "#define \fBEPWMD_LIBXML_ERROR\fP"
29 .br
30 .ti -1c
31 .RI "#define \fBEPWMD_FILE_MODIFIED\fP"
32 .br
33 .ti -1c
34 .RI "#define \fBEPWMD_MAX\fP"
35 .br
36 .in -1c
37 .SS "Typedefs"
39 .in +1c
40 .ti -1c
41 .RI "typedef struct pwm_s \fBpwm_t\fP"
42 .br
43 .ti -1c
44 .RI "typedef gpg_error_t(* \fBpwmd_passphrase_cb_t\fP )(void *user, char **passphrase)"
45 .br
46 .ti -1c
47 .RI "typedef int(* \fBpwmd_status_cb_t\fP )(void *user, const char *line)"
48 .br
49 .ti -1c
50 .RI "typedef gpg_error_t(* \fBpwmd_inquire_cb_t\fP )(void *user, const char *cmd, gpg_error_t rc, char **data, size_t *len)"
51 .br
52 .in -1c
53 .SS "Enumerations"
55 .in +1c
56 .ti -1c
57 .RI "enum \fBpwmd_async_t\fP { \fBASYNC_INIT\fP, \fBASYNC_PROCESS\fP, \fBASYNC_DONE\fP }"
58 .br
59 .ti -1c
60 .RI "enum \fBpwmd_ip_version_t\fP { \fBPWMD_IP_ANY\fP, \fBPWMD_IPV4\fP, \fBPWMD_IPV6\fP }"
61 .br
62 .ti -1c
63 .RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PASSPHRASE\fP, \fBPWMD_OPTION_PINENTRY_TRIES\fP, \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_TITLE\fP, \fBPWMD_OPTION_PINENTRY_PROMPT\fP, \fBPWMD_OPTION_PINENTRY_DESC\fP, \fBPWMD_OPTION_PINENTRY_LC_CTYPE\fP, \fBPWMD_OPTION_PINENTRY_LC_MESSAGES\fP, \fBPWMD_OPTION_PINENTRY_TIMEOUT\fP, \fBPWMD_OPTION_STATUS_CB\fP, \fBPWMD_OPTION_STATUS_DATA\fP, \fBPWMD_OPTION_IP_VERSION\fP }"
64 .br
65 .in -1c
66 .SS "Functions"
68 .in +1c
69 .ti -1c
70 .RI "gpg_error_t \fBpwmd_init\fP (void)"
71 .br
72 .ti -1c
73 .RI "\fBpwm_t\fP * \fBpwmd_new\fP (const char *name)"
74 .br
75 .ti -1c
76 .RI "gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)"
77 .br
78 .ti -1c
79 .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)"
80 .br
81 .ti -1c
82 .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)"
83 .br
84 .ti -1c
85 .RI "gpg_error_t \fBpwmd_get_hostkey\fP (\fBpwm_t\fP *pwm, const char *host, int port, char **result)"
86 .br
87 .ti -1c
88 .RI "gpg_error_t \fBpwmd_get_hostkey_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)"
89 .br
90 .ti -1c
91 .RI "gpg_error_t \fBpwmd_get_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
92 .br
93 .ti -1c
94 .RI "gpg_error_t \fBpwmd_get_async2_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
95 .br
96 .ti -1c
97 .RI "gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)"
98 .br
99 .ti -1c
100 .RI "gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,...)"
102 .ti -1c
103 .RI "gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)"
105 .ti -1c
106 .RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)"
108 .ti -1c
109 .RI "gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)"
111 .ti -1c
112 .RI "gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)"
114 .ti -1c
115 .RI "\fBpwmd_async_t\fP \fBpwmd_process\fP (\fBpwm_t\fP *pwm, gpg_error_t *rc, char **result)"
117 .ti -1c
118 .RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)"
120 .ti -1c
121 .RI "gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)"
123 .ti -1c
124 .RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)"
126 .ti -1c
127 .RI "gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)"
129 .ti -1c
130 .RI "gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)"
132 .ti -1c
133 .RI "gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)"
135 .ti -1c
136 .RI "gpg_error_t \fBpwmd_inquire\fP (\fBpwm_t\fP *pwm, const char *cmd, \fBpwmd_inquire_cb_t\fP func, void *user)"
138 .ti -1c
139 .RI "void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
141 .ti -1c
142 .RI "void \fBpwmd_free\fP (void *ptr)"
144 .ti -1c
145 .RI "void * \fBpwmd_malloc\fP (size_t size)"
147 .ti -1c
148 .RI "void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
150 .ti -1c
151 .RI "void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
153 .ti -1c
154 .RI "char * \fBpwmd_strdup\fP (const char *str)"
156 .ti -1c
157 .RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)"
159 .ti -1c
160 .RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)"
162 .ti -1c
163 .RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)"
165 .in -1c
166 .SH "Detailed Description"
167 .PP 
168 libpwmd is a library making it easy for applications to use the pwmd server.
169 .SH "SSH Details"
171 \fBTodo\fP
172 .RS 4
175 .SH "Pinentry Details"
177 \fBpinentry(1)\fP is a program that prompts the user for input which is normally a passphrase or a confirmation. libpwmd can use this program either locally (the connection is to a remote server not on this host) or have the pwmd server use it's pinentry to retrieve a passphrase when needed.
179 There are a few options that tell pinentry how and where to prompt for a passphrase. See the \fBpwmd_option_t\fP section for details. These options are not sent (when using pwmd's pinentry) until the pinentry is needed.
181 If using a local pinentry by calling \fBpwmd_open2()\fP, \fBpwmd_save2()\fP, \fBpwmd_open_async2()\fP or \fBpwmd_save_async2()\fP, libpwmd will send the command 'OPTION PINENTRY=0' to the server. This is needed for pinentry retries (passphrase or confirmation failure). So if you need to change pinentry methods, then set this option as needed.
183 Some pinentry options can also be specified in a local configuration file \fI'~/.pwmd/pinentry.conf'\fP. These options are initial values for each invokation and may be changed by setting the appropriate \fBpwmd_option_t\fP. Each option and value is separated with a '=' on a single line. Unrecognized options are ignored. Here are the recognized options:
185 .PD 0
186 .IP "\(bu" 2
187 \fBPATH\fP The full path to the location of the pinentry binary. 
188 .IP "\(bu" 2
189 \fBDISPLAY\fP The X11 display to use. 
190 .IP "\(bu" 2
191 \fBTTYNAME\fP The full path to the tty that pinentry should prompt on. 
192 .IP "\(bu" 2
193 \fBTTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. 
195 \fB\fP.RS 4
199 \fBTodo\fP
200 .RS 4
201 X11 forwarding. 
206 .SH "Example Client"
208 The following example will list the element tree of the data file specified in the first command line argument.
212  #include <stdio.h>
213  #include <libpwmd.h>
215  int main()
217      pwm_t *pwm = pwmd_new(NULL);
218      gpg_error_t rc = pwmd_connect(pwm, NULL);
219      char *result;
220      
221      if (!rc) {
222          rc = pwmd_open(pwm, argv[1]);
224          if (!rc) {
225              rc = pwmd_command(pwm, &result, '%s', 'LIST');
227              if (!rc) {
228                  printf('%s', result);
229                  pwmd_free(result);
230              }
231          }
232      }
234      pwmd_close(pwm);
235      
236      if (rc)
237          fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc));
239      exit(rc ? 1 : 0);
244 .SH "Define Documentation"
245 .PP 
246 .SS "#define EPWMD_ERROR"
248 A general pwmd error with no suitable description. 
249 .SS "#define EPWMD_FILE_MODIFIED"
251 The data file was modified either externally or by another another client while trying to process a command. 
252 .SS "#define EPWMD_LIBXML_ERROR"
254 An XML parse or other libxml2 error occurred. 
255 .SS "#define EPWMD_LOOP"
257 A recursion loop was detected while processing a 'target' attribute. 
258 .SS "#define EPWMD_MAX_SLOTS"
260 The maximum number of cache slots has been reached. There is no available slot for a new file. 
261 .SS "#define EPWMD_NO_FILE"
263 A command required an open file, but no file has yet been opened. 
264 .SS "#define LIBPWMD_VERSION"
266 The version of this library. 
267 .SH "Typedef Documentation"
268 .PP 
269 .SS "\fBpwm_t\fP"
271 When a handle is mentioned in this documentation it is a pointer of this type. A new handle is created with \fBpwmd_new()\fP. 
272 .SS "\fBpwmd_inquire_cb_t\fP"
274 This is a callback function that gets passed to \fBpwmd_inquire()\fP. It is used for sending data to the server for commands that return an INQUIRE response (STORE and IMPORT). The reason for this callback is to let the client send as many bytes as it wants rather than the entire chunk at once. It gets called during \fBassuan_transact()\fP from an internal inquire callback function which in turn calls this function by looping over its return value.
276 \fBParameters:\fP
277 .RS 4
278 \fIuser\fP The user data pointer passed to \fBpwmd_inquire()\fP. 
280 \fIcmd\fP The same as the \fIcmd\fP argument to \fBpwmd_inquire()\fP. 
282 \fIrc\fP The result of the last internal call to \fBassuan_send_data()\fP which did the sending of the data to the pwmd server. On the first call to this callback it will always be 0 because no data has been sent yet. 
284 \fIdata\fP The next chunk of data to send or NULL. 
286 \fIlen\fP The length of \fIdata\fP or 0.
289 \fBReturn values:\fP
290 .RS 4
291 \fI0\fP There is more data to be sent. 
293 \fIGPG_ERR_EOF\fP No need to call this function again, the current \fIline\fP is the last to send. 
295 \fIcode\fP Any other error code which will terminate the INQUIRE.
298 \fBNote:\fP
299 .RS 4
300 The sent data is processed line-per-line. The line is either newline terminated or is buffered until ASSUAN_LINELENGTH bytes have been allocated. Any remaining bytes are sent after the INQUIRE has finished. 
304 .SS "\fBpwmd_passphrase_cb_t\fP"
306 The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwmd_setopt()\fP.
308 \fBParameters:\fP
309 .RS 4
310 \fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_PASSPHRASE_DATA\fP. 
312 \fIpassphrase\fP The passphrase which may be an empty string or NULL. 
315 \fBReturns:\fP
316 .RS 4
317 0 on success or an error code which will cause a command to fail. 
321 .SS "\fBpwmd_status_cb_t\fP"
323 The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP.
325 \fBParameters:\fP
326 .RS 4
327 \fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_STATUS_DATA\fP. 
329 \fIline\fP The status message line. 
332 \fBReturns:\fP
333 .RS 4
334 0 on success or an error code which will cause a command to fail. 
338 .SH "Enumeration Type Documentation"
339 .PP 
340 .SS "enum \fBpwmd_async_t\fP"
342 The return code of \fBpwmd_process()\fP which is used for all asynchronous commands. 
344 \fBEnumerator: \fP
345 .in +1c
347 \fB\fIASYNC_INIT \fP\fP
349 \fBFor internal use only.\fP
350 .RS 4
355 \fB\fIASYNC_PROCESS \fP\fP
356 \fBpwmd_process()\fP should be called again. 
358 \fB\fIASYNC_DONE \fP\fP
359 The command has completed. The result code should be checked for an error. 
360 .SS "enum \fBpwmd_ip_version_t\fP"
362 The value of the option \fBPWMD_OPTION_IP_VERSION\fP which is set with \fBpwmd_setopt()\fP. 
364 \fBEnumerator: \fP
365 .in +1c
367 \fB\fIPWMD_IP_ANY \fP\fP
368 Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. 
370 \fB\fIPWMD_IPV4 \fP\fP
371 Only try IPv4. 
373 \fB\fIPWMD_IPV6 \fP\fP
374 Only try IPv6. 
375 .SS "enum \fBpwmd_option_t\fP"
377 libpwmd options which are set with \fBpwmd_setopt()\fP. 
379 \fBEnumerator: \fP
380 .in +1c
382 \fB\fIPWMD_OPTION_PASSPHRASE_CB \fP\fP
383 A custom passphrase retrieval function which, when set, will be used instead of \fBpinentry(1)\fP. This function will not be used when the passphrase is cached on the server or the file is a new one. The value of this option should be a \fBpwmd_passphrase_cb_t\fP function pointer. 
385 \fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
386 User supplied data which is passed to the custom password function. 
388 \fB\fIPWMD_OPTION_PASSPHRASE \fP\fP
389 A string to use as the passphrase when doing an open or save. When not NULL, this option has precedence over \fBPWMD_OPTION_PASSPHRASE_CB\fP. 
391 \fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
392 An integer value that specifies the specified the number of tries before \fBpinentry(1)\fP will give up when opening a file with the wrong supplied passphrase. The default is 3.
394 \fBNote:\fP
395 .RS 4
396 This option has no effect when trying to save a file. The user must either cancel the pinentry causing the save to fail or enter the correct passphrase during passphrase confirmation. 
401 \fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
402 A character string value which specifies the full path of the \fBpinentry(1)\fP binary. For the local \fBpinentry(1)\fP method, the default is specified at compile time.
404 \fBSee also:\fP
405 .RS 4
406 \fBPinentry Details\fP 
411 \fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
412 A value which specifies the full path to the tty that \fBpinentry(1)\fP will use. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set.
414 \fBSee also:\fP
415 .RS 4
416 \fBPinentry Details\fP 
421 \fB\fIPWMD_OPTION_PINENTRY_TERM \fP\fP
422 A value which specifies the terminal type (e.g., vt100) that \fBpinentry(1)\fP will use when no X11 display is available.
424 \fBSee also:\fP
425 .RS 4
426 \fBPinentry Details\fP 
431 \fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP
432 A value which specifies the X11 display that \fBpinentry(1)\fP will use.
434 \fBSee also:\fP
435 .RS 4
436 \fBPinentry Details\fP 
441 \fB\fIPWMD_OPTION_PINENTRY_TITLE \fP\fP
442 A character string that \fBpinentry(1)\fP will use in it's dialog window. 
444 \fB\fIPWMD_OPTION_PINENTRY_PROMPT \fP\fP
445 A character string that \fBpinentry(1)\fP will use in it's dialog window.  
447 \fB\fIPWMD_OPTION_PINENTRY_DESC \fP\fP
448 A character string that \fBpinentry(1)\fP will use in it's dialog window.  
450 \fB\fIPWMD_OPTION_PINENTRY_LC_CTYPE \fP\fP
451 For \fBpinentry(1)\fP localization. 
453 \fB\fIPWMD_OPTION_PINENTRY_LC_MESSAGES \fP\fP
454 For \fBpinentry(1)\fP localization.  
456 \fB\fIPWMD_OPTION_PINENTRY_TIMEOUT \fP\fP
457 An integer value that specifies the number of seconds \fBpinentry(1)\fP will wait for input before timing out and aborting the current command. If 0, then no timeout will be used. The default is 30. 
459 \fB\fIPWMD_OPTION_STATUS_CB \fP\fP
460 A function pointer of type \fBpwmd_status_cb_t\fP that will process status messages received from the pwmd server. 
462 \fB\fIPWMD_OPTION_STATUS_DATA \fP\fP
463 A user data pointer which is passed to the status message function. 
465 \fB\fIPWMD_OPTION_IP_VERSION \fP\fP
466 The IP version of type \fBpwmd_ip_version_t\fP that \fBpwmd_ssh_connect()\fP and \fBpwmd_ssh_connect_async()\fP will use when connecting to the remote pwmd server.
468 \fBNote:\fP
469 .RS 4
470 This option must be set before a connection is made when not the default. 
474 .SH "Function Documentation"
475 .PP 
476 .SS "void* pwmd_calloc (size_t nmemb, size_t size)"
478 A wrapper around calloc(). 
480 Like calloc(), but lets libpwmd keep track of the pointer.
482 \fBParameters:\fP
483 .RS 4
484 \fInmemb\fP The number of bytes to allocate. 
486 \fIsize\fP The number of bytes to allocate. 
489 \fBReturns:\fP
490 .RS 4
491 A newly allocated pointer or NULL if there wasn't enough memory. 
494 \fBSee also:\fP
495 .RS 4
496 calloc(3), \fBpwmd_free()\fP 
500 .SS "void pwmd_close (\fBpwm_t\fP * pwm)"
502 Close a handle. 
504 This will close the connection to a pwmd server and free any resources associated with it.
506 \fBParameters:\fP
507 .RS 4
508 \fIpwm\fP A handle. 
511 \fBReturns:\fP
512 .RS 4
513 Nothing. 
517 .SS "gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, const char * cmd,  ...)"
519 Send a command to the pwmd server. 
521 Sends a command to the pwmd server. You should avoid sending the BYE command here because the assuan context will be freed and bad things will happen. Use \fBpwmd_close()\fP instead. For commands that use an INQUIRE to send data to the server (STORE and IMPORT), \fBpwmd_inquire()\fP should be used and not this function.
523 \fBParameters:\fP
524 .RS 4
525 \fIpwm\fP A handle. 
527 \fIresult\fP The result of the command when successful and which must be freed with \fBpwmd_free()\fP. Note that not all commands return a result. 
529 \fIcmd\fP The command to send. 
531 \fI...\fP The arguments to \fIcmd\fP. 
534 \fBReturns:\fP
535 .RS 4
536 0 on success or an error code. 
540 .SS "gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, const char * cmd, va_list ap)"
542 Send a command to the pwmd server. 
544 Like \fBpwmd_command()\fP but uses an argument pointer instead.
546 \fBParameters:\fP
547 .RS 4
548 \fIpwm\fP A handle. 
550 \fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP. Note that not all commands return a result. 
552 \fIcmd\fP The command to send. 
554 \fIap\fP The arguments to \fIcmd\fP. 
557 \fBReturns:\fP
558 .RS 4
559 0 on success or an error code. 
563 .SS "gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)"
565 Connect to a local pwmd server. 
567 Connects to a local unix domain socket.
569 \fBParameters:\fP
570 .RS 4
571 \fIpwm\fP A handle. 
573 \fIpath\fP The socket path to connect to. If NULL, then a default of \fI'~/.pwmd/socket'\fP will be used. 
576 \fBReturns:\fP
577 .RS 4
578 0 on success or an error code. 
581 \fBSee also:\fP
582 .RS 4
583 \fBpwmd_ssh_connect()\fP, \fBpwmd_ssh_connect_async()\fP 
587 .SS "void pwmd_free (void * ptr)"
589 Free a previously allocated pointer. 
591 Use this function to free resources allocated by the other libpwmd memory functions. Do not use it to free your own allocations.
593 The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it.
595 \fBParameters:\fP
596 .RS 4
597 \fIptr\fP The pointer to deallocate. 
600 \fBReturns:\fP
601 .RS 4
602 Nothing. 
605 \fBSee also:\fP
606 .RS 4
607 \fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_process()\fP, \fBpwmd_command()\fP 
611 .SS "gpg_error_t pwmd_get_async2_fd (\fBpwm_t\fP * pwm, int * fd)"
613 Get the file descriptor of the local pinentry method. 
615 This will allow polling of the file descriptor associated with the pipe of the forked pinentry process from \fBpwmd_open_async2()\fP and \fBpwmd_save_async2()\fP.
617 \fBParameters:\fP
618 .RS 4
619 \fIpwm\fP A handle. 
621 \fIfd\fP Set to the file descriptor of the associated handle. 
624 \fBReturns:\fP
625 .RS 4
626 0 on success or an error code. 
629 \fBSee also:\fP
630 .RS 4
631 \fBpwmd_process()\fP, \fBpwmd_open_async2()\fP, \fBpwmd_save_async2()\fP 
635 .SS "gpg_error_t pwmd_get_fd (\fBpwm_t\fP * pwm, int * fd)"
637 Get the socket file descriptor. 
639 This will allow polling of the file descriptor associated with the assuan context and in turn the pwmd server. It can be used to determine whether \fBpwmd_process()\fP should be called to process status messages.
641 \fBParameters:\fP
642 .RS 4
643 \fIpwm\fP A handle. 
645 \fIfd\fP Set to the file descriptor of the associated handle. 
648 \fBReturns:\fP
649 .RS 4
650 0 on success or an error code. 
653 \fBSee also:\fP
654 .RS 4
655 \fBpwmd_process()\fP 
659 .SS "gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)"
661 Retrieve a remote SSH host key. 
663 This key is needed for host verification of the remote pwmd server.
665 \fBParameters:\fP
666 .RS 4
667 \fIpwm\fP A handle. 
669 \fIhost\fP The hostname to connect to. 
671 \fIport\fP The port. 
673 \fIresult\fP The server host key which must be freed with \fBpwmd_free()\fP. 
676 \fBReturns:\fP
677 .RS 4
678 0 on success or an error code. 
681 \fBSee also:\fP
682 .RS 4
683 \fBpwmd_get_hostkey_async()\fP, \fBSSH Details\fP 
687 .SS "gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)"
689 Retrieve a remote SSH host key asynchronously. 
691 This key is needed for host verification of the remote pwmd server.
693 \fBpwmd_process()\fP should be called until the command completes.
695 \fBParameters:\fP
696 .RS 4
697 \fIpwm\fP A handle. 
699 \fIhost\fP The hostname to connect to. 
701 \fIport\fP The port or a default if set to -1. 
704 \fBReturns:\fP
705 .RS 4
706 0 on success or an error code. 
709 \fBSee also:\fP
710 .RS 4
711 \fBpwmd_get_hostkey()\fP, \fBSSH Details\fP 
715 .SS "gpg_error_t pwmd_init (void)"
717 Initialize the library. 
719 This function must be the first function called in the library before any others. It sets up internationalization among other things.
721 \fBReturns:\fP
722 .RS 4
723 0 Success. 
727 .SS "gpg_error_t pwmd_inquire (\fBpwm_t\fP * pwm, const char * cmd, \fBpwmd_inquire_cb_t\fP func, void * user)"
729 Send data to a pwmd server. 
731 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 commands.
733 \fBParameters:\fP
734 .RS 4
735 \fIpwm\fP A handle. 
737 \fIcmd\fP The command to send that uses an INQUIRE. 
739 \fIfunc\fP A callback function which sets the data to be sent. 
741 \fIuser\fP A user data pointer passed to the callback function \fIfunc\fP. 
744 \fBReturns:\fP
745 .RS 4
746 0 on success or an error code.
749 \fBSee also:\fP
750 .RS 4
751 \fBpwmd_inquire_cb_t\fP 
755 .SS "void* pwmd_malloc (size_t size)"
757 A wrapper around malloc. 
759 Like malloc(), but lets libpwmd keep track of the pointer.
761 \fBParameters:\fP
762 .RS 4
763 \fIsize\fP The number of bytes to allocate. 
766 \fBReturns:\fP
767 .RS 4
768 A newly allocated pointer or NULL if there wasn't enough memory. 
771 \fBSee also:\fP
772 .RS 4
773 malloc(3), \fBpwmd_free()\fP 
777 .SS "\fBpwm_t\fP* pwmd_new (const char * name)"
779 Creates a new handle. 
781 Creates a new handle for use with the other functions.
783 \fBParameters:\fP
784 .RS 4
785 \fIname\fP If not NULL, the name of the application. The application name is sent to the pwmd server after successfully connecting.
787 \fIname\fP The application name or NULL. 
790 \fBReturns:\fP
791 .RS 4
792 a new handle or NULL if there was not enough memory. 
796 .SS "gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)"
798 Open a file on the pwmd server. 
800 This will send the OPEN command to the server.
802 \fBParameters:\fP
803 .RS 4
804 \fIpwm\fP A handle. 
806 \fIfilename\fP The filename to open. 
809 \fBReturns:\fP
810 .RS 4
811 0 on success or an error code. 
814 \fBSee also:\fP
815 .RS 4
816 \fBPinentry Details\fP 
820 .SS "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)"
822 Open a file on the pwmd server using a local pinentry. 
824 This will send the OPEN command to the server like \fBpwmd_open()\fP but will use the local pinentry and not pwmd's pinentry.
826 \fBNote:\fP
827 .RS 4
828 This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
831 \fBParameters:\fP
832 .RS 4
833 \fIpwm\fP A handle. 
835 \fIfilename\fP The filename to open. 
838 \fBReturns:\fP
839 .RS 4
840 0 on success or an error code. 
843 \fBSee also:\fP
844 .RS 4
845 \fBPinentry Details\fP 
849 .SS "gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)"
851 Open a file on the pwmd server asynchronously. 
853 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.
855 \fBpwmd_process()\fP should be called until the command completes.
857 \fBParameters:\fP
858 .RS 4
859 \fIpwm\fP A handle. 
861 \fIfilename\fP The filename to open. 
864 \fBReturns:\fP
865 .RS 4
866 0 on success or an error code. 
869 \fBSee also:\fP
870 .RS 4
871 \fBpwmd_process()\fP, \fBPinentry Details\fP 
875 .SS "gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)"
877 Open a file on the pwmd server asynchronously (fork method). 
879 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.
881 The difference from \fBpwmd_open_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
883 \fBpwmd_process()\fP should be called until the command completes.
885 \fBNote:\fP
886 .RS 4
887 This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
890 \fBParameters:\fP
891 .RS 4
892 \fIpwm\fP A handle. 
894 \fIfilename\fP The filename to open. 
897 \fBReturns:\fP
898 .RS 4
899 0 on success or an error code. 
902 \fBSee also:\fP
903 .RS 4
904 \fBpwmd_process()\fP, \fBPinentry Details\fP 
908 .SS "gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)"
910 Check for a unparsed buffered line. 
912 A buffered line is a line that was read from the server but was not processed. This function determines if there is such a line.
914 \fBParameters:\fP
915 .RS 4
916 \fIpwm\fP A handle. 
919 \fBReturn values:\fP
920 .RS 4
921 \fI0\fP if there is pending data. 
923 \fIGPG_ERR_NO_DATA\fP if there is no pending data. 
926 \fBSee also:\fP
927 .RS 4
928 \fBpwmd_process()\fP 
932 .SS "\fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)"
934 Process an asynchronous function. 
936 After an asynchronous function has been called and has returned successfully, this function must be called to process the command to retrieve the result or return value.
938 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.
940 \fBParameters:\fP
941 .RS 4
942 \fIpwm\fP A handle. 
944 \fIrc\fP Set to the return code of the command after ASYNC_DONE is returned. This value must be checked to determine if the command succeeded. 
946 \fIresult\fP Set to the result of the command when \fIrc\fP is 0. Note that not all commands return a result. 
949 \fBReturn values:\fP
950 .RS 4
951 \fIASYNC_DONE\fP The command has completed. \fIrc\fP should be checked to determine if the command was successful or not. 
953 \fIASYNC_PROCESS\fP The command is still running and this function should be called again. 
956 \fBSee also:\fP
957 .RS 4
958 \fBpwmd_get_fd()\fP, pwmd_get_fd2(), \fBpwmd_pending_line()\fP 
962 .SS "void* pwmd_realloc (void * ptr, size_t size)"
964 A wrapper around realloc(). 
966 Like realloc(), but lets libpwmd keep track of the pointer. Note that this function will try and allocate the entire \fIsize\fP before freeing the original pointer and returning the new one.
968 \fBParameters:\fP
969 .RS 4
970 \fIptr\fP The pointer to reallocate. 
972 \fIsize\fP The new number of bytes to allocate. 
975 \fBReturns:\fP
976 .RS 4
977 A newly allocated pointer or NULL if there wasn't enough memory. 
980 \fBSee also:\fP
981 .RS 4
982 realloc(3), \fBpwmd_free()\fP 
986 .SS "gpg_error_t pwmd_save (\fBpwm_t\fP * pwm)"
988 Save a file on the pwmd server. 
990 This will send the SAVE command.
992 \fBParameters:\fP
993 .RS 4
994 \fIpwm\fP A handle. 
997 \fBReturns:\fP
998 .RS 4
999 0 on success or an error code. 
1002 \fBSee also:\fP
1003 .RS 4
1004 \fBPinentry Details\fP 
1008 .SS "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)"
1010 Save a file on the pwmd server using the local pinentry. 
1012 This will send the SAVE command like \fBpwmd_save()\fP but will use a local pinentry and not pwmd's pinentry.
1014 \fBParameters:\fP
1015 .RS 4
1016 \fIpwm\fP A handle. 
1019 \fBReturns:\fP
1020 .RS 4
1021 0 on success or an error code. 
1024 \fBSee also:\fP
1025 .RS 4
1026 \fBPinentry Details\fP 
1030 .SS "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)"
1032 Save changes to a file on the pwmd server asynchronously. 
1034 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.
1036 \fBpwmd_process()\fP should be called until the command completes.
1038 \fBParameters:\fP
1039 .RS 4
1040 \fIpwm\fP A handle. 
1043 \fBReturns:\fP
1044 .RS 4
1045 0 on success or an error code. 
1048 \fBSee also:\fP
1049 .RS 4
1050 \fBpwmd_process()\fP, \fBPinentry Details\fP 
1054 .SS "gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)"
1056 Save a file on the pwmd server asynchronously (fork method). 
1058 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.
1060 The difference from \fBpwmd_save_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
1062 \fBpwmd_process()\fP should be called until the command completes.
1064 \fBParameters:\fP
1065 .RS 4
1066 \fIpwm\fP A handle. 
1069 \fBReturns:\fP
1070 .RS 4
1071 0 on success or an error code. 
1074 \fBSee also:\fP
1075 .RS 4
1076 \fBpwmd_process()\fP, \fBPinentry Details\fP 
1080 .SS "gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt,  ...)"
1082 Set library options. 
1084 See \fBpwmd_option_t\fP for option specific details.
1086 \fBParameters:\fP
1087 .RS 4
1088 \fIpwm\fP A handle. 
1090 \fIopt\fP The option. 
1092 \fI...\fP The option value. 
1095 \fBReturns:\fP
1096 .RS 4
1097 0 on success or an error code. 
1101 .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)"
1103 Establish a remote connection to a pwmd server. 
1105 Connects to a pwmd server over an SSH channel.
1107 \fBParameters:\fP
1108 .RS 4
1109 \fIpwm\fP A handle. 
1111 \fIhost\fP The hostname to connect to. 
1113 \fIport\fP The port or -1 for the default. 
1115 \fIidentity\fP The SSH identity to use for authentication. 
1117 \fIuser\fP The username on the SSH server to login as. If NULL then invoking user will be used. 
1119 \fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format. 
1122 \fBReturns:\fP
1123 .RS 4
1124 0 on success or an error code. 
1127 \fBSee also:\fP
1128 .RS 4
1129 \fBpwmd_ssh_connect_async()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP 
1132 \fBTodo\fP
1133 .RS 4
1134 X11 forwarding. 
1138 .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)"
1140 Establish a remote connection to a pwmd server asynchronously. 
1142 This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DNS lookups or while connecting.
1144 \fBpwmd_process()\fP should be called until the command completes.
1146 \fBParameters:\fP
1147 .RS 4
1148 \fIpwm\fP A handle. 
1150 \fIhost\fP The hostname to connect to. 
1152 \fIport\fP The port or -1 for the default. 
1154 \fIidentity\fP The SSH identity to use for authentication. 
1156 \fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used. 
1158 \fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format. 
1161 \fBReturns:\fP
1162 .RS 4
1163 0 on success or an error code. 
1166 \fBSee also:\fP
1167 .RS 4
1168 \fBpwmd_process()\fP, \fBSSH Details\fP 
1171 \fBTodo\fP
1172 .RS 4
1173 X11 forwarding. 
1177 .SS "char* pwmd_strdup (const char * str)"
1179 A wrapper around strdup(). 
1181 Like strdup(), but lets libpwmd keep track of the pointer.
1183 \fBParameters:\fP
1184 .RS 4
1185 \fIstr\fP The string to duplicate. 
1188 \fBReturns:\fP
1189 .RS 4
1190 A newly allocated character pointer or NULL if there wasn't enough memory. 
1193 \fBSee also:\fP
1194 .RS 4
1195 strdup(3), \fBpwmd_free()\fP 
1199 .SS "char* pwmd_strdup_printf (const char * fmt,  ...)"
1201 Duplicate a formatted string. 
1203 Like sprintf() but returns an allocated string.
1205 \fBParameters:\fP
1206 .RS 4
1207 \fIfmt\fP The formatted string. 
1209 \fI...\fP Any format arguments to the string. 
1212 \fBReturns:\fP
1213 .RS 4
1214 A newly allocated character pointer or NULL if there wasn't enough memory. 
1217 \fBSee also:\fP
1218 .RS 4
1219 \fBpwmd_free()\fP 
1223 .SS "const char* pwmd_strerror (gpg_error_t code)"
1225 Return a description of an error code. 
1227 \fBParameters:\fP
1228 .RS 4
1229 \fIcode\fP The error code to describe. 
1232 \fBReturns:\fP
1233 .RS 4
1234 A character description of the error code. 
1237 \fBSee also:\fP
1238 .RS 4
1239 \fBpwmd_strerror_r()\fP 
1243 .SS "int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)"
1245 Return a description of an error code (thread-safe). 
1247 This is a thread-safe version of \fBpwmd_strerror()\fP.
1249 \fBParameters:\fP
1250 .RS 4
1251 \fIcode\fP The error code to describe. 
1253 \fIbuf\fP An allocated buffer to hold the error description. 
1255 \fIsize\fP The size of the allocated buffer \fIbuf\fP.
1258 \fBReturn values:\fP
1259 .RS 4
1260 \fI0\fP Success. 
1262 \fIERANGE\fP \fIsize\fP was not large enough to hold the entire description and \fIbuf\fP is set to the truncated error string. 
1266 .SH "Author"
1267 .PP 
1268 Generated automatically by Doxygen for libpwmd from the source code.