1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.10 2005-06-27 22:36:50 jas Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2005-06-27 22:36:50 $
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/}.
87 * Out of memory handling::
88 * Library version handling::
94 @cindex comments describing functions
95 @cindex describing functions, locating
96 Where to put comments describing functions: Because of risk of
97 divergence, we prefer to keep most function describing comments in
98 only one place: just above the actual function definition. Some
99 people prefer to put that documentation in the .h file. In any case,
100 it should appear in just one place unless you can ensure that the
101 multiple copies will always remain identical.
105 @section Header files
107 @cindex double inclusion of header files
108 @cindex header file include protection
109 It is a tradition to use CPP tricks to avoid parsing the same header
110 file more than once, which might cause warnings. The trick is to wrap
111 the content of the header file (say, @file{foo.h}) in a block, as in:
117 body of header file goes here
122 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
123 style. The C89 and C99 standards reserve all identifiers that begin with an
124 underscore and either an uppercase letter or another underscore, for
125 any use. Thus, in theory, an application might not safely assume that
126 @code{_FOO_H} has not already been defined by a library. On the other
127 hand, using @code{FOO_H} will likely lead the higher risk of
128 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
129 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
130 macro function). Your preference may depend on whether you consider
131 the header file under discussion as part of the application (which has
132 its own namespace for CPP symbols) or a supporting library (that
133 shouldn't interfere with the application's CPP symbol namespace).
135 @cindex C++ header files
136 @cindex Header files and C++
137 Adapting C header files for use in C++ applications can use another
146 body of header file goes here
153 The idea here is that @code{__cplusplus} is defined only by C++
154 implementations, which will wrap the header file in an @samp{extern "C"}
155 block. Again, whether to use this trick is a matter of taste and
156 style. While the above can be seen as harmless, it could be argued
157 that the header file is written in C, and any C++ application using it
158 should explicitly use the @samp{extern "C"} block itself. Your
159 preference might depend on whether you consider the API exported by
160 your header file as something available for C programs only, or for C
161 and C++ programs alike.
163 @subsection Include ordering
165 When writing a gnulib module, or even in general, a good way to order
166 the @samp{#include} directives is the following.
169 @item First comes the #include "..." specifying the module being implemented.
170 @item Then come all the #include <...> of system or system-replacement headers,
172 @item Then come all the #include "..." of gnulib and private headers, in
180 The @code{ctime} function need not be reentrant, and consequently is
181 not required to be thread safe. Implementations of @code{ctime}
182 typically write the time stamp into static buffer. If two threads
183 call @code{ctime} at roughly the same time, you might end up with the
184 wrong date in one of the threads, or some undefined string. There is
185 a re-entrant interface @code{ctime_r}, that take a pre-allocated
186 buffer and length of the buffer, and return @code{NULL} on errors.
187 The input buffer should be at least 26 bytes in size. The output
188 string is locale-independent. However, years can have more than 4
189 digits if @code{time_t} is sufficiently wide, so the length of the
190 required output buffer is not easy to determine. Increasing the
191 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
192 sufficient. The @code{NULL} return value could mean some other error
193 condition, which will not go away by increasing the buffer size.
195 A more flexible function is @code{strftime}. However, note that it is
203 The @code{inet_ntoa} function need not be reentrant, and consequently
204 is not required to be thread safe. Implementations of
205 @code{inet_ntoa} typically write the time stamp into static buffer.
206 If two threads call @code{inet_ntoa} at roughly the same time, you
207 might end up with the wrong date in one of the threads, or some
208 undefined string. Further, @code{inet_ntoa} is specific for
209 @acronym{IPv4} addresses.
211 A protocol independent function is @code{inet_ntop}.
214 @node Out of memory handling
215 @section Out of memory handling
217 @cindex Out of Memory handling
218 @cindex Memory allocation failure
219 The GSS API does not have a standard error code for the out of memory
220 error condition. Instead of adding a non-standard error code, this
221 library has chosen to adopt a different strategy. Out of memory
222 handling happens in rare situations, but performing the out of memory
223 error handling after almost all API function invocations pollute your
224 source code and might make it harder to spot more serious problems.
225 The strategy chosen improve code readability and robustness.
227 @cindex Aborting execution
228 For most applications, aborting the application with an error message
229 when the out of memory situation occur is the best that can be wished
230 for. This is how the library behaves by default.
232 @vindex xalloc_fail_func
233 However, we realize that some applications may not want to have the
234 GSS library abort execution in any situation. The GSS library support
235 a hook to let the application regain control and perform its own
236 cleanups when an out of memory situation has occured. The application
237 can define a function (having a @code{void} prototype, i.e., no return
238 value and no parameters) and set the library variable
239 @code{xalloc_fail_func} to that function. The variable should be
243 extern void (*xalloc_fail_func) (void);
246 The GSS library will invoke this function if an out of memory error
247 occurs. Note that after this the GSS library is in an undefined
248 state, so you must unload or restart the application to continue call
249 GSS library functions. The hook is only intended to allow the
250 application to log the situation in a special way. Of course, care
251 must be taken to not allocate more memory, as that will likely also
255 @node Library version handling
256 @section Library version handling
258 The module ``check_version'' can be useful when your gnulib
259 application is a system library. You will typically wrap the call to
260 the @code{check_version} function through a library API, your library
261 header file may contain:
264 #define STRINGPREP_VERSION "0.5.18"
266 extern const char *stringprep_check_version (const char *req_version);
269 The implementation of @code{stringprep_check_version} would simply
270 pass on the call to @code{check_version}.
272 There are two uses of the interface. The first is a way to provide
273 for applications to find out the version number of the library it
274 uses. The application may contain diagnostic code such as:
277 printf ("Stringprep version: header %s library %s",
279 stringprep_check_version (NULL));
282 Separating the library and header file version can be useful when
283 searching for version mismatch related problems.
285 The second uses is as a rudimentary test of proper library version, by
286 making sure the application get a library version that is the same, or
287 newer, than the header file used when building the application. This
288 doesn't catch all problems, libraries may change backwards incompatibly
289 in later versions, but enable applications to require a certain
290 minimum version before it may proceed.
292 Typical uses look like:
295 /* Check version of libgcrypt. */
296 if (!gcry_check_version (GCRYPT_VERSION))
297 die ("version mismatch\n");
300 @node Invoking gnulib-tool
301 @chapter Invoking gnulib-tool
304 @cindex invoking @command{gnulib-tool}
306 Run @samp{gnulib-tool --help}, and use the source.
307 @command{gnulib-tool} is the way to import Gnulib modules.
310 * Initial import:: First import of Gnulib modules.
311 * Importing updated files:: Subsequent imports.
312 * Finishing touches:: Simplifying imports.
317 @section Initial import
318 @cindex initial import
320 Gnulib assumes your project uses Autoconf and Automake. Invoking
321 @samp{gnulib-tool --import} will copy source files, create a
322 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
323 Autoconf M4 macro declarations used by @file{configure.ac}.
325 Our example will be a library that uses Autoconf, Automake and
326 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
327 the package portable to C89 (which doesn't have @code{strdup}).
330 ~/src/libfoo$ gnulib-tool --import strdup
331 Module list with included dependencies:
338 Creating ./lib/Makefile.am...
339 Creating ./m4/gnulib.m4...
342 You may need to add #include directives for the following .h files.
345 Don't forget to add "lib/Makefile"
346 to AC_CONFIG_FILES in "./configure.ac" and to mention
347 "lib" in SUBDIRS in some Makefile.am.
351 By default, the source code is copied into @file{lib/} and the M4
352 macros in @file{m4/}. You can override these paths by using
353 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
354 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
355 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
356 Some modules also provide other files necessary
357 for building. These files are copied into the directory specified
358 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
359 @code{--aux-dir=DIRECTORY} option. If neither is specified, the
360 current directory is assumed.
362 @code{gnulib-tool} can make symbolic links instead
363 of copying the source files. Use the @code{--symbolic}
364 (or @code{-s} for short) option to do this.
366 @code{gnulib-tool} will overwrite any pre-existing files, in
367 particular @file{Makefile.am}. Unfortunately, separating the
368 generated @file{Makefile.am} content (for building the gnulib library)
369 into a separate file, say @file{gnulib.mk}, that could be included
370 by your handwritten @file{Makefile.am} is not possible, due to how
371 variable assignments are handled by Automake.
373 Consequently, it can be a good idea to chose directories that are not
374 already used by your projects, to separate gnulib imported files from
375 your own files. This approach can also be useful if you want to avoid
376 conflicts between other tools (e.g., @code{getextize} that also copy
377 M4 files into your package. Simon Josefsson successfully uses a source
378 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
381 A few manual steps are required to finish the initial import.
383 First, you need to make sure Autoconf can find the macro definitions
384 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
385 top-level @file{Makefile.am} file, as in:
388 ACLOCAL_AMFLAGS = -I m4
391 Naturally, replace @file{m4} with the value from @code{--m4-base} or
392 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
395 ACLOCAL_AMFLAGS = -I gl/m4
398 You are now ready to call the M4 macros in @code{gnulib.m4} from
399 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
400 as possible after verifying that the C compiler is working.
401 Typically, this is immediately after @code{AC_PROG_CC}, as in:
410 The core part of the gnulib checks are done by the macro
411 @code{gl_INIT}. Place it further down in the file, typically where
412 you normally check for header files or functions. Or in a separate
413 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
423 You must also make sure that the gnulib library is built. Add the
424 @code{Makefile} in the gnulib source base directory to
425 @code{AC_CONFIG_FILES}, as in:
428 AC_CONFIG_FILES(... lib/Makefile ...)
431 If your gnulib source base is @file{gl}, you would use:
434 AC_CONFIG_FILES(... gl/Makefile ...)
437 You must also make sure that @code{make} work in the gnulib directory.
438 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
445 or if you, more likely, already have a few entries in @code{SUBDIRS},
446 you can add something like:
452 If you are using a gnulib source base of @code{gl}, you would use:
458 Finally, you have to add compiler and linker flags in the appropriate
459 source directories, so that you can make use
460 of the gnulib library. For example:
464 AM_CPPFLAGS = -I$(top_srcdir)/lib
466 LIBADD = lib/libgnu.a
470 Don't forget to @code{#include} the various header files. In this
471 example, you would need to make sure that @samp{#include <strdup.h>}
472 is evaluated when compiling all source code files, that want to make
473 use of @code{strdup}.
476 @node Importing updated files
477 @section Importing updated files
479 From time to time, you may want to invoke @samp{gnulib-tool --import}
480 to update the files in your package. Once you have set up your
481 package for gnulib, this step is quite simple. For example:
484 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
485 Module list with included dependencies:
492 Creating ./lib/Makefile.am...
493 Creating ./m4/gnulib.m4...
496 Don't forget to add "lib/Makefile"
497 to AC_CONFIG_FILES in "./configure.ac" and to mention
498 "lib" in SUBDIRS in some Makefile.am.
502 If you don't recall how you invoked the tool last time, the commands
503 used (and the operations it resulted in) are placed in comments within
504 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
508 # Invoked as: gnulib-tool --import strdup
509 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
514 @node Finishing touches
515 @section Finishing touches
517 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
518 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
519 snprintf getline minmax}) can be tedious. To simplify this procedure,
520 you may put the command line parameters in your @file{configure.ac}.
532 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
537 This illustrate all macros defined in @file{gnulib.m4}. With the
538 above, importing new files are as simple as running @samp{gnulib-tool
539 --import} with no additional parameters.
541 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
542 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
543 macro can be used if you wish to change the library name (by default
544 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
545 @code{gl_MODULES} macro is used to specify which modules to import.
548 @node Copying This Manual
549 @appendix Copying This Manual
552 * GNU Free Documentation License:: License for copying this manual.