1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.5 2004-09-28 22:58:00 eggert Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2004-09-28 22:58:00 $
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{COFF_LONG_H} which is a CPP
127 macro function). Your preference may depeend on whether you consider
128 the header file under discussion as part of the application (which has
129 its own namespace for CPP symbols) or a supporting library (that
130 shouldn't interfere with the application's CPP symbol namespace).
132 @cindex C++ header files
133 @cindex Header files and C++
134 Adapting C header files for use in C++ applications can use another
143 body of header file goes here
150 The idea here is that @code{__cplusplus} is defined only by C++
151 implementations, which will wrap the header file in an @samp{extern "C"}
152 block. Again, whether to use this trick is a matter of taste and
153 style. While the above can be seen as harmless, it could be argued
154 that the header file is written in C, and any C++ application using it
155 should explicitly use the @samp{extern "C"} block itself. Your
156 preference might depend on whether you consider the API exported by
157 your header file as something available for C programs only, or for C
158 and C++ programs alike.
164 The @code{ctime} function need not be reentrant, and consequently is
165 not required to be thread safe. Implementations of @code{ctime}
166 typically write the time stamp into static buffer. If two threads
167 call @code{ctime} at roughly the same time, you might end up with the
168 wrong date in one of the threads, or some undefined string. There is
169 a re-entrant interface @code{ctime_r}, that take a pre-allocated
170 buffer and length of the buffer, and return @code{NULL} on errors.
171 The input buffer should be at least 26 bytes in size. The output
172 string is locale-independent. However, years can have more than 4
173 digits if @code{time_t} is sufficiently wide, so the length of the
174 required output buffer is not easy to determine. Increasing the
175 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
176 sufficient. The @code{NULL} return value could mean some other error
177 condition, which will not go away by increasing the buffer size.
179 A more flexible function is @code{strftime}. However, note that it is
187 The @code{inet_ntoa} function need not be reentrant, and consequently
188 is not required to be thread safe. Implementations of
189 @code{inet_ntoa} typically write the time stamp into static buffer.
190 If two threads call @code{inet_ntoa} at roughly the same time, you
191 might end up with the wrong date in one of the threads, or some
192 undefined string. Further, @code{inet_ntoa} is specific for
193 @acronym{IPv4} addresses.
195 A protocol independent function is @code{inet_ntop}.
198 @node Out of memory handling
199 @section Out of memory handling
201 @cindex Out of Memory handling
202 @cindex Memory allocation failure
203 The GSS API does not have a standard error code for the out of memory
204 error condition. Instead of adding a non-standard error code, this
205 library has chosen to adopt a different strategy. Out of memory
206 handling happens in rare situations, but performing the out of memory
207 error handling after almost all API function invocations pollute your
208 source code and might make it harder to spot more serious problems.
209 The strategy chosen improve code readability and robustness.
211 @cindex Aborting execution
212 For most applications, aborting the application with an error message
213 when the out of memory situation occur is the best that can be wished
214 for. This is how the library behaves by default.
216 @vindex xalloc_fail_func
217 However, we realize that some applications may not want to have the
218 GSS library abort execution in any situation. The GSS library support
219 a hook to let the application regain control and perform its own
220 cleanups when an out of memory situation has occured. The application
221 can define a function (having a @code{void} prototype, i.e., no return
222 value and no parameters) and set the library variable
223 @code{xalloc_fail_func} to that function. The variable should be
227 extern void (*xalloc_fail_func) (void);
230 The GSS library will invoke this function if an out of memory error
231 occurs. Note that after this the GSS library is in an undefined
232 state, so you must unload or restart the application to continue call
233 GSS library functions. The hook is only intended to allow the
234 application to log the situation in a special way. Of course, care
235 must be taken to not allocate more memory, as that will likely also
239 @node Invoking gnulib-tool
240 @chapter Invoking gnulib-tool
243 @cindex invoking @command{gnulib-tool}
245 Run @samp{gnulib-tool --help}, and use the source.
246 @command{gnulib-tool} is the way to import Gnulib modules.
249 * Initial import:: First import of Gnulib modules.
250 * Importing updated files:: Subsequent imports.
251 * Finishing touches:: Simplifying imports.
256 @section Initial import
257 @cindex initial import
259 Gnulib assumes your project uses Autoconf and Automake. Invoking
260 @samp{gnulib-tool --import} will copy source files, create a
261 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
262 Autoconf M4 macro declarations used by @file{configure.ac}.
264 Our example will be a library that uses Autoconf, Automake and
265 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
266 the package portable to C89 (which doesn't have @code{strdup}).
269 ~/src/libfoo$ gnulib-tool --import strdup
270 Module list with included dependencies:
277 Creating ./lib/Makefile.am...
278 Creating ./m4/gnulib.m4...
281 Don't forget to add "lib/Makefile"
282 to AC_CONFIG_FILES in "./configure.ac" and to mention
283 "lib" in SUBDIRS in some Makefile.am.
287 By default, the source code is copied into @file{lib/} and the M4
288 macros in @file{m4/}. You can override these paths by using
289 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
290 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
291 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
293 @code{gnulib-tool} will overwrite any pre-existing files, in
294 particular @file{Makefile.am}. Unfortunately, separating the
295 generated @file{Makefile.am} content (for building the gnulib library)
296 into a separate file, say @file{gnulib.mk}, that could be included
297 by your handwritten @file{Makefile.am} is not possible, due to how
298 variable assignments are handled by Automake.
300 Consequently, it can be a good idea to chose directories that are not
301 already used by your projects, to separate gnulib imported files from
302 your own files. This approach can also be useful if you want to avoid
303 conflicts between other tools (e.g., @code{getextize} that also copy
304 M4 files into your package. Simon Josefsson successfully uses a source
305 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
308 A few manual steps are required to finish the initial import.
310 First, you need to make sure Autoconf can find the macro definitions
311 in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
312 top-level @file{Makefile.am} file, as in:
315 ACLOCAL_AMFLAGS = -I m4
318 Naturally, replace @file{m4} with the value from @code{--m4-base} or
319 @code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use:
322 ACLOCAL_AMFLAGS = -I gl/m4
325 You are now ready to call the M4 macros in @code{gnulib.m4} from
326 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
327 as possible after verifying that the C compiler is working.
328 Typically, this is immediately after @code{AC_PROG_CC}, as in:
337 The core part of the gnulib checks are done by the macro
338 @code{gl_INIT}. Place it further down in the file, typically where
339 you normally check for header files or functions. Or in a separate
340 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
350 You must also make sure that the gnulib library is built. Add the
351 @code{Makefile} in the gnulib source base directory to
352 @code{AC_CONFIG_FILES}, as in:
355 AC_CONFIG_FILES(... lib/Makefile ...)
358 If your gnulib source base is @file{gl}, you would use:
361 AC_CONFIG_FILES(... gl/Makefile ...)
364 You must also make sure that @code{make} work in the gnulib directory.
365 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
372 or if you, more likely, already have a few entries in @code{SUBDIRS},
373 you can add something like:
379 If you are using a gnulib source base of @code{gl}, you would use:
385 Finally, you have add C flags and LD flags, so that you can make use
386 of the gnulib library. For example:
390 AM_CPPFLAGS = -I$(top_srcdir)/lib
392 LIBADD = lib/libgnu.la
396 Don't forget to @code{#include} the various header files. In this
397 example, you would need to make sure that @samp{#include <strdup.h>}
398 is evaluated when compiling all source code files, that want to make
399 use of @code{strdup}.
402 @node Importing updated files
403 @section Importing updated files
405 From time to time, you may want to invoke @samp{gnulib-tool --import}
406 to update the files in your package. Once you have set up your
407 package for gnulib, this step is quite simple. For example:
410 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
411 Module list with included dependencies:
418 Creating ./lib/Makefile.am...
419 Creating ./m4/gnulib.m4...
422 Don't forget to add "lib/Makefile"
423 to AC_CONFIG_FILES in "./configure.ac" and to mention
424 "lib" in SUBDIRS in some Makefile.am.
428 If you don't recall how you invoked the tool last time, the commands
429 used (and the operations it resulted in) are placed in comments within
430 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
434 # Invoked as: gnulib-tool --import strdup
435 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
440 @node Finishing touches
441 @section Finishing touches
443 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
444 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
445 snprintf getline minmax}) can be tedious. To simplify this procedure,
446 you may put the command line parameters in your @file{configure.ac}.
458 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
463 This illustrate all macros defined in @file{gnulib.m4}. With the
464 above, importing new files are as simple as running @samp{gnulib-tool
465 --import} with no additional parameters.
467 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
468 @code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB}
469 macro can be used if you wish to change the library name (by default
470 @file{libgnu.a} or @file{libgnu.la} if you use libtool). The
471 @code{gl_MODULES} macro is used to specify which modules to import.
474 @node Copying This Manual
475 @appendix Copying This Manual
478 * GNU Free Documentation License:: License for copying this manual.