1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.14 2005-07-27 00:16:01 karl Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2005-07-27 00:16:01 $
13 This manual is for GNU Gnulib (updated @value{UPDATED}),
14 which is a library of common routines intended to be shared at the
17 Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc.
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
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.''
34 @dircategory Software development
36 * Gnulib: (gnulib). Source files to share among distributions.
41 @subtitle updated @value{UPDATED}
42 @author @email{bug-gnulib@@gnu.org}
44 @vskip 0pt plus 1filll
59 * Invoking gnulib-tool::
60 * Copying This Manual::
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.
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/}.
88 * Out of memory handling::
89 * Library version handling::
90 * Regular expressions::
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.
108 @section Header files
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:
120 body of header file goes here
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).
138 @cindex C++ header files
139 @cindex Header files and C++
140 Adapting C header files for use in C++ applications can use another
149 body of header file goes here
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.
166 @subheading Include ordering
168 When writing a gnulib module, or even in general, a good way to order
169 the @samp{#include} directives is the following.
172 @item First comes the #include "..." specifying the module being implemented.
173 @item Then come all the #include <...> of system or system-replacement headers,
175 @item Then come all the #include "..." of gnulib and private headers, in
187 Gnulib provides @samp{quote} and @samp{quotearg} modules to help with
188 quoting text, such as file names, in messages to the user. Here's an
189 example of using @samp{quote}:
194 error (0, errno, _("cannot change owner of %s"), quote (fname));
200 error (0, errno, _("cannot change owner of `%s'"), fname);
203 @noindent in that @code{quote} escapes unusual characters in
204 @code{fname}, e.g., @samp{'} and control characters like @samp{\n}.
207 However, a caveat: @code{quote} reuses the storage that it returns.
208 Hence if you need more than one thing quoted at the same time, you
209 need to use @code{quote_n}.
211 @findex quotearg_alloc
212 Also, the quote module is not suited for multithreaded applications.
213 In that case, you have to use @code{quotearg_alloc}, defined in the
214 @samp{quotearg} module, which is decidedly less convenient.
221 The @code{ctime} function need not be reentrant, and consequently is
222 not required to be thread safe. Implementations of @code{ctime}
223 typically write the time stamp into static buffer. If two threads
224 call @code{ctime} at roughly the same time, you might end up with the
225 wrong date in one of the threads, or some undefined string. There is
226 a re-entrant interface @code{ctime_r}, that take a pre-allocated
227 buffer and length of the buffer, and return @code{NULL} on errors.
228 The input buffer should be at least 26 bytes in size. The output
229 string is locale-independent. However, years can have more than 4
230 digits if @code{time_t} is sufficiently wide, so the length of the
231 required output buffer is not easy to determine. Increasing the
232 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
233 sufficient. The @code{NULL} return value could mean some other error
234 condition, which will not go away by increasing the buffer size.
236 A more flexible function is @code{strftime}. However, note that it is
244 The @code{inet_ntoa} function need not be reentrant, and consequently
245 is not required to be thread safe. Implementations of
246 @code{inet_ntoa} typically write the time stamp into static buffer.
247 If two threads call @code{inet_ntoa} at roughly the same time, you
248 might end up with the wrong date in one of the threads, or some
249 undefined string. Further, @code{inet_ntoa} is specific for
250 @acronym{IPv4} addresses.
252 A protocol independent function is @code{inet_ntop}.
255 @node Out of memory handling
256 @section Out of memory handling
258 @cindex Out of Memory handling
259 @cindex Memory allocation failure
260 The GSS API does not have a standard error code for the out of memory
261 error condition. Instead of adding a non-standard error code, this
262 library has chosen to adopt a different strategy. Out of memory
263 handling happens in rare situations, but performing the out of memory
264 error handling after almost all API function invocations pollute your
265 source code and might make it harder to spot more serious problems.
266 The strategy chosen improve code readability and robustness.
268 @cindex Aborting execution
269 For most applications, aborting the application with an error message
270 when the out of memory situation occur is the best that can be wished
271 for. This is how the library behaves by default.
273 @vindex xalloc_fail_func
274 However, we realize that some applications may not want to have the
275 GSS library abort execution in any situation. The GSS library support
276 a hook to let the application regain control and perform its own
277 cleanups when an out of memory situation has occured. The application
278 can define a function (having a @code{void} prototype, i.e., no return
279 value and no parameters) and set the library variable
280 @code{xalloc_fail_func} to that function. The variable should be
284 extern void (*xalloc_fail_func) (void);
287 The GSS library will invoke this function if an out of memory error
288 occurs. Note that after this the GSS library is in an undefined
289 state, so you must unload or restart the application to continue call
290 GSS library functions. The hook is only intended to allow the
291 application to log the situation in a special way. Of course, care
292 must be taken to not allocate more memory, as that will likely also
296 @node Library version handling
297 @section Library version handling
299 The module @samp{check-version} can be useful when your gnulib
300 application is a system library. You will typically wrap the call to
301 the @code{check_version} function through a library API, your library
302 header file may contain:
305 #define STRINGPREP_VERSION "0.5.18"
307 extern const char *stringprep_check_version (const char *req_version);
310 To avoid ELF symbol collisions with other libraries that use the
311 @samp{check-version} module, add to @file{config.h} through a
312 AC_DEFINE something like:
315 AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])
318 The @code{stringprep_check_version} function will thus be implemented
319 by the @code{check_version} module.
321 There are two uses of the interface. The first is a way to provide
322 for applications to find out the version number of the library it
323 uses. The application may contain diagnostic code such as:
326 printf ("Stringprep version: header %s library %s",
328 stringprep_check_version (NULL));
331 Separating the library and header file version can be useful when
332 searching for version mismatch related problems.
334 The second uses is as a rudimentary test of proper library version, by
335 making sure the application get a library version that is the same, or
336 newer, than the header file used when building the application. This
337 doesn't catch all problems, libraries may change backwards incompatibly
338 in later versions, but enable applications to require a certain
339 minimum version before it may proceed.
341 Typical uses look like:
344 /* Check version of libgcrypt. */
345 if (!gcry_check_version (GCRYPT_VERSION))
346 die ("version mismatch\n");
350 @node Regular expressions
351 @section Regular expressions
353 Gnulib supports many different types of regular expressions; although
354 the underlying features are the same or identical, the syntax used
355 varies. The descriptions given here for the different types are
356 generated automatically.
358 @include regexprops-generic.texi
361 @node Invoking gnulib-tool
362 @chapter Invoking gnulib-tool
365 @cindex invoking @command{gnulib-tool}
367 Run @samp{gnulib-tool --help}, and use the source.
368 @command{gnulib-tool} is the way to import Gnulib modules.
371 * Initial import:: First import of Gnulib modules.
372 * Importing updated files:: Subsequent imports.
373 * Finishing touches:: Simplifying imports.
378 @section Initial import
379 @cindex initial import
381 Gnulib assumes your project uses Autoconf and Automake. Invoking
382 @samp{gnulib-tool --import} will copy source files, create a
383 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
384 Autoconf M4 macro declarations used by @file{configure.ac}.
386 Our example will be a library that uses Autoconf, Automake and
387 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
388 the package portable to C89 (which doesn't have @code{strdup}).
391 ~/src/libfoo$ gnulib-tool --import strdup
392 Module list with included dependencies:
399 Creating ./lib/Makefile.am...
400 Creating ./m4/gnulib.m4...
403 You may need to add #include directives for the following .h files.
406 Don't forget to add "lib/Makefile"
407 to AC_CONFIG_FILES in "./configure.ac" and to mention
408 "lib" in SUBDIRS in some Makefile.am.
412 By default, the source code is copied into @file{lib/} and the M4
413 macros in @file{m4/}. You can override these paths by using
414 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
415 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
416 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
417 Some modules also provide other files necessary
418 for building. These files are copied into the directory specified
419 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
420 @code{--aux-dir=DIRECTORY} option. If neither is specified, the
421 current directory is assumed.
423 @code{gnulib-tool} can make symbolic links instead
424 of copying the source files. Use the @code{--symbolic}
425 (or @code{-s} for short) option to do this.
427 @code{gnulib-tool} will overwrite any pre-existing files, in
428 particular @file{Makefile.am}. Unfortunately, separating the
429 generated @file{Makefile.am} content (for building the gnulib library)
430 into a separate file, say @file{gnulib.mk}, that could be included
431 by your handwritten @file{Makefile.am} is not possible, due to how
432 variable assignments are handled by Automake.
434 Consequently, it can be a good idea to chose directories that are not
435 already used by your projects, to separate gnulib imported files from
436 your own files. This approach can also be useful if you want to avoid
437 conflicts between other tools (e.g., @code{getextize} that also copy
438 M4 files into your package. Simon Josefsson successfully uses a source
439 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
442 A few manual steps are required to finish the initial import.
444 First, you need to make sure Autoconf can find the macro definitions
445 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
446 top-level @file{Makefile.am} file, as in:
449 ACLOCAL_AMFLAGS = -I m4
452 Naturally, replace @file{m4} with the value from @code{--m4-base} or
453 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
456 ACLOCAL_AMFLAGS = -I gl/m4
459 You are now ready to call the M4 macros in @code{gnulib.m4} from
460 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
461 as possible after verifying that the C compiler is working.
462 Typically, this is immediately after @code{AC_PROG_CC}, as in:
471 The core part of the gnulib checks are done by the macro
472 @code{gl_INIT}. Place it further down in the file, typically where
473 you normally check for header files or functions. Or in a separate
474 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
484 @code{gl_INIT} will in turn call the macros related with the
485 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
486 or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or
487 @code{AM_FUNC_GETLINE} so there is no need to call those macros yourself
488 when you use the corresponding gnulib modules.
490 You must also make sure that the gnulib library is built. Add the
491 @code{Makefile} in the gnulib source base directory to
492 @code{AC_CONFIG_FILES}, as in:
495 AC_CONFIG_FILES(... lib/Makefile ...)
498 If your gnulib source base is @file{gl}, you would use:
501 AC_CONFIG_FILES(... gl/Makefile ...)
504 You must also make sure that @code{make} work in the gnulib directory.
505 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
512 or if you, more likely, already have a few entries in @code{SUBDIRS},
513 you can add something like:
519 If you are using a gnulib source base of @code{gl}, you would use:
525 Finally, you have to add compiler and linker flags in the appropriate
526 source directories, so that you can make use
527 of the gnulib library. For example:
531 AM_CPPFLAGS = -I$(top_srcdir)/lib
533 LIBADD = lib/libgnu.a
537 Don't forget to @code{#include} the various header files. In this
538 example, you would need to make sure that @samp{#include "strdup.h"}
539 is evaluated when compiling all source code files, that want to make
540 use of @code{strdup}.
542 When an include file is provided by the gnulib
543 you shouldn't try to include the corresponding system header files
544 yourself but let the gnulib header file do it as the ordering
545 of the definition for some symbols may be significant.
547 For example, to use the @code{time_r} gnulib module you should
548 use include header file provided by the gnulib, and so
549 @samp{#include "time_r.h"}, but you shouldn't explicitely
550 @samp{#include <time.h>} as it is already done in @file{time_r.h}
551 before the redefinition of some symbols.
553 @node Importing updated files
554 @section Importing updated files
556 From time to time, you may want to invoke @samp{gnulib-tool --import}
557 to update the files in your package. Once you have set up your
558 package for gnulib, this step is quite simple. For example:
561 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
562 Module list with included dependencies:
569 Creating ./lib/Makefile.am...
570 Creating ./m4/gnulib.m4...
573 Don't forget to add "lib/Makefile"
574 to AC_CONFIG_FILES in "./configure.ac" and to mention
575 "lib" in SUBDIRS in some Makefile.am.
579 If you don't recall how you invoked the tool last time, the commands
580 used (and the operations it resulted in) are placed in comments within
581 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
585 # Invoked as: gnulib-tool --import strdup
586 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
591 @node Finishing touches
592 @section Finishing touches
594 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
595 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
596 snprintf getline minmax}) can be tedious. To simplify this procedure,
597 you may put the command line parameters in your @file{configure.ac}.
609 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
614 This illustrate all macros defined in @file{gnulib.m4}. With the
615 above, importing new files are as simple as running @samp{gnulib-tool
616 --import} with no additional parameters.
618 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
619 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
620 macro can be used if you wish to change the library name (by default
621 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
622 @code{gl_MODULES} macro is used to specify which modules to import.
625 @node Copying This Manual
626 @appendix Copying This Manual
629 * GNU Free Documentation License:: License for copying this manual.