GNU Gnulib
**********

This manual is for GNU Gnulib (updated $Date: 2005-07-30 13:47:19 $), which is a library of common routines intended to be shared at the source level.

Copyright © 2004, 2005 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software.  Copies published by the Free Software Foundation raise funds for GNU development.''

Gnulib
******

This manual contains some bare-bones documentation, but not much more. It's mostly been a place to store notes until someone (you?) gets around to writing a coherent manual.

Getting started:

  * Gnulib is hosted at Savannah: http://savannah.gnu.org/projects/gnulib.  Get the sources through CVS from there.

  * The Gnulib home page: http://www.gnu.org/software/gnulib/.

Comments
========

Where to put comments describing functions: Because of risk of divergence, we prefer to keep most function describing comments in only one place: just above the actual function definition.  Some people prefer to put that documentation in the .h file.  In any case, it should appear in just one place unless you can ensure that the multiple copies will always remain identical.

Header files
============

It is a tradition to use CPP tricks to avoid parsing the same header file more than once, which might cause warnings.  The trick is to wrap the content of the header file (say, foo.h) in a block, as in:

     #ifndef FOO_H
     # define FOO_H
     ...
     body of header file goes here
     ...
     #endif /* FOO_H */

Whether to use FOO_H or _FOO_H is a matter of taste and style.  The C89 and C99 standards reserve all identifiers that begin with an underscore and either an uppercase letter or another underscore, for any use.  Thus, in theory, an application might not safely assume that _FOO_H has not already been defined by a library.  On the other hand, using FOO_H will likely lead the higher risk of collisions with other symbols (e.g., KEY_H, XK_H, BPF_H, which are CPP macro constants, or COFF_LONG_H, which is a CPP macro function).  Your preference may depend on whether you consider the header file under discussion as part of the application (which has its own namespace for CPP symbols) or a supporting library (that shouldn't interfere with the application's CPP symbol namespace).

Adapting C header files for use in C++ applications can use another CPP trick, as in:

     # ifdef __cplusplus
     extern "C"
     {
     # endif
     ...
     body of header file goes here
     ...
     # ifdef __cplusplus
     }
     # endif

The idea here is that __cplusplus is defined only by C++ implementations, which will wrap the header file in an extern "C" block.  Again, whether to use this trick is a matter of taste and style.  While the above can be seen as harmless, it could be argued that the header file is written in C, and any C++ application using it should explicitly use the extern "C" block itself.  Your preference might depend on whether you consider the API exported by your header file as something available for C programs only, or for C and C++ programs alike.

Include ordering
----------------

When writing a gnulib module, or even in general, a good way to order the #include directives is the following.

  * First comes the #include "..." specifying the module being implemented.

  * Then come all the #include <...> of system or system-replacement headers, in arbitrary order.

  * Then come all the #include "..." of gnulib and private headers, in arbitrary order.

Quoting
=======

Gnulib provides quote and quotearg modules to help with quoting text, such as file names, in messages to the user.  Here's an example of using quote:

     #include <quote.h>
      ...
       error (0, errno, _("cannot change owner of %s"), quote (fname));

This differs from

       error (0, errno, _("cannot change owner of `%s'"), fname);

in that quote escapes unusual characters in fname, e.g., ' and control characters like \n.

However, a caveat: quote reuses the storage that it returns. Hence if you need more than one thing quoted at the same time, you need to use quote_n.

Also, the quote module is not suited for multithreaded applications. In that case, you have to use quotearg_alloc, defined in the quotearg module, which is decidedly less convenient.

ctime
=====

The ctime function need not be reentrant, and consequently is not required to be thread safe.  Implementations of ctime typically write the time stamp into static buffer.  If two threads call ctime at roughly the same time, you might end up with the wrong date in one of the threads, or some undefined string.  There is a re-entrant interface ctime_r, that take a pre-allocated buffer and length of the buffer, and return NULL on errors. The input buffer should be at least 26 bytes in size.  The output string is locale-independent.  However, years can have more than 4 digits if time_t is sufficiently wide, so the length of the required output buffer is not easy to determine.  Increasing the buffer size when ctime_r return NULL is not necessarily sufficient. The NULL return value could mean some other error condition, which will not go away by increasing the buffer size.

A more flexible function is strftime.  However, note that it is locale dependent.

inet_ntoa
=========

The inet_ntoa function need not be reentrant, and consequently is not required to be thread safe.  Implementations of inet_ntoa typically write the time stamp into static buffer. If two threads call inet_ntoa at roughly the same time, you might end up with the wrong date in one of the threads, or some undefined string.  Further, inet_ntoa is specific for IPv4 addresses.

A protocol independent function is inet_ntop.

Out of memory handling
======================

