libpwmd.3.in

   1 .\" This program is free software; you can redistribute it and/or modify
   2 .\" it under the terms of the GNU General Public License as published by
   3 .\" the Free Software Foundation; either version 2 of the License, or
   4 .\" (at your option) any later version.
   5 .\"
   6 .\" This program is distributed in the hope that it will be useful,
   7 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   8 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   9 .\" GNU General Public License for more details.
  10 .\"
  11 .\" You should have received a copy of the GNU General Public License
  12 .\" along with this program; if not, write to the Free Software
  13 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH LIBPWMD 3 "3 Feb 2007" "Password Manager Daemon Library" "Password Manager Daemon Library"
  19 .SH NAME
  20
  21 libpwmd \- pwmd client interface library
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <libpwmd.h>
  25 .sp
  26 .BI "pwm_t *pwmd_connect(const char " *socket ", int " **error ");"
  27 .BI "int pwmd_command(pwm_t " *pwm ", char " **result ", int " **error ", pwmd_cmd " cmd ", " ... ");"
  28 .BI "void pwmd_close(pwm_t " *pwm ");"
  29 .BI "const char *pwmd_strerror(int " error ");"
  30 .P
  31 .BI "typedef char *(" pwmd_password_func ")(void *" data ");"
  32 .fi
  33 .SH DESCRIPTION
  34 .B libpwmd
  35 is an library making it easy for applications to use
  36 .BR pwmd (1).
  37 .P
  38 \fBpwmd_connect\fP() connects to the specified \fIsocket\fP. If \fIsocket\fP
  39 is NULL then a default of \fI~/.pwmd/socket\fP will be used. If there is an
  40 error while connecting \fIerror\fP is set to the errno of the failed function
  41 and NULL is returned. When successful a handle is returned for use in the
  42 other library functions.
  43 .P
  44 \fBpwmd_command\fP() sends either a protocol command to the server or sets
  45 library options using handle \fIpwm\fP. The function returns \fBPWMD_OK\fP
  46 when successful and stores the output of the protocol command \fIcmd\fP to
  47 \fIresult\fP which should be
  48 .BR free (3)'ed.
  49 Protocol commands that don't have a result will set \fIresult\fP to NULL. If
  50 a protocol error occurs then \fBPWMD_PERROR\fP is returned and \fIerror\fP is
  51 set to the protocol error code. \fBPWMD_ERROR\fP is returned when a
  52 non-protocol error occurs and sets \fIerror\fP to the errno of the failed
  53 function. \fBPWMD_PINENTRY_ERROR\fP is returned when
  54 .BR pinentry (1)
  55 fails and sets \fIerror\fP to \fBEPWMD_ERROR\fP. \fIcmd\fP is one of:
  56 .RS
  57 .TP
  58 .B PWMD_OPEN
  59 Opens a file on the server. The following argument should be of type
  60 \fIchar *\fP to specify the filename.
  61 .TP
  62 .B PWMD_SAVE
  63 Sends the \fISAVE\fP protocol command. It also checks to see if the file is
  64 cached on the server and determines whether to obtain a password from
  65 .BR pinentry (1).
  66 This command takes no arguments.
  67 .TP
  68 .B PWMD_COMMAND
  69 Sends a protocol command to the server. The next argument is of type
  70 \fIchar *\fP which is the command to send. The command should be newline
  71 terminated.
  72 .TP
  73 .B PWMD_SETOPT
  74 Sets library options and
  75 .BR pinentry (1)
  76 settings. The next argument is one of the following:
  77 .RS
  78 .TP
  79 .B PWMD_OPTION_PASSWORD_FUNC
  80 Specifies a function to use to get a password. The function should return an
  81 allocated \fIchar *\fP string which is the password or NULL if there is an
  82 error.
  83 .TP
  84 .B PWMD_OPTION_PASSWORD_DATA
  85 A userdata pointer passed to the password function.
  86 .TP
  87 .B PWMD_OPTION_PINENTRY
  88 Whether to use
  89 .BR pinentry (1)
  90 to obtain the password for opening and saving a file on the server. The
  91 following argument is an \fIint\fP and is \fI1\fP to enable
  92 .BR pinentry (1)
  93 use, and \fI0\fP to use the password which is set with
  94 \fBPWMD_OPTION_PASSWORD\fP.
  95 .TP
  96 .B PWMD_OPTION_TITLE
  97 .TP
  98 .B PWMD_OPTION_DESC
  99 .TP
 100 .B PWMD_OPTION_PROMPT
 101 Sets the strings used in the
 102 .BR pinentry (1)
 103 program.
 104 The next argument is of type \fIchar *\fP. If not defined then a default will
 105 be used.
 106 .TP
 107 .B PWMD_OPTION_PASSWORD
 108 Sets the password to use for opening and saving a file when
 109 \fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
 110 and is of type \fIchar *\fP.
 111 .RE
 112 .RE
 113 .P
 114 \fBpwmd_close\fP() closes the connection to the server and frees resources
 115 used by the handle \fIpwm\fP.
 116 .P
 117 \fBpwmd_strerror\fP() returns a string describing a protocol error code
 118 \fIerror\fP or NULL if \fIerror\fP is invalid.
 119
 120 .SH FILES
 121 .TP
 122 .B ~/.pwmd/socket
 123 Default connecting socket.
 124 .TP
 125 .B @prefix@/lib/pkgconfig/libpwmd.pc
 126 A
 127 .BR pkg-config (1)
 128 metadata file.
 129
 130 .SH AUTHOR
 131 Ben Kibbey <bjk@luxsci.net>
 132 .br
 133 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 134
 135 .SH "SEE ALSO"
 136 .BR pwmd (1),
 137 .BR pinentry (1),
 138 .BR free (3),
 139 .BR errno (3)