info: macros.h

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

1 files changed, 123 insertions, 1 deletions

diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index 25790af..ee10a47 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -884,15 +884,137 @@ elements in @code{array}, and than calls
 requires @code{size_t i} is declared.
 
 @item @code{xmalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}]
+Allocates a @code{type*} with @code{elements}
+elements and store the allocated pointer to
+@code{var}. Returns zero on and only on success.
+
 @item @code{xcalloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}]
+Allocates a zero-initialised @code{type*} with
+@code{elements} elements and store the allocated
+pointer to @code{var}. Returns zero on and only
+on success.
+
 @item @code{xrealloc} [(@code{type* var, size_t elements, type}) @arrow{} @code{int}]
+Reallocates @code{var} and updates the variable
+@code{var} accordingly. @code{var} will be
+allocated to have @code{elements} elements
+of the type @code{type}. If @code{var} is
+@code{NULL} a new allocation is created. If
+@code{elements} is zero, @code{var} will
+be deallocated. Returns zero on and only
+on success. On failure, @code{var} will be
+@code{NULL}, so you must store the @code{var}
+into another variable in case this macro
+fails.
+
 @item @code{growalloc} [(@code{type* old, type* var, size_t elements, type}) @arrow{} @code{int}]
+When using this macro @code{var} should
+be a @code{type*} pointer allocated for
+@code{elements} elements of the type
+@code{type}. This macro will reallocate
+@code{var} to contain twice as many elements
+and update @code{elements} accordingly.
+On failure nothing changes. You must specify
+an auxiliary @code{type*} variable and
+specify it in as the @code{old} parameter.
+Returns zero on and only on success.
+
 @item @code{xperror} [(@code{const char* str}) @arrow{} @code{void}]
+Invokes @code{perror(str)} if and only if
+@code{errno} is non-zero and then sets
+@code{errno} to zero. @code{str} should
+unless you have a specific reason be
+@code{*argv}.
+
 @item @code{fail_if} [(@code{condition}) @arrow{} @code{void}]
+If @code{condition} is satisfied, a jump
+is made to the label @code{pfail}.
+@code{pfail:} should be used for calling
+@code{xperror} and return @code{-1}.
+
 @item @code{exit_if} [(@code{condition, instructions}) @arrow{} @code{void}]
+If @code{condition} is satisfied,
+@code{instructions} is invoked and
+@code{1} is @code{return}:ed.
 @end table
 
-@c SIGDANGER SIGUPDATE macro-bits.h
+Additionally, @file{<libmdsserver/macros.h>}
+defines any missing signal name:
+currenly @code{SIGDANGER} and
+@code{SIGUPDATE}, and by inclusion of
+@file{<libmdsserver/macro-bits.h>}, variants
+of @code{atoi} for portability and
+convenience:
+
+@table @code
+@item atoz
+Parse a human readable @code{const char*}
+10-radix integer to an @code{size_t}.
+
+@item atosz
+Parse a human readable @code{const char*}
+10-radix integer to an @code{ssize_t}.
+
+@item atoh
+Parse a human readable @code{const char*}
+10-radix integer to an @code{short int}.
+
+@item atouh
+Parse a human readable @code{const char*}
+10-radix integer to an @code{unsigned short int}.
+
+@item atou
+Parse a human readable @code{const char*}
+10-radix integer to an @code{unsigned int}.
+
+@item atoul
+Parse a human readable @code{const char*}
+10-radix integer to an @code{unsigned long int}.
+
+@item atoull
+Parse a human readable @code{const char*}
+10-radix integer to an @code{unsigned long long int}.
+
+@item ato8
+Parse a human readable @code{const char*}
+10-radix integer to an @code{int8_t}.
+
+@item atou8
+Parse a human readable @code{const char*}
+10-radix integer to an @code{uint8_t}.
+
+@item ato16
+Parse a human readable @code{const char*}
+10-radix integer to an @code{int16_t}.
+
+@item atou16
+Parse a human readable @code{const char*}
+10-radix integer to an @code{uint16_t}.
+
+@item ato32
+Parse a human readable @code{const char*}
+10-radix integer to an @code{int32_t}.
+
+@item atou32
+Parse a human readable @code{const char*}
+10-radix integer to an @code{uint32_t}.
+
+@item ato64
+Parse a human readable @code{const char*}
+10-radix integer to an @code{int64_t}.
+
+@item atou64
+Parse a human readable @code{const char*}
+10-radix integer to an @code{uint64_t}.
+
+@item atoj
+Parse a human readable @code{const char*}
+10-radix integer to an @code{intmax_t}.
+
+@item atouj
+Parse a human readable @code{const char*}
+10-radix integer to an @code{uintmax_t}.
+@end table