[svn] assuan - r319 - trunk/doc
svn author marcus
cvs at cvs.gnupg.org
Tue Nov 10 18:59:41 CET 2009
Author: marcus
Date: 2009-11-10 18:59:41 +0100 (Tue, 10 Nov 2009)
New Revision: 319
Modified:
trunk/doc/ChangeLog
trunk/doc/assuan.texi
Log:
2009-11-10 Marcus Brinkmann <marcus at g10code.de>
* assuan.texi: Various fixes and updates for the new interface.
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2009-11-10 09:04:50 UTC (rev 318)
+++ trunk/doc/ChangeLog 2009-11-10 17:59:41 UTC (rev 319)
@@ -1,3 +1,7 @@
+2009-11-10 Marcus Brinkmann <marcus at g10code.de>
+
+ * assuan.texi: Various fixes and updates for the new interface.
+
2009-11-05 Marcus Brinkmann <marcus at g10code.de>
* assuan.texi: Update assuan_pipe_connect, assuan_socket_connect
Modified: trunk/doc/assuan.texi
===================================================================
--- trunk/doc/assuan.texi 2009-11-10 09:04:50 UTC (rev 318)
+++ trunk/doc/assuan.texi 2009-11-10 17:59:41 UTC (rev 319)
@@ -624,7 +624,7 @@
One way to call this function is
@smallexample
-assuan_set_assuan_err_source (GPG_ERR_SOURCE_DEFAULT);
+assuan_set_gpg_err_source (GPG_ERR_SOURCE_DEFAULT);
@end smallexample
@end deftypefun
@@ -813,6 +813,8 @@
suppressed and the caller is responsible to cleanup the child process.
@item ASSUAN_CONFIDENTIAL
Uses to return the state of the confidential logging mode.
+ at item ASSUAN_NO_FIXSIGNALS
+Do not modify signal handler for @code{SIGPIPE}.
@end table
@end deftp
@end deftypefun
@@ -844,6 +846,100 @@
@end deftypefun
+ at deftp {Data type} {struct assuan_system_hooks}
+This structure is used to store the system callback interface
+functions. It has the following members, whose semantics are similar
+to the corresponding system functions, but not exactly equivalent.
+
+ at table @code
+ at item int version
+The user should set this to @code{ASSUAN_SYSTEM_HOOKS_VERSION}. This
+indicates to the library which members of this structure are present
+in case of future extensions. The user should initialize the whole
+structure with zero bytes.
+
+ at item void (*usleep) (assuan_context_t ctx, unsigned int usec)
+This is the function called by @sc{Assuan} to sleep for @code{USEC}
+microseconds.
+
+ at item int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx)
+This is the function called by @sc{Assuan} to create a pipe. The
+returned file descriptor @code{fd[inherit_idx]} must be inheritable by
+the child process (under Windows, this requires some extra work).
+
+ at item int (*close) (assuan_context_t ctx, assuan_fd_t fd)
+This is the function called by @sc{Assuan} to close a file descriptor
+created through the system functions.
+
+ at item ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer, size_t size)
+This is the function called by @sc{Assuan} to read data from a file
+descriptor. It is functionally equivalent to the system @code{read}
+function.
+
+ at item ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd, const void *buffer, size_t size)
+This is the function called by @sc{Assuan} to write data to a file
+descriptor. It is functionally equivalent to the system @code{write}
+function.
+
+ at item int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, int flags)
+This is the function called by @sc{Assuan} to receive a message from a
+file descriptor. It is functionally equivalent to the system
+ at code{recvmsg} function.
+
+ at item int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd, const assuan_msghdr_t msg, int flags);
+This is the function called by @sc{Assuan} to send a message to a
+file descriptor. It is functionally equivalent to the system
+ at code{sendmsg} function.
+
+ at item int (*spawn) (assuan_context_t ctx, pid_t *r_pid, const char *name, const char **argv, assuan_fd_t fd_in, assuan_fd_t fd_out, assuan_fd_t *fd_child_list, void (*atfork) (void *opaque, int reserved), void *atforkvalue, unsigned int flags)
+This is the function called by @sc{Assuan} to spawn a child process.
+The @code{stdin} and @code{stdout} file descriptors are provided in
+ at code{fd_in} and @code{fd_out} respectively, but can be set to
+ at code{ASSUAN_INVALID_FD}, in which case they are set to
+ at code{/dev/null}. On systems which use @code{fork} and @code{exec},
+the @code{atfork} function should be called with @code{atforkvalue}
+and @code{0} for flags in the child process right after @code{fork}
+returns. @code{fd_child_list} is a @code{ASSUAN_INVALID_FD}
+terminated array (or @code{NULL}) and specifies file descriptors to be
+inherited by the child process.
+
+A special situation occurs if @code{name} is a null pointer, in which
+case the process should just fork but not call @code{exec}. In this
+case, @code{*argv} should be set to @code{"client"} in the parent
+process and @code{"server"} in the child process.
+
+ at item pid_t (*waitpid) (assuan_context_t ctx, pid_t pid, int action, int *status, int options)
+This is the function called by @sc{Assuan} to wait for the spawned
+child process @var{pid} to exit, or, if @var{action} is 1, to just
+release all resources associated with @var{pid} (required on Windows
+platforms). If @var{action} is 0, this is equivalent to @code{waitpid}.
+
+ at item int (*socketpair) (assuan_context_t ctx, int namespace, int style, int protocol, assuan_fd_t filedes[2])
+This is the function called by @sc{Assuan} to create a socketpair. It
+is equivalent to @code{socketpair}.
+ at end table
+ at end deftp
+
+
+ at deftypefun void assuan_set_system_hooks (@w{assuan_system_hooks_t @var{system_hooks}})
+Set the default system hooks to use. There is currently no way to
+reset to the default system hooks.
+ at end deftypefun
+
+ at deftypefun void assuan_ctx_set_system_hooks (@w{assuan_context_t @var{ctx}}, @w{assuan_system_hooks_t @var{system_hooks}})
+Set the system hooks for context @var{ctx}. There is currently no way
+to reset tot the default system hooks, create a new context for that.
+ at end deftypefun
+
+The following system hook collections are defined by the library for
+your convenience:
+
+ at table @code
+ at item ASSUAN_SYSTEM_PTH
+System hooks suitable for use with the GNU Pth library.
+ at end table
+
+
@node Reading and Writing
@section How to communicate with the peer
@@ -1040,7 +1136,7 @@
functions are used with this feature:
@anchor{function assuan_sendfd}
- at deftypefun gpg_error_t assuan_sendfd (@w{assuan_context_t @var{ctx}}, @w{int @var{fd}})
+ at deftypefun gpg_error_t assuan_sendfd (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t @var{fd}})
Send the descriptor @var{fd} to the peer using the context @var{ctx}.
The descriptor must be sent before the command is issued that makes
@@ -1052,7 +1148,7 @@
@end deftypefun
@anchor{function assuan_receivefd}
- at deftypefun gpg_error_t assuan_receivefd (@w{assuan_context_t @var{ctx}}, @w{int *@var{fd}})
+ at deftypefun gpg_error_t assuan_receivefd (@w{assuan_context_t @var{ctx}}, @w{assuan_fd_t *@var{fd}})
Receive a descriptor pending for the context @var{ctx} from the peer.
The descriptor must be pending before this function is called. To
@@ -1116,7 +1212,7 @@
rc = assuan_init_pipe_server (&ctx, filedes);
@}
else
- rc = assuan_init_socket_server (&ctx, fd, 2);
+ rc = assuan_init_socket_server (&ctx, fd, ASSUAN_SOCKET_SERVER_ACCEPTED);
if (rc)
@{
fprintf (stderr, "server init failed: %s\n", gpg_strerror (rc));
@@ -1126,7 +1222,7 @@
@noindent
This is the first part of the command handler. In case this is called
-as a pipe based server, @var{fd} will be based as @code{fd} and the
+as a pipe based server, @var{fd} will be based as @var{fd} and the
code assumes that the server's @code{stdin} and @code{stdout} file
handles are connected to a pipe. The initialization is thus done
using the function:
@@ -1142,7 +1238,7 @@
In case the server has been called using a bi-directional pipe
(socketpair), @var{filedes} is ignored and the file descriptor is
taken from the environment variable @env{_assuan_connection_fd}. You
-won't need to know that because @code{assuan_pipe_connect_ext}, used
+won't need to know that because @code{assuan_pipe_connect}, used
by the client to connect to such a server, automagically sets this
variable.
@end deftypefun
@@ -1206,8 +1302,13 @@
@}
@end example
+ at deftp {Data type} {gpg_error_t (*assuan_handler_t) (@w{assuan_context_t @var{ctx}}, @w{char *@var{line}})}
+This is the function invoked by @sc{Assuan} for various command
+related callback functions. Some of these callback functions have a
+different type, but most use @code{assuan_handler_t}.
+ at end deftp
- at deftypefun gpg_error_t assuan_register_command (@w{assuan_context_t @var{ctx}}, @w{const char *@var{cmd_string}}, @w{int (*@var{handler}) (assuan_context_t, char *)})
+ at deftypefun gpg_error_t assuan_register_command (@w{assuan_context_t @var{ctx}}, @w{const char *@var{cmd_string}}, @w{assuan_handler_t @var{handler}}, @w{const char *@var{help_string}})
This registers the command named @var{cmd_string} with the Assuan
context @var{ctx}. @var{handler} is the function called by Libassuan
@@ -1218,6 +1319,10 @@
@code{CANCEL}, @code{OPTION}, @code{BYE}, @code{AUTH}, @code{RESET}
and @code{END}. It is possible, but not recommended, to override
these commands.
+
+ at var{help_string} is a help string that is used for automatic
+documentation. It should contain a usage line followed by an empty
+line and a complete description.
@end deftypefun
@deftypefun gpg_error_t assuan_register_post_cmd_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)}, @w{gpg_error_t @var{err}})
@@ -1228,19 +1333,19 @@
command-related cleanup.
@end deftypefun
- at deftypefun gpg_error_t assuan_register_bye_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)})
+ at deftypefun gpg_error_t assuan_register_bye_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
Register function @var{fnc} with context @var{ctx} to be called right
before the standard handler for the @code{BYE} command is being called.
@end deftypefun
- at deftypefun gpg_error_t assuan_register_reset_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)})
+ at deftypefun gpg_error_t assuan_register_reset_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
Register function @var{fnc} with context @var{ctx} to be called right
before the standard handler for the @code{RESET} command is being called.
@end deftypefun
- at deftypefun gpg_error_t assuan_register_cancel_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)})
+ at deftypefun gpg_error_t assuan_register_cancel_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
Register function @var{fnc} with context @var{ctx} to be called right
before the standard handler for the @code{RESET} command is being called.
@@ -1258,7 +1363,7 @@
@end deftypefun
- at deftypefun gpg_error_t assuan_register_input_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t, const char*)})
+ at deftypefun gpg_error_t assuan_register_input_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
Although the input function may be overridden with a custom handler, it
is often more convenient to use the default handler and to know whether
@@ -1269,7 +1374,7 @@
descriptor is available by calling @code{assuan_get_input_fd}.
@end deftypefun
- at deftypefun gpg_error_t assuan_register_output_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t, const char*)})
+ at deftypefun gpg_error_t assuan_register_output_notify (@w{assuan_context_t @var{ctx}}, @w{assuan_handler_t @var{handler}})
Although the output function may be overridden with a custom handler, it
is often more convenient to use the default handler and to know whether
@@ -1488,10 +1593,10 @@
should just implement the bind/connect/listen/accept stage yourself.
You can register the listen FD with your main event loop, accept the
connection when it becomes ready, and finally call
- at code{assuan_init_socket_server} with the final argument being 2
-to create an Assuan context for this connection. This way you can
-also handle multiple connections in parallel. The reference
-implementation for this approach is DirMngr.
+ at code{assuan_init_socket_server} with the final argument being
+ at code{ASSUAN_SOCKET_SERVER_ACCEPTED} to create an Assuan context for this
+connection. This way you can also handle multiple connections in
+parallel. The reference implementation for this approach is DirMngr.
For pipe servers: @code{assuan_init_pipe_server} creates an Assuan
context valid for the pipe FDs.
@@ -1654,16 +1759,16 @@
@end deftypefun
- at deftypefun int assuan_get_input_fd (@w{assuan_context_t @var{ctx}})
+ at deftypefun assuan_fd_t assuan_get_input_fd (@w{assuan_context_t @var{ctx}})
Return the file descriptor sent by the client using the last @code{INPUT}
-command. Returns @code{-1} if no file descriptor is available.
+command. Returns @code{ASSUAN_INVALID_FD} if no file descriptor is available.
@end deftypefun
- at deftypefun int assuan_get_output_fd (@w{assuan_context_t @var{ctx}})
+ at deftypefun assuan_fd_t assuan_get_output_fd (@w{assuan_context_t @var{ctx}})
Return the file descriptor sent by the client using the last
- at code{OUTPUT} command. Returns @code{-1} if no file descriptor is
+ at code{OUTPUT} command. Returns @code{ASSUAN_INVALID_FD} if no file descriptor is
available.
@end deftypefun
@@ -1700,13 +1805,14 @@
@deftypefun pid_t assuan_get_pid (@w{assuan_context_t @var{ctx}})
-This function returns the pid of the connected connected peer. If that
-pid is not known @code{-1} is returned. Note that it is not always
-possible to learn the pid of the other process. For a pipe based server
-the client knows it instantly and a mechanism is in place to let the
-server learn it. For socket based servers the pid is only available on
-systems providing the @code{SO_PEERCRED} socket option @footnote{to our
-knowledge only the Linux kernel has this feature}.
+This function returns the pid of the connected connected peer. If
+that pid is not known @code{ASSUAN_INVALID_PID} is returned. Note
+that it is not always possible to learn the pid of the other
+process. For a pipe based server the client knows it instantly and a
+mechanism is in place to let the server learn it. For socket based
+servers the pid is only available on systems providing the
+ at code{SO_PEERCRED} socket option @footnote{to our knowledge only the
+Linux kernel has this feature}.
@end deftypefun
More information about the Gnupg-commits
mailing list