[Pkg-gnupg-commit] [libassuan] 186/437: 2007-05-06 Marcus Brinkmann <marcus at g10code.de>
Eric Dorland
eric at moszumanska.debian.org
Fri May 22 05:33:41 UTC 2015
This is an automated email from the git hooks/post-receive script.
eric pushed a commit to branch master
in repository libassuan.
commit 6746803805f884c42119555e33892c51b4bdfc65
Author: Marcus Brinkmann <mb at g10code.com>
Date: Sun May 6 21:57:58 2007 +0000
2007-05-06 Marcus Brinkmann <marcus at g10code.de>
* assuan.texi: Clean up typos.
---
doc/ChangeLog | 4 +
doc/assuan.texi | 262 +++++++++++++++++++++++++++++---------------------------
2 files changed, 139 insertions(+), 127 deletions(-)
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 25fb64a..8c4131d 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2007-05-06 Marcus Brinkmann <marcus at g10code.de>
+
+ * assuan.texi: Clean up typos.
+
2006-10-31 Werner Koch <wk at g10code.com>
* assuan.texi: Finished.
diff --git a/doc/assuan.texi b/doc/assuan.texi
index 54ed7f3..53430b1 100644
--- a/doc/assuan.texi
+++ b/doc/assuan.texi
@@ -136,22 +136,22 @@ Indices
@node Introduction
@chapter Introduction to Assuan
-In an ideal world, Assuan is irrelevant. Assuan's primary use is to
-allow a client to interact with a non-persistent server. Using
-Assuan, this is accomplished by forking a subprocess and communicating
-with it via, for example, a pipe or Unix domain socket. This method
-is neither elegant nor efficient especially when there is a lot of
-data spread across several transactions: not only is there a penalty
-for an increased number of context switches, but also a significant
-amount of data is @var{memcpy}ed from the client to a file descriptor
-and from the file descriptor to the server. Despite these and other
-disadvantages, this type of client/server communication can be useful:
-the client is completely separate from the server; they are in
-different address spaces. This is especially important in situations
-where the server must have a known degree of reliability and data must
-be protected: as the Assuan protocol is well defined and clients
-cannot corrupt the servers' address space, auditing become much
-easier.
+In an ideal world, Assuan would not be necessary. Assuan's primary
+use is to allow a client to interact with a non-persistent server.
+Using Assuan, this is accomplished by forking a subprocess and
+communicating with it via, for example, a pipe or Unix domain socket.
+This method is neither elegant nor efficient, especially when there is
+a lot of data spread across several transactions: not only is there a
+penalty for an increased number of context switches, but also a
+significant amount of data is @var{memcpy}ed from the client to a file
+descriptor and from the file descriptor to the server. Despite these
+and other disadvantages, this type of client/server communication can
+be useful: the client is completely separate from the server; they are
+in different address spaces. This is especially important in
+situations where the server must have a known degree of reliability
+and data must be protected: as the Assuan protocol is well defined and
+clients cannot corrupt the servers' address space, auditing becomes
+much easier.
Assuan was developed for use by the GNU Privacy Guard, GnuPG, to
prevent potentially buggy clients from unwittingly corrupting
@@ -162,13 +162,12 @@ independently of the user interfaces, e.g. mail clients and other
encryption front ends. Like a shared library, the interface is well
defined and any number of front ends can use it; however, unlike a
shared library, the client cannot see or touch the server's data. As
-with any modular system, Assuan helps keep the servers small and
-understandable help to make code more understandable and less error
-prone.
+with any modular system, Assuan helps keep the components small,
+understandable and less error prone.
Assuan is not, however, limited to use with GnuPG servers and clients:
-it was design to be flexible enough to meet the demands of almost any
-transaction based environment with non-persistent servers.
+it was designed to be flexible enough to meet the demands of many
+transaction based environments with non-persistent servers.
@node Assuan
@chapter Description of the Assuan protocol.
@@ -210,13 +209,13 @@ Design criteria:
The implementation is line based with a maximum line size of 1000
octets. The default IPC mechanism are Unix Domain Sockets.
-On a connect request the server responds either with an okay or an error
-status. For authentication check the server may send an Inquiry
-Response prior to the first Okay, it may also issue Status messages.
-The server must check that the client is allowed to connect, this is
-done by requesting the credentials for the peer and comparing them to
-those of the server. This avoids attacks based on wrong socket
-permissions.
+On a connect request the server responds either with an okay or an
+error status. For authentication check the server may send an Inquiry
+Response prior to the first Okay, and it may also issue Status
+messages. The server must check that the client is allowed to
+connect, this is done by requesting the credentials for the peer and
+comparing them to those of the server. This avoids attacks based on
+wrong socket permissions.
It may choose to delay the first response in case of an error. The
server never closes the connection - however the lower protocol may do
@@ -325,17 +324,9 @@ Although the commands are application specific, some of them are used by
all protocols and partly directly supported by the Assuan library:
@table @code
- at item CANCEL
-This command is used for future extensions.
-
@item BYE
Close the connect, the server will reply with an @code{OK}.
- at item AUTH
-Not yet specified as we don't implement it in the first phase. See my
-mail to gpa-dev on 2001-10-25 about the rationale for measurements
-against local attacks.
-
@item RESET
Reset the connection but not any existing authentication. The server
should release all resources associated with the connection.
@@ -359,6 +350,14 @@ Leading and trailing spaces around @var{name} and @var{value} are
allowed but should be ignored. For compatibility reasons, @var{name}
may be prefixed with two dashes. The use of the equal sign is optional
but suggested if @var{value} is given.
+
+ at item CANCEL
+This command is reserved for future extensions.
+
+ at item AUTH
+This command is reserved for future extensions. Not yet specified as
+we don't implement it in the first phase. See my mail to gpa-dev on
+2001-10-25 about the rationale for measurements against local attacks.
@end table
@@ -615,9 +614,10 @@ assuan_set_assuan_err_source (GPG_ERR_SOURCE_DEFAULT);
@node Reading and Writing
@section How to communicate with the peer
-What would be a IPC library without the ability to read and write data?
-Not very useful. Libassuan has high level functions to take care of of
-the more boring stuff but eventfully actually data needs to be written.
+What would be an IPC library without the ability to read and write
+data? Not very useful. Libassuan has high level functions to take
+care of of the more boring stuff but eventually data needs to be
+written and read.
@noindent
The basic read and write functions are:
@@ -655,7 +655,7 @@ may get buffered until a line is full. To force sending the data out
When used by a client this flush operation does also send the
terminating @code{END} command to terminate the response on an
-``INQUIRE'' response. Note, that the function @code{assuan_transact}
+``INQUIRE'' response. Note that the function @code{assuan_transact}
takes care of sending this @code{END} itself.
@noindent
@@ -706,15 +706,15 @@ the child returns with a @var{ctx} set to @code{NULL}.
If @var{atfork} is not NULL, this function is called in the child right
after the fork and the value @var{atforkvalue} is passed as the first
argument. That function should only act if the second argument it
-received is @code{0}. Such a fork callback is useful to releases
+received is @code{0}. Such a fork callback is useful to release
additional resources not to be used by the child.
- at var{flags} controls how the function acts: With a value of @code{0} it
-expects a simple pipe based server and is in that identical to
+ at var{flags} controls how the function acts: With a value of @code{0}
+it expects a simple pipe based server and behaves similar to
@code{assuan_pipe_connect}. With a value of @code{1} a sever based on
-full-duplex pipes is expected. Such pipes are usually created using the
- at code{socketpair} function. It also enables features only available
-with such servers.
+full-duplex pipes is expected. Such pipes are usually created using
+the @code{socketpair} function. It also enables features only
+available with such servers.
@end deftypefun
@@ -723,15 +723,15 @@ Unix domain socket, the following function is used to connect to the server:
@deftypefun assuan_error_t assuan_socket_connect_ext (@w{assuan_context_t *@var{ctx}}, @w{const char *@var{name}}, @w{pid_t @var{server_pid}}, @w{unsigned int @var{flags}})
-Make a connection to the Unix domain socket @var{name} and return a new
-Assuan context at @var{ctx}. @var{server_pid} is currently not used but
-may become handy in the future; if you don't know the server's pid, pass
- at code{-1}. With @var{flags} set to @code{1} the @code{sendmsg} and
- at code{recvmesg} are used for input and output and thereby enabling the
-the use of descriptor passing.
+Make a connection to the Unix domain socket @var{name} and return a
+new Assuan context at @var{ctx}. @var{server_pid} is currently not
+used but may become handy in the future; if you don't know the
+server's pid, pass @code{-1}. With @var{flags} set to @code{1},
+ at code{sendmsg} and @code{recvmesg} are used for input and output and
+thereby enabling the the use of descriptor passing.
-Connecting a TCP server is not yet implemented. Standard URL schemes
-are reserved for @var{name} specifying a TCP server.
+Connecting to a TCP server is not yet implemented. Standard URL
+schemes are reserved for @var{name} specifying a TCP server.
@end deftypefun
@@ -751,25 +751,27 @@ to the server but won't fail on error. It is explicitly allowed to pass
@code{NULL} for @var{ctx}, in which case the function does nothing.
@end deftypefun
-Now that we have a connection to the server all work may be conveniently
-done using a couple of callbacks and the transact function:
+Now that we have a connection to the server, all work may be
+conveniently done using a couple of callbacks and the transact
+function:
@deftypefun assuan_error_t assuan_transact (@w{assuan_context_t @var{ctx}}, @w{const char *@var{command}}, @w{int (*@var{data_cb})(void *, const void *, size_t)}, @w{void *@var{data_cb_arg}}, @w{int (*@var{inquire_cb})(void*, const char *)}, @w{void *@var{inquire_cb_arg}}, @w{int (*@var{status_cb})(void*, const char *)}, @w{void *@var{status_cb_arg}})
-Here @var{ctx} is the Assuan context opened by one of the connect call.
- at var{command} is the actual one liner Assuan command. It shall not end
-with a line feed and its length is limited to @code{ASSUAN_LINELENGTH}
-(~1000 bytes)
+Here @var{ctx} is the Assuan context opened by one of the connect
+calls. @var{command} is the actual one liner Assuan command. It
+shall not end with a line feed and its length is limited to
+ at code{ASSUAN_LINELENGTH} (~1000 bytes)
@var{data_cb} is called by Libassuan for data lines; @var{data_cb_arg}
-is passed to it along with the data and the length. [fixme: needs more
-documentation].
+is passed to it along with the data and the length. [FIXME: needs
+more documentation].
@var{inquire_cb} is called by Libassuan when the server requests
-additional information from the client during the processing of a
-request. This callback shall check the provided inquriy name and send
-the data as requested back using the @code{assuan_write_data}. The server
-passed @var{inquriy_cb_arg} along with the inquiry name to the callback.
+additional information from the client while processing the command.
+This callback shall check the provided inquiry name and send the data
+as requested back using the @code{assuan_write_data}. The server
+passed @var{inquiry_cb_arg} along with the inquiry name to the
+callback.
@var{status_cb} is called by Libassuan for each status line it receives
from the server. @var{status_cb_arg} is passed along with the status
@@ -790,7 +792,8 @@ functions are used with this feature:
Send the descriptor @var{fd} to the peer using the context @var{ctx}.
Note, that calling this function with a @var{ctx} of @code{NULL} and
@var{fd} of @code{-1} is a valid runtime test to check whether
-descriptor passing is available on the platform.
+descriptor passing is available on the platform. The descriptor must
+be sent before the command is issued that makes use of the descriptor.
@end deftypefun
@@ -798,8 +801,8 @@ descriptor passing is available on the platform.
@deftypefun assuan_error_t assuan_receivefd (@w{assuan_context_t @var{ctx}}, @w{int *@var{fd}})
Receive a descriptor pending for the context @var{ctx} from the peer.
-This descriptor must be pending before this function is called. To
-accomplish this the peer needs to use @code{assuan_sendfd} before the
+The descriptor must be pending before this function is called. To
+accomplish this, the peer needs to use @code{assuan_sendfd} before the
trigger is sent (e.g. using @code{assuan_write_line ("INPUT FD")}.
@end deftypefun
@@ -830,7 +833,7 @@ The list of the implemented server commands is defined by a table like:
@end smallexample
For convenience this table is usually put after the actual command
-handlers (cmd_foo, cmd_bar) or even put inside the the command_handler.
+handlers (cmd_foo, cmd_bar) or even put inside the command_handler.
Note that commands with the name ``INPUT'' and ``OUTPUT'' do not require
a handler because Libassuan provides a default handler for them. It is
however possible to assign a custom handler.
@@ -838,7 +841,7 @@ however possible to assign a custom handler.
A prerequisite for this example code is that a client has already
connected to the server. Often there are two modes combined in one
program: A pipe based server, where a client has forked the server
-process or a Unix domain socket based server that is listening on the
+process, or a Unix domain socket based server that is listening on the
socket.
@example
@@ -866,28 +869,31 @@ command_handler (int fd)
@end example
@noindent
-This is the first part of the command hander. In case this is called as
-a pipe based server @var{fd} will be based as @code{fd} and the code
-assumes that the server's stdin and stdout are connected to a pipe. The
-initialization is thus done using
+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
+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:
@deftypefun assuan_error_t assuan_init_pipe_server (@w{assuan_context_t *@var{r_ctx}}, @w{int @var{filedes}[2]})
The function takes the two file descriptors from @var{filedes} and
-returns a new Assuan context at @var{r_ctx}. As usual a return value of
- at code{0} indicates success and a failure is indicated by a returning an
-error code. In case of error @code{NULL} will be stored at @var{r_ctx}.
-
-In case that 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 by the
-client to connect to such a server, automagically sets this variable.
+returns a new Assuan context at @var{r_ctx}. As usual, a return value
+of @code{0} indicates success and a failure is indicated by a
+returning an error code. In case of error, @code{NULL} will be stored
+at @var{r_ctx}.
+
+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
+by the client to connect to such a server, automagically sets this
+variable.
@end deftypefun
@noindent
-If a file descriptor has been passed, the assuan context gets initialized
-by
+If a file descriptor has been passed, the assuan context gets
+initialized by the function:
@deftypefun assuan_error_t assuan_init_socket_server_ext (@w{assuan_context_t *@var{r_ctx}}, @w{int @var{fd}}, @w{unsigned int @var{flags}})
@@ -897,17 +903,17 @@ associated with a socket and returns a new Assuan context at
@table @code
@item Bit 0
-When set @code{sendmsg} and @code{recvmesg} are used for input and
+If set, @code{sendmsg} and @code{recvmesg} are used for input and
output and thus enabling the use of descriptor passing.
@item Bit 1
-When set @var{fd} refers to an already accepted socket. That is,
+If set, @var{fd} refers to an already accepted socket. That is,
Libassuan won't call @var{accept} for it. It is suggested to set this
bit as it allows better control of the connection state.
@end table
-As usual a return value of @code{0} indicates success and a failure is
-indicated by a returning an error code. In case of error @code{NULL}
-will be stored at @var{r_ctx}.
+As usual, a return value of @code{0} indicates success and a failure
+is indicated by a returning an error code. In case of error,
+ at code{NULL} will be stored at @var{r_ctx}.
@end deftypefun
@noindent
@@ -915,14 +921,14 @@ After error checking, the implemented assuan commands are registered with
the server.
@example
- for (i=0; command_table[i].name; i++)
+ for (i = 0; command_table[i].name; i++)
@{
rc = assuan_register_command (ctx,
command_table[i].name,
command_table[i].handler);
if (rc)
@{
- fprintf (stderr, "register failed: %s\n", gpg_strerror(rc));
+ fprintf (stderr, "register failed: %s\n", gpg_strerror (rc));
assuan_deinit_server (ctx);
return;
@}
@@ -932,23 +938,21 @@ the server.
@deftypefun assuan_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 *)})
This registers the command named @var{cmd_string} with the Assuan
-context @var{ctx}. @var{handler} is the function called by Libassuan if
-this command is received from the client. @var{NULL} may be used
- at var{handler} to use a default handler (this only works with a few
-pre-defined commands). Note, that several default handlers have already
-been registered when the context has been created: ``NOP'', ``CANCEL'',
-``OPTION'', ``BYE'', ``AUTH'', ``RESET'' and ``END''. Although
-possible, these commands should better not be overridden by the
-application. Instead special functions should be used to get hold of
-these commands.
+context @var{ctx}. @var{handler} is the function called by Libassuan
+if this command is received from the client. @var{NULL} may be used
+for @var{handler} to use a default handler (this only works with a few
+pre-defined commands). Note that several default handlers have
+already been registered when the context has been created: ``NOP'',
+``CANCEL'', ``OPTION'', ``BYE'', ``AUTH'', ``RESET'' and ``END''. It
+is possible, but not recommended, to override these commands.
@end deftypefun
@deftypefun assuan_error_t assuan_register_post_cmd_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)}, @w{int @var{err}})
Register a function to be called right after a command has been
-processed. @var{err} is the result code from the last internal assuan
-operation and not the one returned by the handler. It may be used to
-command related cleanup.
+processed. @var{err} is the result code from the last internal assuan
+operation and not the one returned by the handler. It may be used for
+command-related cleanup.
@end deftypefun
@deftypefun assuan_error_t assuan_register_bye_notify (@w{assuan_context_t @var{ctx}}, @w{void (*@var{fnc})(assuan_context_t)})
@@ -971,12 +975,13 @@ before the standard handler for the ``RESET'' command is being called.
@deftypefun assuan_error_t assuan_register_option_handler (@w{assuan_context_t @var{ctx}}, @w{int (*@var{fnc})(assuan_context_t, const char*, const char*)})
-Register function @var{fnc} with context @var{ctx} for processing of
+Register function @var{fnc} with context @var{ctx} for processing
options. That function is being called with the context, the name and
the value of the option. Leading and trailing spaces are removed from
-the name and the value. The optional leading two dashes of the name are
-removed as well. If no value has been given, an empty string is passed.
-The function needs to return @code{0} on success or an error code.
+the name and the value. The optional leading two dashes of the name
+are removed as well. If no value has been given, an empty string is
+passed. The function needs to return @code{0} on success or an error
+code.
@end deftypefun
@@ -1005,18 +1010,18 @@ descriptor is available by calling @code{assuan_get_output_fd}.
@deftypefun assuan_error_t assuan_set_hello_line (@w{assuan_context_t @var{ctx}}, @w{const char *@var{line}})
This is not actually a register function but may be called also after
-registering commands. It changes the ``Hello'' line, send by the server
-to the client as a first response, from a default string to the string
- at var{line}. For logging purposes, it is often useful to use such a
-custom hello line which may tell version numbers and such. Linefeeds
-are allowed in this string, however, each line needs to be shorter than
-the Assuan line length limit.
+registering commands. It changes the ``Hello'' line, sent by the
+server to the client as a first response, from a default string to the
+string @var{line}. For logging purposes, it is often useful to use
+such a custom hello line which may tell version numbers and such.
+Linefeeds are allowed in this string, however, each line needs to be
+shorter than the Assuan line length limit.
@end deftypefun
@noindent
-As a last initialization step debugging may be enabled for the current
-connection. This is done using
+As a last initialization step, debugging may be enabled for the
+current connection. This is done using
@deftypefun void assuan_set_log_stream (@w{assuan_context_t @var{ctx}}, @w{FILE *@var{fp}})
@@ -1197,22 +1202,24 @@ current handler.
This is the core of the default ``INPUT'' and ``OUTPUT'' handler. It
may be used in custom commands as well to negotiate a file descriptor.
-If @var{line} contains @code{FD=@var{n}}, it returns @var{n} assuming a
-local file descriptor. If @var{line} contains just @code{FD} it returns
-a file descriptor at @var{rdf}; this file descriptor needs to have been
-sent by the client right before using @code{assuan_sendfd}.
+If @var{line} contains @code{FD=@var{n}}, it returns @var{n} in
+ at var{rfd} assuming a local file descriptor. If @var{line} contains
+just @code{FD} it returns a file descriptor at @var{rfd}; this file
+descriptor needs to have been sent by the client right before using
+ at code{assuan_sendfd}.
@end deftypefun
@deftypefun int assuan_get_input_fd (@w{assuan_context_t @var{ctx}})
-Return the file descriptor send by the client using the last ``INPUT''
+Return the file descriptor sent by the client using the last ``INPUT''
command. Returns @code{-1} if no file descriptor is available.
@end deftypefun
@deftypefun int assuan_get_output_fd (@w{assuan_context_t @var{ctx}})
-Return the file descriptor send by the client using the last ``OUTPUT''
-command. Returns @code{-1} if no file descriptor is available.
+Return the file descriptor sent by the client using the last
+``OUTPUT'' command. Returns @code{-1} if no file descriptor is
+available.
@end deftypefun
@deftypefun assuan_error_t assuan_close_input_fd (@w{assuan_context_t @var{ctx}})
@@ -1234,14 +1241,15 @@ some sanity checks and make sure that a following
@deftypefun int assuan_set_error (@w{assuan_context_t @var{ctx}}, @w{int @var{err}}, @w{const char *@var{text}})
This is a helper to provide a more descriptive error text with ``ERR''
-lines. For this to work the text needs to be stored in the context
+lines. For this to work, the text needs to be stored in the context
@var{ctx} while still being in the command handler. This function is
commonly called this way
@smallexample
return assuan_set_error (ctx, err, "commands needs 5 arguments");
@end smallexample
- at var{err} is passed through and thus the return value of the command
-handler. The provided text further explains that error code to humans.
+The value @var{err} is passed through and thus the return value of the
+command handler in the example. The provided text further explains
+that error code to humans.
@end deftypefun
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/libassuan.git
More information about the Pkg-gnupg-commit
mailing list