m doc fix + info: communication utilties

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 314 insertions, 1 deletions

diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index 0c36968..0b60714 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -8707,8 +8707,13 @@ macros, but function-like macros and lvalue-macros use
 shorter. Inclusion-guards are formatted
 @code{MDS_LIBMDSCLIENT_*_H}.
 
+libmdsclient is not yet capable of state marshalling
+which is required for online updating to newer versions
+of the client.
+
 @menu
 * Protocol Utilties::                         Low-level functions for implementing protocols.
+* Communication Utilties::                    Low-level communication functions.
 @end menu
 
 
@@ -9009,7 +9014,7 @@ in the call to the function @code{libmds_next_message_id}.
 @code{test} is @code{NULL}.
 
 Upon successful completion zero is returned. On error
-@code{-1} is returned and @code{errno} is set the indicate
+@code{-1} is returned and @code{errno} is set to indicate
 the error.
 
 This function can fail with errno set to any error thrown
@@ -9032,6 +9037,314 @@ that uses @code{va_list} instead. These functions are suffixed
 
 
 
+@node Communication Utilties
+@section Communication Utilties
+
+@cpindex Communication foundation
+The header file @file{<libmdsclient/comm.h>} provides
+functions for connecting to the display server and
+performing thread-safe communication.
+
+@cpindex Descriptor, connection
+@cpindex Connection descriptor
+@tpindex @code{libmds_connection_t}
+@tpindex @code{struct libmds_connection}
+These functions use the structured @code{libmds_connection_t}.
+@{also known as @code{struct libmds_connection}@}. Instances
+of this structure are referred to as connection descriptors.
+This structure should be considered opaque.
+
+For these functions, the @code{this} parameter has the
+type @code{libmds_connection_initialise* restrict}.
+
+@table @asis
+@item @code{libmds_connection_initialise} [(@code{this}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_initialise}
+Initialises a connection descriptor, but does not connect
+it to the display server.
+
+Upon successful completion, zero is returned. On error,
+@code{-1} is returned and @code{errno} is set to indicate
+the error.
+
+This function may fail with @code{errno} set to
+@code{EAGAIN}, @code{ENOMEM} or @code{EPERM}, as
+specified for @code{pthread_mutex_init(3)}.
+
+@item @code{libmds_connection_create} [(@code{void}) @arrow{} @code{libmds_connection_t*}]
+@fnindex @code{libmds_connection_create}
+Wrapper for @code{libmds_connection_initialise} that
+also allocates the connection descriptor.
+
+Upon successful completion, the descriptor is returned.
+On error, @code{NULL} is returned and @code{errno} is
+set to indicate the error.
+
+This function may fail for any reason, with @code{errno}
+is to the same value, as @code{libmds_connection_initialise}.
+It may also fail with @code{errno} set to @code{ENOMEM} if
+the descriptor cannot be allocated. This is, on memory
+exhaustion.
+
+@item @code{libmds_connection_destroy} [(@code{this}) @arrow{} @code{void}]
+@fnindex @code{libmds_connection_destroy}
+Release all resources held by a connection descriptor.
+This also means that the connection to the display
+server will close. Nothing will happen if @code{this}
+is @code{NULL}.
+
+@item @code{libmds_connection_free} [(@code{this}) @arrow{} @code{void}]
+@fnindex @code{libmds_connection_free}
+Wrapper for @code{libmds_connection_destroy} that also
+calls @code{free} on the descriptor to deallocate the
+descriptor itself.
+
+@item @code{libmds_connection_establish} [(@code{this, const char** restrict display}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_establish}
+Establishes a connection to the display server.
+It is preferred to use @code{libmds_connection_establish_address},
+over using @code{libmds_connection_establish}.
+
+@code{display} must either be a pointer to a string,
+or a pointer to @code{NULL}. It pointer @code{display}
+itself must not be @code{NULL}. If @code{display} points
+to @code{NULL}, it will be update with the value of
+the environment variable @env{MDS_DISPLAY}, or left
+@code{NULL} if not set.
+
+This function will parse value @code{display} points
+to (after it has been updated if it points to @code{NULL},)
+and attempt to connect to the display server it addresses.
+
+Upon successful completetion, zero is returned. On error,
+@code{-1} is returned and @code{errno} is set to indicate
+the error.
+
+This function may fail with @code{errno} set to @code{EFAULT}
+if @env{MDS_DISPLAY} is not set (if @code{display} pointed
+to, and will in such case still point to, @code{NULL}, or
+if the display server's address is not properly formatted,
+or specifies an unsupported protocol. It may also fail with
+@code{errno} set to @code{ENAMETOOLONG} if the pathname of
+the display server's socket is too long. The function may
+also fail with any value on @code{errno} specified for
+@code{socket(2)} or @code{connect(2)}, except @code{EINTR}.
+
+@item @code{libmds_connection_establish_address} [(@code{this, const libmds_display_address_t* restrict address}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_establish_address}
+This function is an alternative to @code{libmds_connection_establish},
+which is preferred because it is easier to find out
+why it potentially failed. And it can be done reliably.
+
+Instead of a pointer to a string formated as @env{MDS_DISPLAY},
+or a pointer to @code{NULL}. This function takes a, by
+@code{libmds_parse_display_address}, preparsed address.
+
+Upon successful completetion, zero is returned. On error,
+@code{-1} is returned and @code{errno} is set to indicate
+the error.
+
+This function may fail with @code{errno} set to @code{EFAULT}
+if the address is not full set, this can happen even if
+@code{libmds_parse_display_address} returns successfully;
+it means that the display server address is not properly
+formatted or specifies an unsupported protocol. This function
+may also fail with any value on @code{errno} specified for
+@code{socket(2)} or @code{connect(2)}, except @code{EINTR}.
+
+@item @code{libmds_connection_send} [(@code{this, const char* restrict message, size_t length}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_connection_send}
+This function locks a connection descriptor and --- when
+it is entered the lock --- it will send a message to the
+display server over the connection, and ignores all
+interrupts.
+
+The message is specified by the parameter @code{message},
+and this length is specified by the parameter @code{length}.
+Note that this function treats @code{message} as a raw
+memory segment rather than as a NUL-terminated string.
+
+Undefined behaviour is invoked if @code{message} is
+@code{NULL} or if @code{length} is zero.
+
+Upon successful completeion, the number of sent bytes
+are returned. On error, zero is returned and @code{errno}
+is set to indicate the error.
+
+This function may fail with errno set to any error
+specified for @code{pthread_mutex_lock(3)}, or any
+of the errors @code{EACCES}, @code{EWOULDBLOCK} (but
+only if the socket has been modified to be nonblocking,)
+@code{EBADF}, @code{ECONNRESET} --- if connection to
+the display server is lost, --- @code{EDESTADDRREQ},
+@code{EFAULT}, @code{EINVAL}, @code{ENOBUFS}, @code{ENOMEM},
+@code{ENOTCONN}, @code{ENOTSOCK} or @code{EPIPE}, as
+specified for @code{send(2)}.
+
+@item @code{libmds_connection_send_unlocked} [(@code{this, const char* restrict message, size_t length, int continue_on_interrupt}) @arrow{} @code{size_t}]
+@fnindex @code{libmds_connection_send_unlocked}
+Variant of @code{libmds_connection_send} that does
+not perform a lock on the connection descriptor.
+This is not intended for single-threaded programs,
+rather, it is intended to be used instead of
+@code{libmds_connection_send} if the thread already
+holds a lock on the connection descriptor.
+
+This function is otherwise identical to
+@code{libmds_connection_send}, except it has one
+additional parameter: @code{continue_on_interrupt},
+and cannot fail because of failure to call
+@code{pthread_mutex_lock}. It can however also fail
+with @code{errno} set to @code{EINTR} if
+@code{continue_on_interrupt} is zero.
+
+The function will continue sending the message
+if it gets interrupted by a signal only if
+@code{continue_on_interrupt} is non-zero.
+@end table
+
+@file{<libmdsclient/comm.h>} also provides a few
+macros for use with connection descriptors.
+For these macros, the @code{this} parameter has the
+type @code{libmds_connection_initialise* restrict}.
+
+@table @asis
+@item @code{libmds_connection_lock} [(@code{this}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_lock}
+Wrapper for @code{pthread_mutex_lock} that locks
+@code{this}'s mutex. One difference from the wrapped
+function, is that rather than returning a value for
+@code{errno}, it sets @code{errno} and returns zero
+on success and @code{-1} on failure.@footnote{POSIX
+threading and reenterant functions has a weird
+property of returning an error code rather than
+setting it on @code{errno}, despite that all other
+C functions sets @code{errno} (provided that they
+have error codes specified in @file{<errno.h>}.)}
+
+@item @code{libmds_connection_trylock} [(@code{this}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_trylock}
+Wrapper for @code{pthread_mutex_trylock} that locks
+@code{this}'s mutex. One difference from the wrapped
+function, is that rather than returning a value for
+@code{errno}, it sets @code{errno} and returns zero
+on success and @code{-1} on failure.
+
+@item @code{libmds_connection_timedlock} [(@code{this, const struct timespec *restrict deadline}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_timedlock}
+Wrapper for @code{pthread_mutex_timedlock} that locks
+@code{this}'s mutex. One difference from the wrapped
+function, is that rather than returning a value for
+@code{errno}, it sets @code{errno} and returns zero
+on success and @code{-1} on failure.
+Neither parameter may be @code{NULL}.
+
+@item @code{libmds_connection_unlock} [(@code{this}) @arrow{} @code{int}]
+@fnindex @code{libmds_connection_unlock}
+Wrapper for @code{pthread_mutex_unlock} that unlocks
+@code{this}'s mutex. One difference from the wrapped
+function, is that rather than returning a value for
+@code{errno}, it sets @code{errno} and returns zero
+on success and @code{-1} on failure.
+
+@item @code{LIBMDS_HEADER_CLIENT_ID} [(@code{this})]
+@fnindex @code{LIBMDS_HEADER_CLIENT_ID}
+@fnindex @code{libmds_compose}
+Macro to be used with @code{libmds_compose}, to
+add the connection's client ID to a message.
+
+@item @code{LIBMDS_HEADER_MESSAGE_ID} [(@code{this})]
+@fnindex @code{LIBMDS_HEADER_MESSAGE_ID}
+@fnindex @code{libmds_next_message_id}
+Macro to be used with @code{libmds_compose}, to
+add the connection's next message ID to a message.
+@code{libmds_next_message_id} shall have been called
+prior to using this macro.
+
+@item @code{LIBMDS_HEADERS_STANDARD} [(@code{this})]
+@fnindex @code{LIBMDS_HEADERS_STANDARD}
+Macro that can be used in place of using both
+@code{LIBMDS_HEADER_CLIENT_ID} and
+@code{LIBMDS_HEADER_MESSAGE_ID}.
+@end table
+
+@file{<libmdsclient/comm.h>} includes @file{<libmdsclient/address.h>},
+with defines the structure @code{libmds_display_address_t}
+@{also known as @code{struct libmds_display_address}@},
+and the function @code{libmds_parse_display_address}.
+
+@tpindex @code{libmds_display_address_t}
+@tpindex @code{struct libmds_display_address}
+@code{libmds_display_address_t} holds parsing results
+from @code{libmds_parse_display_address}. Its members
+are:
+
+@table @asis
+@item @code{domain} [@code{int}]
+The domain (protocol family), that is the first
+argument for @code{socket(2)}. This is a value
+whose constant is prefixed @code{PF_}.@footnote{It
+is common to use @code{AF_}-constants instead,
+however this practice is not portable.}
+@code{-1} if not detected.
+
+@item @code{type} [@code{int}]
+The socket type, that is the second argument
+for @code{socket(2)}. This is a value
+whose constant is prefixed @code{SOCK_}.
+@code{-1} if not detected.
+
+@item @code{protocol} [@code{int}]
+The protocol, that is the third argument
+for @code{socket(2)}. This is a value
+whose constant is affixed @code{PROTO_}.
+Zero can be used for the default protocol.
+For example, for stream IP sockets, the protocol
+can only be TCP, thus zero would indicate
+@code{IPPROTO_TCP}.
+@code{-1} if not detected.
+
+@item @code{address} [@code{struct sockaddr*}]
+The address. @code{NULL} if not detected.
+You are responsible for freeing this.
+
+@item @code{address_len} [@code{socklen_t}]
+The allocation size of @code{.address}.
+This value may be set even if @code{address}
+is @code{NULL}.
+
+@item @code{gai_error} [@code{int}]
+Code for an error that has occured when parsing
+the address, whose description can be retrieved
+using @code{gia_strerror}, zero if none.
+@end table
+
+@fnindex @code{libmds_parse_display_address}
+The function @code{libmds_parse_display_address}
+is used to parse the a display address string:
+
+@table @asis
+@item @code{libmds_parse_display_address} [(@code{const char* restrict display, libmds_display_address_t* restrict address}) @arrow{} @code{int}]
+@code{display} should be the address of the display
+server, formatted as a value for @env{MDS_DISPLAY}.
+
+The address of the display will be stored in @code{*address}.
+
+Neither parameter may be @code{NULL}.
+
+Upon successful completion, zero is returned. On error,
+@code{-1} is returned and errno is set to indicate the
+error. Parsing-failure is not considered an error,
+instead data that could not retrieved from the address
+string will be set to @code{-1} or @code{NULL}.
+
+This function may fail with @code{errno} set to
+@code{ENOMEM} on memory exhaustion, or @code{ENAMETOOLONG}
+if the addressed socket's filename is too long.
+@end table
+
+
+
 @node libmdslltk
 @chapter libmdslltk