1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.11 2005-07-11 15:12:49 karl Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2005-07-11 15:12:49 $
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::
96 @cindex comments describing functions
97 @cindex describing functions, locating
98 Where to put comments describing functions: Because of risk of
99 divergence, we prefer to keep most function describing comments in
100 only one place: just above the actual function definition. Some
101 people prefer to put that documentation in the .h file. In any case,
102 it should appear in just one place unless you can ensure that the
103 multiple copies will always remain identical.
107 @section Header files
109 @cindex double inclusion of header files
110 @cindex header file include protection
111 It is a tradition to use CPP tricks to avoid parsing the same header
112 file more than once, which might cause warnings. The trick is to wrap
113 the content of the header file (say, @file{foo.h}) in a block, as in:
119 body of header file goes here
124 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
125 style. The C89 and C99 standards reserve all identifiers that begin with an
126 underscore and either an uppercase letter or another underscore, for
127 any use. Thus, in theory, an application might not safely assume that
128 @code{_FOO_H} has not already been defined by a library. On the other
129 hand, using @code{FOO_H} will likely lead the higher risk of
130 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
131 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
132 macro function). Your preference may depend on whether you consider
133 the header file under discussion as part of the application (which has
134 its own namespace for CPP symbols) or a supporting library (that
135 shouldn't interfere with the application's CPP symbol namespace).
137 @cindex C++ header files
138 @cindex Header files and C++
139 Adapting C header files for use in C++ applications can use another
148 body of header file goes here
155 The idea here is that @code{__cplusplus} is defined only by C++
156 implementations, which will wrap the header file in an @samp{extern "C"}
157 block. Again, whether to use this trick is a matter of taste and
158 style. While the above can be seen as harmless, it could be argued
159 that the header file is written in C, and any C++ application using it
160 should explicitly use the @samp{extern "C"} block itself. Your
161 preference might depend on whether you consider the API exported by
162 your header file as something available for C programs only, or for C
163 and C++ programs alike.
165 @subheading Include ordering
167 When writing a gnulib module, or even in general, a good way to order
168 the @samp{#include} directives is the following.
171 @item First comes the #include "..." specifying the module being implemented.
172 @item Then come all the #include <...> of system or system-replacement headers,
174 @item Then come all the #include "..." of gnulib and private headers, in
186 Gnulib provides @samp{quote} and @samp{quotearg} modules to help with
187 quoting text, such as file names, in messages to the user. Here's an
188 example of using @samp{quote}:
193 error (0, errno, _("cannot change owner of %s"), quote (fname));
199 error (0, errno, _("cannot change owner of `%s'"), fname);
202 @noindent in that @code{quote} escapes unusual characters in
203 @code{fname}, e.g., @samp{'} and control characters like @samp{\n}.
206 However, a caveat: @code{quote} reuses the storage that it returns.
207 Hence if you need more than one thing quoted at the same time, you
208 need to use @code{quote_n}.
210 @findex quotearg_alloc
211 Also, the quote module is not suited for multithreaded applications.
212 In that case, you have to use @code{quotearg_alloc}, defined in the
213 @samp{quotearg} module, which is decidedly less convenient.
220 The @code{ctime} function need not be reentrant, and consequently is
221 not required to be thread safe. Implementations of @code{ctime}
222 typically write the time stamp into static buffer. If two threads
223 call @code{ctime} at roughly the same time, you might end up with the
224 wrong date in one of the threads, or some undefined string. There is
225 a re-entrant interface @code{ctime_r}, that take a pre-allocated
226 buffer and length of the buffer, and return @code{NULL} on errors.
227 The input buffer should be at least 26 bytes in size. The output
228 string is locale-independent. However, years can have more than 4
229 digits if @code{time_t} is sufficiently wide, so the length of the
230 required output buffer is not easy to determine. Increasing the
231 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
232 sufficient. The @code{NULL} return value could mean some other error
233 condition, which will not go away by increasing the buffer size.
235 A more flexible function is @code{strftime}. However, note that it is
243 The @code{inet_ntoa} function need not be reentrant, and consequently
244 is not required to be thread safe. Implementations of
245 @code{inet_ntoa} typically write the time stamp into static buffer.
246 If two threads call @code{inet_ntoa} at roughly the same time, you
247 might end up with the wrong date in one of the threads, or some
248 undefined string. Further, @code{inet_ntoa} is specific for
249 @acronym{IPv4} addresses.
251 A protocol independent function is @code{inet_ntop}.
254 @node Out of memory handling
255 @section Out of memory handling
257 @cindex Out of Memory handling
258 @cindex Memory allocation failure
259 The GSS API does not have a standard error code for the out of memory
260 error condition. Instead of adding a non-standard error code, this
261 library has chosen to adopt a different strategy. Out of memory
262 handling happens in rare situations, but performing the out of memory
263 error handling after almost all API function invocations pollute your
264 source code and might make it harder to spot more serious problems.
265 The strategy chosen improve code readability and robustness.
267 @cindex Aborting execution
268 For most applications, aborting the application with an error message
269 when the out of memory situation occur is the best that can be wished
270 for. This is how the library behaves by default.
272 @vindex xalloc_fail_func
273 However, we realize that some applications may not want to have the
274 GSS library abort execution in any situation. The GSS library support
275 a hook to let the application regain control and perform its own
276 cleanups when an out of memory situation has occured. The application
277 can define a function (having a @code{void} prototype, i.e., no return
278 value and no parameters) and set the library variable
279 @code{xalloc_fail_func} to that function. The variable should be
283 extern void (*xalloc_fail_func) (void);
286 The GSS library will invoke this function if an out of memory error
287 occurs. Note that after this the GSS library is in an undefined
288 state, so you must unload or restart the application to continue call
289 GSS library functions. The hook is only intended to allow the
290 application to log the situation in a special way. Of course, care
291 must be taken to not allocate more memory, as that will likely also
295 @node Library version handling
296 @section Library version handling
298 The module ``check_version'' can be useful when your gnulib
299 application is a system library. You will typically wrap the call to
300 the @code{check_version} function through a library API, your library
301 header file may contain:
304 #define STRINGPREP_VERSION "0.5.18"
306 extern const char *stringprep_check_version (const char *req_version);
309 The implementation of @code{stringprep_check_version} would simply
310 pass on the call to @code{check_version}.
312 There are two uses of the interface. The first is a way to provide
313 for applications to find out the version number of the library it
314 uses. The application may contain diagnostic code such as:
317 printf ("Stringprep version: header %s library %s",
319 stringprep_check_version (NULL));
322 Separating the library and header file version can be useful when
323 searching for version mismatch related problems.
325 The second uses is as a rudimentary test of proper library version, by
326 making sure the application get a library version that is the same, or
327 newer, than the header file used when building the application. This
328 doesn't catch all problems, libraries may change backwards incompatibly
329 in later versions, but enable applications to require a certain
330 minimum version before it may proceed.
332 Typical uses look like:
335 /* Check version of libgcrypt. */
336 if (!gcry_check_version (GCRYPT_VERSION))
337 die ("version mismatch\n");
341 @node Invoking gnulib-tool
342 @chapter Invoking gnulib-tool
345 @cindex invoking @command{gnulib-tool}
347 Run @samp{gnulib-tool --help}, and use the source.
348 @command{gnulib-tool} is the way to import Gnulib modules.
351 * Initial import:: First import of Gnulib modules.
352 * Importing updated files:: Subsequent imports.
353 * Finishing touches:: Simplifying imports.
358 @section Initial import
359 @cindex initial import
361 Gnulib assumes your project uses Autoconf and Automake. Invoking
362 @samp{gnulib-tool --import} will copy source files, create a
363 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
364 Autoconf M4 macro declarations used by @file{configure.ac}.
366 Our example will be a library that uses Autoconf, Automake and
367 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
368 the package portable to C89 (which doesn't have @code{strdup}).
371 ~/src/libfoo$ gnulib-tool --import strdup
372 Module list with included dependencies:
379 Creating ./lib/Makefile.am...
380 Creating ./m4/gnulib.m4...
383 You may need to add #include directives for the following .h files.
386 Don't forget to add "lib/Makefile"
387 to AC_CONFIG_FILES in "./configure.ac" and to mention
388 "lib" in SUBDIRS in some Makefile.am.
392 By default, the source code is copied into @file{lib/} and the M4
393 macros in @file{m4/}. You can override these paths by using
394 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
395 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
396 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
397 Some modules also provide other files necessary
398 for building. These files are copied into the directory specified
399 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
400 @code{--aux-dir=DIRECTORY} option. If neither is specified, the
401 current directory is assumed.
403 @code{gnulib-tool} can make symbolic links instead
404 of copying the source files. Use the @code{--symbolic}
405 (or @code{-s} for short) option to do this.
407 @code{gnulib-tool} will overwrite any pre-existing files, in
408 particular @file{Makefile.am}. Unfortunately, separating the
409 generated @file{Makefile.am} content (for building the gnulib library)
410 into a separate file, say @file{gnulib.mk}, that could be included
411 by your handwritten @file{Makefile.am} is not possible, due to how
412 variable assignments are handled by Automake.
414 Consequently, it can be a good idea to chose directories that are not
415 already used by your projects, to separate gnulib imported files from
416 your own files. This approach can also be useful if you want to avoid
417 conflicts between other tools (e.g., @code{getextize} that also copy
418 M4 files into your package. Simon Josefsson successfully uses a source
419 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
422 A few manual steps are required to finish the initial import.
424 First, you need to make sure Autoconf can find the macro definitions
425 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
426 top-level @file{Makefile.am} file, as in:
429 ACLOCAL_AMFLAGS = -I m4
432 Naturally, replace @file{m4} with the value from @code{--m4-base} or
433 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
436 ACLOCAL_AMFLAGS = -I gl/m4
439 You are now ready to call the M4 macros in @code{gnulib.m4} from
440 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
441 as possible after verifying that the C compiler is working.
442 Typically, this is immediately after @code{AC_PROG_CC}, as in:
451 The core part of the gnulib checks are done by the macro
452 @code{gl_INIT}. Place it further down in the file, typically where
453 you normally check for header files or functions. Or in a separate
454 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
464 @code{gl_INIT} will in turn call the macros related with the
465 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
466 or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or
467 @code{AM_FUNC_GETLINE} so there is no need to call those macros yourself
468 when you use the corresponding gnulib modules.
470 You must also make sure that the gnulib library is built. Add the
471 @code{Makefile} in the gnulib source base directory to
472 @code{AC_CONFIG_FILES}, as in:
475 AC_CONFIG_FILES(... lib/Makefile ...)
478 If your gnulib source base is @file{gl}, you would use:
481 AC_CONFIG_FILES(... gl/Makefile ...)
484 You must also make sure that @code{make} work in the gnulib directory.
485 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
492 or if you, more likely, already have a few entries in @code{SUBDIRS},
493 you can add something like:
499 If you are using a gnulib source base of @code{gl}, you would use:
505 Finally, you have to add compiler and linker flags in the appropriate
506 source directories, so that you can make use
507 of the gnulib library. For example:
511 AM_CPPFLAGS = -I$(top_srcdir)/lib
513 LIBADD = lib/libgnu.a
517 Don't forget to @code{#include} the various header files. In this
518 example, you would need to make sure that @samp{#include "strdup.h"}
519 is evaluated when compiling all source code files, that want to make
520 use of @code{strdup}.
522 When an include file is provided by the gnulib
523 you shouldn't try to include the corresponding system header files
524 yourself but let the gnulib header file do it as the ordering
525 of the definition for some symbols may be significant.
527 For example, to use the @code{time_r} gnulib module you should
528 use include header file provided by the gnulib, and so
529 @samp{#include "time_r.h"}, but you shouldn't explicitely
530 @samp{#include <time.h>} as it is allready done in @file{time_r.h}
531 before the redefinition of some symbols.
533 @node Importing updated files
534 @section Importing updated files
536 From time to time, you may want to invoke @samp{gnulib-tool --import}
537 to update the files in your package. Once you have set up your
538 package for gnulib, this step is quite simple. For example:
541 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
542 Module list with included dependencies:
549 Creating ./lib/Makefile.am...
550 Creating ./m4/gnulib.m4...
553 Don't forget to add "lib/Makefile"
554 to AC_CONFIG_FILES in "./configure.ac" and to mention
555 "lib" in SUBDIRS in some Makefile.am.
559 If you don't recall how you invoked the tool last time, the commands
560 used (and the operations it resulted in) are placed in comments within
561 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
565 # Invoked as: gnulib-tool --import strdup
566 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
571 @node Finishing touches
572 @section Finishing touches
574 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
575 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
576 snprintf getline minmax}) can be tedious. To simplify this procedure,
577 you may put the command line parameters in your @file{configure.ac}.
589 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
594 This illustrate all macros defined in @file{gnulib.m4}. With the
595 above, importing new files are as simple as running @samp{gnulib-tool
596 --import} with no additional parameters.
598 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
599 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
600 macro can be used if you wish to change the library name (by default
601 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
602 @code{gl_MODULES} macro is used to specify which modules to import.
605 @node Copying This Manual
606 @appendix Copying This Manual
609 * GNU Free Documentation License:: License for copying this manual.