The GSS API does not have a standard error code for the out of memory error condition.  Instead of adding a non-standard error code, this library has chosen to adopt a different strategy.  Out of memory handling happens in rare situations, but performing the out of memory error handling after almost all API function invocations pollute your source code and might make it harder to spot more serious problems. The strategy chosen improve code readability and robustness.

For most applications, aborting the application with an error message when the out of memory situation occur is the best that can be wished for.  This is how the library behaves by default.

However, we realize that some applications may not want to have the GSS library abort execution in any situation.  The GSS library support a hook to let the application regain control and perform its own cleanups when an out of memory situation has occured.  The application can define a function (having a void prototype, i.e., no return value and no parameters) and set the library variable xalloc_fail_func to that function.  The variable should be declared as follows.

     extern void (*xalloc_fail_func) (void);

The GSS library will invoke this function if an out of memory error occurs.  Note that after this the GSS library is in an undefined state, so you must unload or restart the application to continue call GSS library functions.  The hook is only intended to allow the application to log the situation in a special way.  Of course, care must be taken to not allocate more memory, as that will likely also fail.

Library version handling
========================

The module check-version can be useful when your gnulib application is a system library.  You will typically wrap the call to the check_version function through a library API, your library header file may contain:

     #define STRINGPREP_VERSION "0.5.18"
     ...
       extern const char *stringprep_check_version (const char *req_version);

To avoid ELF symbol collisions with other libraries that use the check-version module, add to config.h through a AC_DEFINE something like:

     AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])

The stringprep_check_version function will thus be implemented by the check_version module.

There are two uses of the interface.  The first is a way to provide for applications to find out the version number of the library it uses.  The application may contain diagnostic code such as:

       printf ("Stringprep version: header %s library %s",
               STRINGPREP_VERSION,
               stringprep_check_version (NULL));

Separating the library and header file version can be useful when searching for version mismatch related problems.

The second uses is as a rudimentary test of proper library version, by making sure the application get a library version that is the same, or newer, than the header file used when building the application.  This doesn't catch all problems, libraries may change backwards incompatibly in later versions, but enable applications to require a certain minimum version before it may proceed.

Typical uses look like:

            /* Check version of libgcrypt. */
            if (!gcry_check_version (GCRYPT_VERSION))
              die ("version mismatch\n");

Regular expressions
===================

Gnulib supports many different types of regular expressions; although the underlying features are the same or identical, the syntax used varies.  The descriptions given here for the different types are generated automatically.

     [file regexprops-generic.texi not included]

Invoking gnulib-tool
********************

Run gnulib-tool --help, and use the source. gnulib-tool is the way to import Gnulib modules.

Initial import
==============

Gnulib assumes your project uses Autoconf and Automake.  Invoking gnulib-tool --import will copy source files, create a Makefile.am to build them, and generate a gnulib.m4 with Autoconf M4 macro declarations used by configure.ac.

