1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.8 2005-05-19 13:17:34 karl Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2005-05-19 13:17:34 $
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::
93 @cindex comments describing functions
94 @cindex describing functions, locating
95 Where to put comments describing functions: Because of risk of
96 divergence, we prefer to keep most function describing comments in
97 only one place: just above the actual function definition. Some
98 people prefer to put that documentation in the .h file. In any case,
99 it should appear in just one place unless you can ensure that the
100 multiple copies will always remain identical.
104 @section Header files
106 @cindex double inclusion of header files
107 @cindex header file include protection
108 It is a tradition to use CPP tricks to avoid parsing the same header
109 file more than once, which might cause warnings. The trick is to wrap
110 the content of the header file (say, @file{foo.h}) in a block, as in:
116 body of header file goes here
121 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
122 style. The C89 and C99 standards reserve all identifiers that begin with an
123 underscore and either an uppercase letter or another underscore, for
124 any use. Thus, in theory, an application might not safely assume that
125 @code{_FOO_H} has not already been defined by a library. On the other
126 hand, using @code{FOO_H} will likely lead the higher risk of
127 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
128 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
129 macro function). Your preference may depend on whether you consider
130 the header file under discussion as part of the application (which has
131 its own namespace for CPP symbols) or a supporting library (that
132 shouldn't interfere with the application's CPP symbol namespace).
134 @cindex C++ header files
135 @cindex Header files and C++
136 Adapting C header files for use in C++ applications can use another
145 body of header file goes here
152 The idea here is that @code{__cplusplus} is defined only by C++
153 implementations, which will wrap the header file in an @samp{extern "C"}
154 block. Again, whether to use this trick is a matter of taste and
155 style. While the above can be seen as harmless, it could be argued
156 that the header file is written in C, and any C++ application using it
157 should explicitly use the @samp{extern "C"} block itself. Your
158 preference might depend on whether you consider the API exported by
159 your header file as something available for C programs only, or for C
160 and C++ programs alike.
166 The @code{ctime} function need not be reentrant, and consequently is
167 not required to be thread safe. Implementations of @code{ctime}
168 typically write the time stamp into static buffer. If two threads
169 call @code{ctime} at roughly the same time, you might end up with the
170 wrong date in one of the threads, or some undefined string. There is
171 a re-entrant interface @code{ctime_r}, that take a pre-allocated
172 buffer and length of the buffer, and return @code{NULL} on errors.
173 The input buffer should be at least 26 bytes in size. The output
174 string is locale-independent. However, years can have more than 4
175 digits if @code{time_t} is sufficiently wide, so the length of the
176 required output buffer is not easy to determine. Increasing the
177 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
178 sufficient. The @code{NULL} return value could mean some other error
179 condition, which will not go away by increasing the buffer size.
181 A more flexible function is @code{strftime}. However, note that it is
189 The @code{inet_ntoa} function need not be reentrant, and consequently
190 is not required to be thread safe. Implementations of
191 @code{inet_ntoa} typically write the time stamp into static buffer.
192 If two threads call @code{inet_ntoa} at roughly the same time, you
193 might end up with the wrong date in one of the threads, or some
194 undefined string. Further, @code{inet_ntoa} is specific for
195 @acronym{IPv4} addresses.
197 A protocol independent function is @code{inet_ntop}.
200 @node Out of memory handling
201 @section Out of memory handling
203 @cindex Out of Memory handling
204 @cindex Memory allocation failure
205 The GSS API does not have a standard error code for the out of memory
206 error condition. Instead of adding a non-standard error code, this
207 library has chosen to adopt a different strategy. Out of memory
208 handling happens in rare situations, but performing the out of memory
209 error handling after almost all API function invocations pollute your
210 source code and might make it harder to spot more serious problems.
211 The strategy chosen improve code readability and robustness.
213 @cindex Aborting execution
214 For most applications, aborting the application with an error message
215 when the out of memory situation occur is the best that can be wished
216 for. This is how the library behaves by default.
218 @vindex xalloc_fail_func
219 However, we realize that some applications may not want to have the
220 GSS library abort execution in any situation. The GSS library support
221 a hook to let the application regain control and perform its own
222 cleanups when an out of memory situation has occured. The application
223 can define a function (having a @code{void} prototype, i.e., no return
224 value and no parameters) and set the library variable
225 @code{xalloc_fail_func} to that function. The variable should be
229 extern void (*xalloc_fail_func) (void);
232 The GSS library will invoke this function if an out of memory error
233 occurs. Note that after this the GSS library is in an undefined
234 state, so you must unload or restart the application to continue call
235 GSS library functions. The hook is only intended to allow the
236 application to log the situation in a special way. Of course, care
237 must be taken to not allocate more memory, as that will likely also
241 @node Invoking gnulib-tool
242 @chapter Invoking gnulib-tool
245 @cindex invoking @command{gnulib-tool}
247 Run @samp{gnulib-tool --help}, and use the source.
248 @command{gnulib-tool} is the way to import Gnulib modules.
251 * Initial import:: First import of Gnulib modules.
252 * Importing updated files:: Subsequent imports.
253 * Finishing touches:: Simplifying imports.
258 @section Initial import
259 @cindex initial import
261 Gnulib assumes your project uses Autoconf and Automake. Invoking
262 @samp{gnulib-tool --import} will copy source files, create a
263 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
264 Autoconf M4 macro declarations used by @file{configure.ac}.
266 Our example will be a library that uses Autoconf, Automake and
267 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
268 the package portable to C89 (which doesn't have @code{strdup}).
271 ~/src/libfoo$ gnulib-tool --import strdup
272 Module list with included dependencies:
279 Creating ./lib/Makefile.am...
280 Creating ./m4/gnulib.m4...
283 You may need to add #include directives for the following .h files.
286 Don't forget to add "lib/Makefile"
287 to AC_CONFIG_FILES in "./configure.ac" and to mention
288 "lib" in SUBDIRS in some Makefile.am.
292 By default, the source code is copied into @file{lib/} and the M4
293 macros in @file{m4/}. You can override these paths by using
294 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
295 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
296 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
297 Some modules also provide other files necessary
298 for building. These files are copied into the directory specified
299 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
300 @code{--aux-dir=DIRECTORY} option. If neither is specified, the
301 current directory is assumed.
303 @code{gnulib-tool} can make symbolic links instead
304 of copying the source files. Use the @code{--symbolic}
305 (or @code{-s} for short) option to do this.
307 @code{gnulib-tool} will overwrite any pre-existing files, in
308 particular @file{Makefile.am}. Unfortunately, separating the
309 generated @file{Makefile.am} content (for building the gnulib library)
310 into a separate file, say @file{gnulib.mk}, that could be included
311 by your handwritten @file{Makefile.am} is not possible, due to how
312 variable assignments are handled by Automake.
314 Consequently, it can be a good idea to chose directories that are not
315 already used by your projects, to separate gnulib imported files from
316 your own files. This approach can also be useful if you want to avoid
317 conflicts between other tools (e.g., @code{getextize} that also copy
318 M4 files into your package. Simon Josefsson successfully uses a source
319 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
322 A few manual steps are required to finish the initial import.
324 First, you need to make sure Autoconf can find the macro definitions
325 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
326 top-level @file{Makefile.am} file, as in:
329 ACLOCAL_AMFLAGS = -I m4
332 Naturally, replace @file{m4} with the value from @code{--m4-base} or
333 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
336 ACLOCAL_AMFLAGS = -I gl/m4
339 You are now ready to call the M4 macros in @code{gnulib.m4} from
340 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
341 as possible after verifying that the C compiler is working.
342 Typically, this is immediately after @code{AC_PROG_CC}, as in:
351 The core part of the gnulib checks are done by the macro
352 @code{gl_INIT}. Place it further down in the file, typically where
353 you normally check for header files or functions. Or in a separate
354 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
364 You must also make sure that the gnulib library is built. Add the
365 @code{Makefile} in the gnulib source base directory to
366 @code{AC_CONFIG_FILES}, as in:
369 AC_CONFIG_FILES(... lib/Makefile ...)
372 If your gnulib source base is @file{gl}, you would use:
375 AC_CONFIG_FILES(... gl/Makefile ...)
378 You must also make sure that @code{make} work in the gnulib directory.
379 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
386 or if you, more likely, already have a few entries in @code{SUBDIRS},
387 you can add something like:
393 If you are using a gnulib source base of @code{gl}, you would use:
399 Finally, you have to add compiler and linker flags in the appropriate
400 source directories, so that you can make use
401 of the gnulib library. For example:
405 AM_CPPFLAGS = -I$(top_srcdir)/lib
407 LIBADD = lib/libgnu.a
411 Don't forget to @code{#include} the various header files. In this
412 example, you would need to make sure that @samp{#include <strdup.h>}
413 is evaluated when compiling all source code files, that want to make
414 use of @code{strdup}.
417 @node Importing updated files
418 @section Importing updated files
420 From time to time, you may want to invoke @samp{gnulib-tool --import}
421 to update the files in your package. Once you have set up your
422 package for gnulib, this step is quite simple. For example:
425 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
426 Module list with included dependencies:
433 Creating ./lib/Makefile.am...
434 Creating ./m4/gnulib.m4...
437 Don't forget to add "lib/Makefile"
438 to AC_CONFIG_FILES in "./configure.ac" and to mention
439 "lib" in SUBDIRS in some Makefile.am.
443 If you don't recall how you invoked the tool last time, the commands
444 used (and the operations it resulted in) are placed in comments within
445 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
449 # Invoked as: gnulib-tool --import strdup
450 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
455 @node Finishing touches
456 @section Finishing touches
458 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
459 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
460 snprintf getline minmax}) can be tedious. To simplify this procedure,
461 you may put the command line parameters in your @file{configure.ac}.
473 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
478 This illustrate all macros defined in @file{gnulib.m4}. With the
479 above, importing new files are as simple as running @samp{gnulib-tool
480 --import} with no additional parameters.
482 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
483 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
484 macro can be used if you wish to change the library name (by default
485 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
486 @code{gl_MODULES} macro is used to specify which modules to import.
489 @node Copying This Manual
490 @appendix Copying This Manual
493 * GNU Free Documentation License:: License for copying this manual.