X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=4f7025055d142c37f459895dcda23ef8339dae75;hb=54bfcf266e208d1d8abc93885934254e852739ca;hp=36da884bc047b56314042da4c9e6151d9ef5b3cd;hpb=2b41521150b0141c6bf6730f1820e78efc90e02a;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 36da884bc..4f7025055 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,20 +1,20 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.1 2004-09-19 13:17:06 karl Exp $ +@comment $Id: gnulib.texi,v 1.21 2006-04-30 13:38:54 karl Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib -@syncodeindex pg cp @syncodeindex fn cp +@syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2004-09-19 13:17:06 $ +@set UPDATED $Date: 2006-04-30 13:38:54 $ @copying This manual is for GNU Gnulib (updated @value{UPDATED}), which is a library of common routines intended to be shared at the source level. -Copyright @copyright{} 2004 Free Software Foundation, Inc. +Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -33,7 +33,7 @@ Software Foundation raise funds for GNU development.'' @dircategory Software development @direntry -* gnulib: (gnulib). Source files to share among distributions. +* Gnulib: (gnulib). Source files to share among distributions. @end direntry @titlepage @@ -65,8 +65,9 @@ Software Foundation raise funds for GNU development.'' @node Gnulib @chapter Gnulib -This is not a real manual. It's just a place to store random notes -until someone (you?) gets around to actually writing a manual. +This manual contains some bare-bones documentation, but not much more. +It's mostly been a place to store notes until someone (you?)@ gets +around to writing a coherent manual. Getting started: @@ -80,11 +81,17 @@ Getting started: @menu * Comments:: +* Header files:: +* Quoting:: * ctime:: * inet_ntoa:: +* gcd:: * Out of memory handling:: +* Library version handling:: +* Regular expressions:: @end menu + @node Comments @section Comments @@ -98,42 +105,86 @@ it should appear in just one place unless you can ensure that the multiple copies will always remain identical. -@node ctime -@section ctime -@findex ctime +@node Header files +@section Header files + +@cindex double inclusion of header files +@cindex header file include protection +It is a tradition to use CPP tricks to avoid parsing the same header +file more than once, which might cause warnings. The trick is to wrap +the content of the header file (say, @file{foo.h}) in a block, as in: + +@example +#ifndef FOO_H +# define FOO_H +... +body of header file goes here +... +#endif /* FOO_H */ +@end example + +Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and +style. The C89 and C99 standards reserve all identifiers that begin with an +underscore and either an uppercase letter or another underscore, for +any use. Thus, in theory, an application might not safely assume that +@code{_FOO_H} has not already been defined by a library. On the other +hand, using @code{FOO_H} will likely lead the higher risk of +collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H}, +which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP +macro function). Your preference may depend on whether you consider +the header file under discussion as part of the application (which has +its own namespace for CPP symbols) or a supporting library (that +shouldn't interfere with the application's CPP symbol namespace). + +@cindex C++ header files +@cindex Header files and C++ +Adapting C header files for use in C++ applications can use another +CPP trick, as in: + +@example +# ifdef __cplusplus +extern "C" +@{ +# endif +... +body of header file goes here +... +# ifdef __cplusplus +@} +# endif +@end example + +The idea here is that @code{__cplusplus} is defined only by C++ +implementations, which will wrap the header file in an @samp{extern "C"} +block. Again, whether to use this trick is a matter of taste and +style. While the above can be seen as harmless, it could be argued +that the header file is written in C, and any C++ application using it +should explicitly use the @samp{extern "C"} block itself. Your +preference might depend on whether you consider the API exported by +your header file as something available for C programs only, or for C +and C++ programs alike. + +@subheading Include ordering -The @code{ctime} function need not be reentrant, and consequently is -not required to be thread safe. Implementations of @code{ctime} -typically write the time stamp into static buffer. If two threads -call @code{ctime} at roughly the same time, you might end up with the -wrong date in one of the threads, or some undefined string. There is -a re-entrant interface @code{ctime_r}, that take a pre-allocated -buffer and length of the buffer, and return @code{NULL} on errors. -The input buffer should be at least 26 bytes in size. The output -string is locale-independent. However, years can have more than 4 -digits if @code{time_t} is sufficiently wide, so the length of the -required output buffer is not easy to determine. Increasing the -buffer size when @code{ctime_r} return @code{NULL} is not necessarily -sufficient. The @code{NULL} return value could mean some other error -condition, which will not go away by increasing the buffer size. +When writing a gnulib module, or even in general, a good way to order +the @samp{#include} directives is the following. + +@itemize +@item First comes the #include "..." specifying the module being implemented. +@item Then come all the #include <...> of system or system-replacement headers, +in arbitrary order. +@item Then come all the #include "..." of gnulib and private headers, in +arbitrary order. +@end itemize -A more flexible function is @code{strftime}. However, note that it is -locale dependent. +@include quote.texi -@node inet_ntoa -@section inet_ntoa -@findex inet_ntoa +@include ctime.texi -The @code{inet_ntoa} function need not be reentrant, and consequently -is not required to be thread safe. Implementations of -@code{inet_ntoa} typically write the time stamp into static buffer. -If two threads call @code{inet_ntoa} at roughly the same time, you -might end up with the wrong date in one of the threads, or some -undefined string. Further, @code{inet_ntoa} is specific for -@acronym{IPv4} addresses. +@include gcd.texi -A protocol independent function is @code{inet_ntop}. +@include inet_ntoa.texi @node Out of memory handling @@ -177,14 +228,72 @@ must be taken to not allocate more memory, as that will likely also fail. -@node Invoking gnulib-tool -@chapter Invoking gnulib-tool +@node Library version handling +@section Library version handling + +The module @samp{check-version} can be useful when your gnulib +application is a system library. You will typically wrap the call to +the @code{check_version} function through a library API, your library +header file may contain: + +@example +#define STRINGPREP_VERSION "0.5.18" +... + extern const char *stringprep_check_version (const char *req_version); +@end example + +To avoid ELF symbol collisions with other libraries that use the +@samp{check-version} module, add to @file{config.h} through a +AC_DEFINE something like: + +@example +AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.]) +@end example + +The @code{stringprep_check_version} function will thus be implemented +by the @code{check_version} module. + +There are two uses of the interface. The first is a way to provide +for applications to find out the version number of the library it +uses. The application may contain diagnostic code such as: + +@example + printf ("Stringprep version: header %s library %s", + STRINGPREP_VERSION, + stringprep_check_version (NULL)); +@end example + +Separating the library and header file version can be useful when +searching for version mismatch related problems. + +The second uses is as a rudimentary test of proper library version, by +making sure the application get a library version that is the same, or +newer, than the header file used when building the application. This +doesn't catch all problems, libraries may change backwards incompatibly +in later versions, but enable applications to require a certain +minimum version before it may proceed. + +Typical uses look like: + +@example + /* Check version of libgcrypt. */ + if (!gcry_check_version (GCRYPT_VERSION)) + die ("version mismatch\n"); +@end example + + +@node Regular expressions +@section Regular expressions + +Gnulib supports many different types of regular expressions; although +the underlying features are the same or identical, the syntax used +varies. The descriptions given here for the different types are +generated automatically. + +@include regexprops-generic.texi -@pindex gnulib-tool -@cindex invoking @command{gnulib-tool} -Run @samp{gnulib-tool --help}, and use the source. -@command{gnulib-tool} is the way to import Gnulib modules. +@include gnulib-tool.texi @node Copying This Manual