Our example will be a library that uses Autoconf, Automake and Libtool.  It calls strdup, and you wish to use gnulib to make the package portable to C89 (which doesn't have strdup).

     ~/src/libfoo$ gnulib-tool --import strdup
     Module list with included dependencies:
       strdup
     File list:
       lib/strdup.c
       lib/strdup.h
       m4/onceonly_2_57.m4
       m4/strdup.m4
     Creating ./lib/Makefile.am...
     Creating ./m4/gnulib.m4...
     Finished.

     You may need to add #include directives for the following .h files.
       #include "strdup.h"

     Don't forget to add "lib/Makefile"
     to AC_CONFIG_FILES in "./configure.ac" and to mention
     "lib" in SUBDIRS in some Makefile.am.
     ~/src/libfoo$

By default, the source code is copied into lib/ and the M4 macros in m4/.  You can override these paths by using --source-base=DIRECTORY and --m4-base=DIRECTORY, or by adding gl_SOURCE_BASE(DIRECTORY) and gl_M4_BASE(DIRECTORY) to your configure.ac. Some modules also provide other files necessary for building. These files are copied into the directory specified by AC_CONFIG_AUX_DIR in configure.ac or by the --aux-dir=DIRECTORY option. If neither is specified, the current directory is assumed.

gnulib-tool can make symbolic links instead of copying the source files. Use the --symbolic (or -s for short) option to do this.

gnulib-tool will overwrite any pre-existing files, in particular Makefile.am.  Unfortunately, separating the generated Makefile.am content (for building the gnulib library) into a separate file, say gnulib.mk, that could be included by your handwritten Makefile.am is not possible, due to how variable assignments are handled by Automake.

Consequently, it can be a good idea to chose directories that are not already used by your projects, to separate gnulib imported files from your own files.  This approach can also be useful if you want to avoid conflicts between other tools (e.g., getextize that also copy M4 files into your package.  Simon Josefsson successfully uses a source base of gl/, and a M4 base of gl/m4/, in several packages.

A few manual steps are required to finish the initial import.

First, you need to make sure Autoconf can find the macro definitions in gnulib.m4.  Use the ACLOCAL_AMFLAGS specifier in your top-level Makefile.am file, as in:

     ACLOCAL_AMFLAGS = -I m4

Naturally, replace m4 with the value from --m4-base or gl_M4_BASE.  If the M4 base is gl/m4 you would use:

     ACLOCAL_AMFLAGS = -I gl/m4

You are now ready to call the M4 macros in gnulib.m4 from configure.ac.  The macro gl_EARLY must be called as soon as possible after verifying that the C compiler is working. Typically, this is immediately after AC_PROG_CC, as in:

     ...
     AC_PROG_CC
     gl_EARLY
     ...

The core part of the gnulib checks are done by the macro gl_INIT.  Place it further down in the file, typically where you normally check for header files or functions.  Or in a separate section with other gnulib statements, such as gl_SOURCE_BASE. For example:

     ...
     # For gnulib.
     gl_INIT
     ...

gl_INIT will in turn call the macros related with the gnulib functions, be it specific gnulib macros, like gl_FUNC_ALLOCA or autoconf or automake macro like AC_FUNC_ALLOCA or AM_FUNC_GETLINE so there is no need to call those macros yourself when you use the corresponding gnulib modules.

You must also make sure that the gnulib library is built.  Add the Makefile in the gnulib source base directory to AC_CONFIG_FILES, as in:

     AC_CONFIG_FILES(... lib/Makefile ...)

If your gnulib source base is gl, you would use:

     AC_CONFIG_FILES(... gl/Makefile ...)

You must also make sure that make work in the gnulib directory. Add the gnulib source base directory to a SUBDIRS Makefile.am statement, as in:

     SUBDIRS = lib

or if you, more likely, already have a few entries in SUBDIRS, you can add something like:

     SUBDIRS += lib

If you are using a gnulib source base of gl, you would use:

     SUBDIRS += gl

Finally, you have to add compiler and linker flags in the appropriate source directories, so that you can make use of the gnulib library. Since some modules (getopt, for example) may copy files into the build directory, top_builddir/lib is needed as well as top_srcdir/lib.  For example:

     ...
     AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
     ...
     LIBADD = lib/libgnu.a
     ...

Don't forget to #include the various header files.  In this example, you would need to make sure that #include "strdup.h" is evaluated when compiling all source code files, that want to make use of strdup.

When an include file is provided by the gnulib you shouldn't try to include the corresponding system header files yourself but let the gnulib header file do it as the ordering of the definition for some symbols may be significant.

For example, to use the time_r gnulib module you should use include header file provided by the gnulib, and so #include "time_r.h", but you shouldn't explicitely #include <time.h> as it is already done in time_r.h before the redefinition of some symbols.

Importing updated files
=======================

From time to time, you may want to invoke gnulib-tool --import to update the files in your package.  Once you have set up your package for gnulib, this step is quite simple.  For example:

     ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
     Module list with included dependencies:
       strdup
     File list:
       lib/strdup.c
       lib/strdup.h
       m4/onceonly_2_57.m4
       m4/strdup.m4
     Creating ./lib/Makefile.am...
     Creating ./m4/gnulib.m4...
     Finished.

     Don't forget to add "lib/Makefile"
     to AC_CONFIG_FILES in "./configure.ac" and to mention
     "lib" in SUBDIRS in some Makefile.am.
     ~/src/libfoo$

If you don't recall how you invoked the tool last time, the commands used (and the operations it resulted in) are placed in comments within the generated Makefile.am and gnulib.m4, as in:

     ...
     # Invoked as: gnulib-tool --import strdup
     # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
     ...

Finishing touches
=================

Invoking gnulib-tool --import with the proper parameters (e.g., --m4-base gl/m4) and list of modules (e.g., strdup snprintf getline minmax) can be tedious.  To simplify this procedure, you may put the command line parameters in your configure.ac. For example:

     ...
     AC_PROG_CC
     gl_EARLY
     ...
     # For gnulib.
     gl_SOURCE_BASE(gl)
     gl_M4_BASE(gl/m4)
     gl_LIB(libgl)
     gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
     gl_INIT
     ...

This illustrate all macros defined in gnulib.m4.  With the above, importing new files are as simple as running gnulib-tool --import with no additional parameters.

The macros gl_EARLY, gl_INIT, gl_SOURCE_BASE, and gl_M4_BASE have been discussed earlier.  The gl_LIB macro can be used if you wish to change the library name (by default libgnu.a or libgnu.la if you use libtool).  The gl_MODULES macro is used to specify which modules to import.

Copying This Manual
*******************

     [file fdl.texi not included]