1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.6 2004-09-29 10:58:47 haible Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2004-09-29 10:58:47 $
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 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 is not a real manual. It's just a place to store random notes
69 until someone (you?) gets around to actually writing a manual.
74 @item Gnulib is hosted at Savannah:
75 @url{http://savannah.gnu.org/projects/gnulib}. Get the sources
76 through CVS from there.
77 @item The Gnulib home page:
78 @url{http://www.gnu.org/software/gnulib/}.
86 * Out of memory handling::
92 @cindex comments describing functions
93 @cindex describing functions, locating
94 Where to put comments describing functions: Because of risk of
95 divergence, we prefer to keep most function describing comments in
96 only one place: just above the actual function definition. Some
97 people prefer to put that documentation in the .h file. In any case,
98 it should appear in just one place unless you can ensure that the
99 multiple copies will always remain identical.
103 @section Header files
105 @cindex double inclusion of header files
106 @cindex header file include protection
107 It is a tradition to use CPP tricks to avoid parsing the same header
108 file more than once, which might cause warnings. The trick is to wrap
109 the content of the header file (say, @file{foo.h}) in a block, as in:
115 body of header file goes here
120 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
121 style. The C89 and C99 standards reserve all identifiers that begin with an
122 underscore and either an uppercase letter or another underscore, for
123 any use. Thus, in theory, an application might not safely assume that
124 @code{_FOO_H} has not already been defined by a library. On the other
125 hand, using @code{FOO_H} will likely lead the higher risk of
126 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
127 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
128 macro function). Your preference may depend on whether you consider
129 the header file under discussion as part of the application (which has
130 its own namespace for CPP symbols) or a supporting library (that
131 shouldn't interfere with the application's CPP symbol namespace).
133 @cindex C++ header files
134 @cindex Header files and C++
135 Adapting C header files for use in C++ applications can use another
144 body of header file goes here
151 The idea here is that @code{__cplusplus} is defined only by C++
152 implementations, which will wrap the header file in an @samp{extern "C"}
153 block. Again, whether to use this trick is a matter of taste and
154 style. While the above can be seen as harmless, it could be argued
155 that the header file is written in C, and any C++ application using it
156 should explicitly use the @samp{extern "C"} block itself. Your
157 preference might depend on whether you consider the API exported by
158 your header file as something available for C programs only, or for C
159 and C++ programs alike.
165 The @code{ctime} function need not be reentrant, and consequently is
166 not required to be thread safe. Implementations of @code{ctime}
167 typically write the time stamp into static buffer. If two threads
168 call @code{ctime} at roughly the same time, you might end up with the
169 wrong date in one of the threads, or some undefined string. There is
170 a re-entrant interface @code{ctime_r}, that take a pre-allocated
171 buffer and length of the buffer, and return @code{NULL} on errors.
172 The input buffer should be at least 26 bytes in size. The output
173 string is locale-independent. However, years can have more than 4
174 digits if @code{time_t} is sufficiently wide, so the length of the
175 required output buffer is not easy to determine. Increasing the
176 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
177 sufficient. The @code{NULL} return value could mean some other error
178 condition, which will not go away by increasing the buffer size.
180 A more flexible function is @code{strftime}. However, note that it is
188 The @code{inet_ntoa} function need not be reentrant, and consequently
189 is not required to be thread safe. Implementations of
190 @code{inet_ntoa} typically write the time stamp into static buffer.
191 If two threads call @code{inet_ntoa} at roughly the same time, you
192 might end up with the wrong date in one of the threads, or some
193 undefined string. Further, @code{inet_ntoa} is specific for
194 @acronym{IPv4} addresses.
196 A protocol independent function is @code{inet_ntop}.
199 @node Out of memory handling
200 @section Out of memory handling
202 @cindex Out of Memory handling
203 @cindex Memory allocation failure
204 The GSS API does not have a standard error code for the out of memory
205 error condition. Instead of adding a non-standard error code, this
206 library has chosen to adopt a different strategy. Out of memory
207 handling happens in rare situations, but performing the out of memory
208 error handling after almost all API function invocations pollute your
209 source code and might make it harder to spot more serious problems.
210 The strategy chosen improve code readability and robustness.
212 @cindex Aborting execution
213 For most applications, aborting the application with an error message
214 when the out of memory situation occur is the best that can be wished
215 for. This is how the library behaves by default.
217 @vindex xalloc_fail_func
218 However, we realize that some applications may not want to have the
219 GSS library abort execution in any situation. The GSS library support
220 a hook to let the application regain control and perform its own
221 cleanups when an out of memory situation has occured. The application
222 can define a function (having a @code{void} prototype, i.e., no return
223 value and no parameters) and set the library variable
224 @code{xalloc_fail_func} to that function. The variable should be
228 extern void (*xalloc_fail_func) (void);
231 The GSS library will invoke this function if an out of memory error
232 occurs. Note that after this the GSS library is in an undefined
233 state, so you must unload or restart the application to continue call
234 GSS library functions. The hook is only intended to allow the
235 application to log the situation in a special way. Of course, care
236 must be taken to not allocate more memory, as that will likely also
240 @node Invoking gnulib-tool
241 @chapter Invoking gnulib-tool
244 @cindex invoking @command{gnulib-tool}
246 Run @samp{gnulib-tool --help}, and use the source.
247 @command{gnulib-tool} is the way to import Gnulib modules.
250 * Initial import:: First import of Gnulib modules.
251 * Importing updated files:: Subsequent imports.
252 * Finishing touches:: Simplifying imports.
257 @section Initial import
258 @cindex initial import
260 Gnulib assumes your project uses Autoconf and Automake. Invoking
261 @samp{gnulib-tool --import} will copy source files, create a
262 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
263 Autoconf M4 macro declarations used by @file{configure.ac}.
265 Our example will be a library that uses Autoconf, Automake and
266 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
267 the package portable to C89 (which doesn't have @code{strdup}).
270 ~/src/libfoo$ gnulib-tool --import strdup
271 Module list with included dependencies:
278 Creating ./lib/Makefile.am...
279 Creating ./m4/gnulib.m4...
282 Don't forget to add "lib/Makefile"
283 to AC_CONFIG_FILES in "./configure.ac" and to mention
284 "lib" in SUBDIRS in some Makefile.am.
288 By default, the source code is copied into @file{lib/} and the M4
289 macros in @file{m4/}. You can override these paths by using
290 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
291 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
292 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
294 @code{gnulib-tool} will overwrite any pre-existing files, in
295 particular @file{Makefile.am}. Unfortunately, separating the
296 generated @file{Makefile.am} content (for building the gnulib library)
297 into a separate file, say @file{gnulib.mk}, that could be included
298 by your handwritten @file{Makefile.am} is not possible, due to how
299 variable assignments are handled by Automake.
301 Consequently, it can be a good idea to chose directories that are not
302 already used by your projects, to separate gnulib imported files from
303 your own files. This approach can also be useful if you want to avoid
304 conflicts between other tools (e.g., @code{getextize} that also copy
305 M4 files into your package. Simon Josefsson successfully uses a source
306 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
309 A few manual steps are required to finish the initial import.
311 First, you need to make sure Autoconf can find the macro definitions
312 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
313 top-level @file{Makefile.am} file, as in:
316 ACLOCAL_AMFLAGS = -I m4
319 Naturally, replace @file{m4} with the value from @code{--m4-base} or
320 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
323 ACLOCAL_AMFLAGS = -I gl/m4
326 You are now ready to call the M4 macros in @code{gnulib.m4} from
327 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
328 as possible after verifying that the C compiler is working.
329 Typically, this is immediately after @code{AC_PROG_CC}, as in:
338 The core part of the gnulib checks are done by the macro
339 @code{gl_INIT}. Place it further down in the file, typically where
340 you normally check for header files or functions. Or in a separate
341 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
351 You must also make sure that the gnulib library is built. Add the
352 @code{Makefile} in the gnulib source base directory to
353 @code{AC_CONFIG_FILES}, as in:
356 AC_CONFIG_FILES(... lib/Makefile ...)
359 If your gnulib source base is @file{gl}, you would use:
362 AC_CONFIG_FILES(... gl/Makefile ...)
365 You must also make sure that @code{make} work in the gnulib directory.
366 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
373 or if you, more likely, already have a few entries in @code{SUBDIRS},
374 you can add something like:
380 If you are using a gnulib source base of @code{gl}, you would use:
386 Finally, you have add C flags and LD flags, so that you can make use
387 of the gnulib library. For example:
391 AM_CPPFLAGS = -I$(top_srcdir)/lib
393 LIBADD = lib/libgnu.la
397 Don't forget to @code{#include} the various header files. In this
398 example, you would need to make sure that @samp{#include <strdup.h>}
399 is evaluated when compiling all source code files, that want to make
400 use of @code{strdup}.
403 @node Importing updated files
404 @section Importing updated files
406 From time to time, you may want to invoke @samp{gnulib-tool --import}
407 to update the files in your package. Once you have set up your
408 package for gnulib, this step is quite simple. For example:
411 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
412 Module list with included dependencies:
419 Creating ./lib/Makefile.am...
420 Creating ./m4/gnulib.m4...
423 Don't forget to add "lib/Makefile"
424 to AC_CONFIG_FILES in "./configure.ac" and to mention
425 "lib" in SUBDIRS in some Makefile.am.
429 If you don't recall how you invoked the tool last time, the commands
430 used (and the operations it resulted in) are placed in comments within
431 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
435 # Invoked as: gnulib-tool --import strdup
436 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
441 @node Finishing touches
442 @section Finishing touches
444 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
445 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
446 snprintf getline minmax}) can be tedious. To simplify this procedure,
447 you may put the command line parameters in your @file{configure.ac}.
459 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
464 This illustrate all macros defined in @file{gnulib.m4}. With the
465 above, importing new files are as simple as running @samp{gnulib-tool
466 --import} with no additional parameters.
468 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
469 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
470 macro can be used if you wish to change the library name (by default
471 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
472 @code{gl_MODULES} macro is used to specify which modules to import.
475 @node Copying This Manual
476 @appendix Copying This Manual
479 * GNU Free Documentation License:: License for copying this manual.