diff options
| -rw-r--r-- | doc/info/mds.texinfo | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index a5b5329..25790af 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -54,6 +54,7 @@ Texts. A copy of the license is included in the section entitled * Overview:: Brief overview of @command{mds}. * Architecture:: Architectural overview of @command{mds}. * Protocol:: The @command{mds} procotol. +* libmdsserver:: Overview of @command{libmdsserver}. * GNU Free Documentation License:: Copying and sharing this manual. @end menu @@ -758,6 +759,143 @@ Command: keyboard-enumeration\n +@node libmdsserver +@chapter libmdsserver + +libmdsserver is library written for the reference +implementation of the @command{mds} servers. +libmdsserver does not contain support or any +protocols, rather it contains auxiliary functions, +macros, data structures such as linked lists and +hash tables, and support the basics of the message +passing protocol: receiving message and decode it +into headers and payloads. + +The header file @file{<libmdsserver/macros.h>} +contains macros for readability and code reduction, +it also contains macros and definitions for portability; +they may either provide portability by nature, or +provide one place to do modifications to port the +system. + +@table @asis +@item @code{xsnprintf} [(@code{char[] buffer, char* format, ...}) @arrow{} @code{int}] +This is a wrapper for @code{snprintf} that allows you +to forget about the buffer size. When you know how long +a string can be, you should use @code{sprintf}. But when +you cannot know for sure you should use @code{xsnprintf}. +@code{xsnprintf} works exactly as @code{sprintf}, but +it will require that the first argument is defined +using @code{[]} rather than @code{*} because it will use +this to find out how large the buffer is so it can call +@code{snprintf} with that size. + +@item @code{eprint} [(@code{const char* format}) @arrow{} @code{int}] +A wrapper for @code{fprintf} that prints a string prefixed +with the value value of @code{*argv} to @code{stderr}. +Because @code{eprintf} naïvely wraps @code{fprintf}, all +`%':s in the string must be duplicated. + +@item @code{eprintf} [(@code{const char* format, ...}) @arrow{} @code{int}] +@code{eprint} extends @code{eprint} with variadic arguments +that can be used to insert values into the format string +just like you can do in @code{fprintf}. + +@item @code{with_mutex} [(@code{pthread_mutex_t mutex, instructions})] +Wraps @code{instructions} with @code{errno = pthread_mutex_lock(mutex);} +and @code{errno = pthread_mutex_unlock(mutex);}, so a set of +instructions can be invoked inside mutex protection. + +@item @code{with_mutex_if} [(@code{pthread_mutex_t mutex, condition, instructions})] +An alternative to @code{with_mutex} where @code{instructions} +is wrapped around @code{if (condition)} which in turn is +wrapped inside the mutex protection. + +@item @code{max} [(@code{a, b})] +Returns the higher value of @code{a} and @code{b}. + +@item @code{min} [(@code{a, b})] +Returns the lower value of @code{a} and @code{b}. + +@item @code{buf_cast} [(@code{char* buffer, type, size_t index})] +Casts @code{buffer} to a @code{type} buffer and +subscripts to the @code{index}:th element. You +can either use this function as a getter or a +setter. + +@item @code{buf_set} [(@code{char* buffer, type, size_t index, type variable}) @arrow{} @code{type}] +Wrapper for @code{buf_cast} that sets the addressed +element to the value of @code{variable}. + +@item @code{buf_get} [(@code{const char* buffer, type, size_t index, type variable}) @arrow{} @code{type}] +Wrapper for @code{buf_cast} that sets the value of +@code{variable} to the value of the addressed element. + +@item @code{buf_next} [(@code{char* buffer, type, size_t count}) @arrow{} @code{char*}] +Increases the pointer @code{buffer} by the size of +@code{type} @code{count} types. + +@item @code{buf_prev} [(@code{char* buffer, type, size_t count}) @arrow{} @code{char*}] +Decreases the pointer @code{buffer} by the size of +@code{type} @code{count} types. + +@item @code{buf_set_next} [(@code{char* buffer, type, type variable}) @arrow{} @code{type}] +@example +buf_set(buffer, type, 0, variable), +buf_next(buffer, type, 1); +@end example + +@item @code{buf_get_next} [(@code{char* buffer, type, type variable}) @arrow{} @code{type}] +@example +buf_get(buffer, type, 0, variable), +buf_next(buffer, type, 1); +@end example + +@item @code{strequals} [(@code{const char* a, const char* b}) @arrow{} @code{int}] +Evaluates whether the strings @code{a} and @code{b} +are equals, neither may be @code{NULL}. + +@item @code{startswith} [(@code{const char* haystack, const char* needle}) @arrow{} @code{int}] +Evaluates whether the string @code{haystack} +starts with the string @code{needle}, neither +may be @code{NULL}. + +@item @code{drop_privileges} [() @arrow{} @code{int}] +Sets the effective user to the real user and the +effective group to the real group. This is used +by most servers and ensure that they are not +running with unnecessary privileges. Returns zero +on and only on success. + +@item @code{monotone} [(@code{struct timespec* time_slot}) @arrow{} @code{int}] +Stores the time of an unspecified monotonic clock +into @code{time_slot}. Returns zero on and only on +success. + +@item @code{close_files} [(@code{condition}) @arrow{} @code{void}] +Closes all file descriptors named by a variable +@code{fd} for which @code{condition} evalutes +to non-zero. + +@item @code{xfree} [(@code{void** array, size_t elements}) @arrow{} @code{void}] +Calls @code{free} on the first @code{elements} +elements in @code{array}, and than calls +@code{free} on @code{array}. This macro +requires @code{size_t i} is declared. + +@item @code{xmalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] +@item @code{xcalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] +@item @code{xrealloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}] +@item @code{growalloc} [(@code{type* old, type* var, size_t elements, type}) @arrow{} @code{int}] +@item @code{xperror} [(@code{const char* str}) @arrow{} @code{void}] +@item @code{fail_if} [(@code{condition}) @arrow{} @code{void}] +@item @code{exit_if} [(@code{condition, instructions}) @arrow{} @code{void}] +@end table + +@c SIGDANGER SIGUPDATE macro-bits.h + + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl.texinfo |