doc/gnulib.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment $Id: gnulib.texi,v 1.19 2005-09-19 15:48:03 haible Exp $
   3 @comment %**start of header
   4 @setfilename gnulib.info
   5 @settitle GNU Gnulib
   6 @syncodeindex fn cp
   7 @syncodeindex pg cp
   8 @comment %**end of header
   9
  10 @set UPDATED $Date: 2005-09-19 15:48:03 $
  11
  12 @copying
  13 This manual is for GNU Gnulib (updated @value{UPDATED}),
  14 which is a library of common routines intended to be shared at the
  15 source level.
  16
  17 Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc.
  18
  19 @quotation
  20 Permission is granted to copy, distribute and/or modify this document
  21 under the terms of the GNU Free Documentation License, Version 1.1 or
  22 any later version published by the Free Software Foundation; with no
  23 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  24 and with the Back-Cover Texts as in (a) below.  A copy of the
  25 license is included in the section entitled ``GNU Free Documentation
  26 License.''
  27
  28 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
  29 this GNU Manual, like GNU software.  Copies published by the Free
  30 Software Foundation raise funds for GNU development.''
  31 @end quotation
  32 @end copying
  33
  34 @dircategory Software development
  35 @direntry
  36 * Gnulib: (gnulib).             Source files to share among distributions.
  37 @end direntry
  38
  39 @titlepage
  40 @title GNU Gnulib
  41 @subtitle updated @value{UPDATED}
  42 @author @email{bug-gnulib@@gnu.org}
  43 @page
  44 @vskip 0pt plus 1filll
  45 @insertcopying
  46 @end titlepage
  47
  48 @contents
  49
  50 @ifnottex
  51 @node Top
  52 @top GNU Gnulib
  53
  54 @insertcopying
  55 @end ifnottex
  56
  57 @menu
  58 * Gnulib::
  59 * Invoking gnulib-tool::
  60 * Copying This Manual::
  61 * Index::
  62 @end menu
  63
  64
  65 @node Gnulib
  66 @chapter Gnulib
  67
  68 This manual contains some bare-bones documentation, but not much more.
  69 It's mostly been a place to store notes until someone (you?)@ gets
  70 around to writing a coherent manual.
  71
  72 Getting started:
  73
  74 @itemize
  75 @item Gnulib is hosted at Savannah:
  76       @url{http://savannah.gnu.org/projects/gnulib}.  Get the sources
  77       through CVS from there.
  78 @item The Gnulib home page:
  79       @url{http://www.gnu.org/software/gnulib/}.
  80 @end itemize
  81
  82 @menu
  83 * Comments::
  84 * Header files::
  85 * Quoting::
  86 * ctime::
  87 * inet_ntoa::
  88 * Out of memory handling::
  89 * Library version handling::
  90 * Regular expressions::
  91 @end menu
  92
  93
  94 @node Comments
  95 @section Comments
  96
  97 @cindex comments describing functions
  98 @cindex describing functions, locating
  99 Where to put comments describing functions: Because of risk of
 100 divergence, we prefer to keep most function describing comments in
 101 only one place: just above the actual function definition.  Some
 102 people prefer to put that documentation in the .h file.  In any case,
 103 it should appear in just one place unless you can ensure that the
 104 multiple copies will always remain identical.
 105
 106
 107 @node Header files
 108 @section Header files
 109
 110 @cindex double inclusion of header files
 111 @cindex header file include protection
 112 It is a tradition to use CPP tricks to avoid parsing the same header
 113 file more than once, which might cause warnings.  The trick is to wrap
 114 the content of the header file (say, @file{foo.h}) in a block, as in:
 115
 116 @example
 117 #ifndef FOO_H
 118 # define FOO_H
 119 ...
 120 body of header file goes here
 121 ...
 122 #endif /* FOO_H */
 123 @end example
 124
 125 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
 126 style.  The C89 and C99 standards reserve all identifiers that begin with an
 127 underscore and either an uppercase letter or another underscore, for
 128 any use.  Thus, in theory, an application might not safely assume that
 129 @code{_FOO_H} has not already been defined by a library.  On the other
 130 hand, using @code{FOO_H} will likely lead the higher risk of
 131 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
 132 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
 133 macro function).  Your preference may depend on whether you consider
 134 the header file under discussion as part of the application (which has
 135 its own namespace for CPP symbols) or a supporting library (that
 136 shouldn't interfere with the application's CPP symbol namespace).
 137
 138 @cindex C++ header files
 139 @cindex Header files and C++
 140 Adapting C header files for use in C++ applications can use another
 141 CPP trick, as in:
 142
 143 @example
 144 # ifdef __cplusplus
 145 extern "C"
 146 @{
 147 # endif
 148 ...
 149 body of header file goes here
 150 ...
 151 # ifdef __cplusplus
 152 @}
 153 # endif
 154 @end example
 155
 156 The idea here is that @code{__cplusplus} is defined only by C++
 157 implementations, which will wrap the header file in an @samp{extern "C"}
 158 block.  Again, whether to use this trick is a matter of taste and
 159 style.  While the above can be seen as harmless, it could be argued
 160 that the header file is written in C, and any C++ application using it
 161 should explicitly use the @samp{extern "C"} block itself.  Your
 162 preference might depend on whether you consider the API exported by
 163 your header file as something available for C programs only, or for C
 164 and C++ programs alike.
 165
 166 @subheading Include ordering
 167
 168 When writing a gnulib module, or even in general, a good way to order
 169 the @samp{#include} directives is the following.
 170
 171 @itemize
 172 @item First comes the #include "..." specifying the module being implemented.
 173 @item Then come all the #include <...> of system or system-replacement headers,
 174 in arbitrary order.
 175 @item Then come all the #include "..." of gnulib and private headers, in
 176 arbitrary order.
 177 @end itemize
 178
 179
 180 @include quote.texi
 181
 182
 183 @include ctime.texi
 184
 185
 186 @include inet_ntoa.texi
 187
 188
 189 @node Out of memory handling
 190 @section Out of memory handling
 191
 192 @cindex Out of Memory handling
 193 @cindex Memory allocation failure
 194 The GSS API does not have a standard error code for the out of memory
 195 error condition.  Instead of adding a non-standard error code, this
 196 library has chosen to adopt a different strategy.  Out of memory
 197 handling happens in rare situations, but performing the out of memory
 198 error handling after almost all API function invocations pollute your
 199 source code and might make it harder to spot more serious problems.
 200 The strategy chosen improve code readability and robustness.
 201
 202 @cindex Aborting execution
 203 For most applications, aborting the application with an error message
 204 when the out of memory situation occur is the best that can be wished
 205 for.  This is how the library behaves by default.
 206
 207 @vindex xalloc_fail_func
 208 However, we realize that some applications may not want to have the
 209 GSS library abort execution in any situation.  The GSS library support
 210 a hook to let the application regain control and perform its own
 211 cleanups when an out of memory situation has occured.  The application
 212 can define a function (having a @code{void} prototype, i.e., no return
 213 value and no parameters) and set the library variable
 214 @code{xalloc_fail_func} to that function.  The variable should be
 215 declared as follows.
 216
 217 @example
 218 extern void (*xalloc_fail_func) (void);
 219 @end example
 220
 221 The GSS library will invoke this function if an out of memory error
 222 occurs.  Note that after this the GSS library is in an undefined
 223 state, so you must unload or restart the application to continue call
 224 GSS library functions.  The hook is only intended to allow the
 225 application to log the situation in a special way.  Of course, care
 226 must be taken to not allocate more memory, as that will likely also
 227 fail.
 228
 229
 230 @node Library version handling
 231 @section Library version handling
 232
 233 The module @samp{check-version} can be useful when your gnulib
 234 application is a system library.  You will typically wrap the call to
 235 the @code{check_version} function through a library API, your library
 236 header file may contain:
 237
 238 @example
 239 #define STRINGPREP_VERSION "0.5.18"
 240 ...
 241   extern const char *stringprep_check_version (const char *req_version);
 242 @end example
 243
 244 To avoid ELF symbol collisions with other libraries that use the
 245 @samp{check-version} module, add to @file{config.h} through a
 246 AC_DEFINE something like:
 247
 248 @example
 249 AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])
 250 @end example
 251
 252 The @code{stringprep_check_version} function will thus be implemented
 253 by the @code{check_version} module.
 254
 255 There are two uses of the interface.  The first is a way to provide
 256 for applications to find out the version number of the library it
 257 uses.  The application may contain diagnostic code such as:
 258
 259 @example
 260   printf ("Stringprep version: header %s library %s",
 261           STRINGPREP_VERSION,
 262           stringprep_check_version (NULL));
 263 @end example
 264
 265 Separating the library and header file version can be useful when
 266 searching for version mismatch related problems.
 267
 268 The second uses is as a rudimentary test of proper library version, by
 269 making sure the application get a library version that is the same, or
 270 newer, than the header file used when building the application.  This
 271 doesn't catch all problems, libraries may change backwards incompatibly
 272 in later versions, but enable applications to require a certain
 273 minimum version before it may proceed.
 274
 275 Typical uses look like:
 276
 277 @example
 278        /* Check version of libgcrypt. */
 279        if (!gcry_check_version (GCRYPT_VERSION))
 280          die ("version mismatch\n");
 281 @end example
 282
 283
 284 @node Regular expressions
 285 @section Regular expressions
 286
 287 Gnulib supports many different types of regular expressions; although
 288 the underlying features are the same or identical, the syntax used
 289 varies.  The descriptions given here for the different types are
 290 generated automatically.
 291
 292 @include regexprops-generic.texi
 293
 294
 295 @include gnulib-tool.texi
 296
 297
 298 @node Copying This Manual
 299 @appendix Copying This Manual
 300
 301 @menu
 302 * GNU Free Documentation License::  License for copying this manual.
 303 @end menu
 304
 305 @include fdl.texi
 306
 307
 308 @node Index
 309 @unnumbered Index
 310
 311 @printindex cp
 312
 313 @bye