GNU Gnulib

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled “GNU Free
Documentation License”.

1.1 Gnulib Basics

While portability across operating systems is not one of GNU’s primary
goals, it has helped introduce many people to the GNU system, and is
worthwhile when it can be achieved at a low cost. This collection helps
lower that cost.

Gnulib is intended to be the canonical source for most of the important
“portability” and/or common files for GNU projects. These are files
intended to be shared at the source level; Gnulib is not a typical
library meant to be installed and linked against. Thus, unlike most
projects, Gnulib does not normally generate a source tarball
distribution; instead, developers grab modules directly from the
source repository.

The easiest, and recommended, way to do this is to use the
gnulib-tool script. Since there is no installation
procedure for Gnulib, gnulib-tool needs to be run directly
in the directory that contains the Gnulib source code. You can do
this either by specifying the absolute filename of
gnulib-tool, or by using a symbolic link from a place inside
your PATH to the gnulib-tool file of your preferred
Gnulib checkout. For example:

Sometimes, using an updated version of Gnulib will require you to use
newer versions of GNU Automake or Autoconf. You may find it helpful
to join the autotools-announce mailing list to be advised of such
changes.

1.4.1 Gnulib licensing

Gnulib contains code both under GPL and LGPL. Because several packages
that use Gnulib are GPL, the files state they are licensed under GPL.
However, to support LGPL projects as well, you may use some of the
files under LGPL. The “License:” information in the files under
modules/ clarifies the real license that applies to the module source.

Keep in mind that if you submit patches to files in Gnulib, you should
license them under a compatible license, which means that sometimes
the contribution will have to be LGPL, if the original file is
available under LGPL via a “License: LGPL” information in the
projects’ modules/ file.

1.4.2 Indent with spaces not TABs

We use space-only indentation in nearly all files. This includes all
*.h, *.c, *.y files, except for the regex
module. Makefile and ChangeLog files are excluded, since TAB
characters are part of their format.

In order to tell your editor to produce space-only indentation, you
can use these instructions.

For Emacs: Add these lines to your Emacs initialization file
($HOME/.emacs or similar):

1.4.3 How to add a new module

If the module needs configure-time checks, write an Autoconf
macro for it in m4/module.m4. See m4/README for details.

Write a module description modules/module, based on
modules/TEMPLATE.

If the module contributes a section to the end-user documentation,
put this documentation in doc/module.texi and add it to the “Files”
section of modules/module. Most modules don’t do this; they have only
documentation for the programmer (= Gnulib user). Such documentation
usually goes into the lib/ source files. It may also go into doc/;
but don’t add it to the module description in this case.

Add source files to config/srclist* if they are identical to upstream
and should be upgraded in Gnulib whenever the upstream source changes.

Include header files in source files to verify the function prototypes.

Make sure a replacement function doesn’t cause warnings or clashes on
systems that have the function.

Autoconf functions can use ‘gl_*’ prefix. The ‘AC_*’ prefix is for
autoconf internal functions.

Build files only if they are needed on a platform. Look at the
alloca and fnmatch modules for how to achieve this. If
for some reason you cannot do this, and you have a .c file that
leads to an empty .o file on some platforms (through some big
#if around all the code), then ensure that the compilation unit
is not empty after preprocessing. One way to do this is to
#include <stddef.h> or <stdio.h> before the big
#if.

1.4.4 Portability guidelines

Gnulib code is intended to be portable to a wide variety of platforms,
not just GNU platforms. See the documentation section “Target Platforms”
for details.

Many Gnulib modules exist so that applications need not worry about
undesirable variability in implementations. For example, an
application that uses the malloc module need not worry about
malloc (0) returning NULL on some Standard C
platforms; and time_r users need not worry about
localtime_r returning int (not char *) on some
platforms that predate POSIX 1003.1-2001.

Currently we assume at least a freestanding C89 compiler, possibly
operating with a C library that predates C89. The oldest environments
currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we
are not testing these platforms very often.

Because we assume a freestanding C89 compiler, Gnulib code can include
<float.h>, <limits.h>, <stdarg.h>, and
<stddef.h> unconditionally. It can also assume the existence
of <ctype.h>, <errno.h>, <fcntl.h>,
<locale.h>, <signal.h>, <stdio.h>,
<stdlib.h>, <string.h>, and <time.h>. Similarly,
many modules include <sys/types.h> even though it’s not even in
C99; that’s OK since <sys/types.h> has been around nearly
forever.

Even if the include files exist, they may not conform to C89.
However, GCC has a fixincludes script that attempts to fix most
C89-conformance problems. So Gnulib currently assumes include files
largely conform to C89 or better. People still using ancient hosts
should use fixincludes or fix their include files manually.

Even if the include files conform to C89, the library itself may not.
For example, strtod and mktime have some bugs on some platforms.
You can work around some of these problems by requiring the relevant
modules, e.g., the Gnulib mktime module supplies a working and
conforming mktime.

The GNU coding standards allow one departure from strict C99: Gnulib
code can assume that standard internal types like size_t are no wider
than long. POSIX 1003.1-2001 and the GNU coding standards both
require int to be at least 32 bits wide, so Gnulib code assumes this
as well. Gnulib code makes the following additional assumptions:

Signed integer arithmetic is two’s complement.

Previously, Gnulib code sometimes assumed that signed integer
arithmetic wraps around, but modern compiler optimizations
sometimes do not guarantee this, and Gnulib code with this
assumption is now considered to be questionable.
See Integer Properties.

Some Gnulib modules contain explicit support for the other signed
integer representations allowed by C99 (ones’ complement and signed
magnitude), but these modules are the exception rather than the rule.
All practical Gnulib targets use two’s complement.

There are no “holes” in integer values: all the bits of an integer
contribute to its value in the usual way.

Addresses and sizes behave as if objects reside in a flat address space.
In particular:

If two nonoverlapping objects have sizes S and T represented as
size_t values, then S + T cannot overflow.

If an existing object has size S, and if T is sufficiently
small (e.g., 8 KiB), then S + T cannot overflow.
Overflow in this case would mean that the rest of your program fits
into T bytes, which can’t happen in realistic flat-address-space
hosts.

Objects with all bits zero are treated as 0 or NULL. For example,
memset (A, 0, sizeof A) initializes an array A of
pointers to NULL.

The above assumptions are not required by the C or POSIX standards but
hold on all practical porting targets that we’re familiar with. If
you have a porting target where these assumptions are not true, we’d
appreciate hearing of any fixes. We need fixes that do not increase
runtime overhead on standard hosts and that are relatively easy to
maintain.

With the above caveats, Gnulib code should port without problem to new
hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
Hence Gnulib code should avoid using constructs (e.g., undeclared
functions return int) that do not conform to C99.

1.5 High Quality

We develop and maintain a testsuite for Gnulib. The goal is to have a
100% firm interface so that maintainers can feel free to update to the
code in git at any time and know that their application will not
break. This means that before any change can be committed to the
repository, a test suite program must be produced that exposes the bug
for regression testing. All experimental work should be done on
branches to help promote this.

2.1 Benefits of using Gnulib

Portability: With Gnulib, a package maintainer can program against the
POSIX and GNU libc APIs and nevertheless expect good portability to
platforms that don’t implement POSIX.

Maintainability: When a package uses modules from Gnulib instead of code
written specifically for that package, the maintainer has less code to
maintain.

Security: Gnulib provides functions that are immune against vulnerabilities
that plague the uses of the corresponding commonplace functions. For
example, asprintf, canonicalize_file_name are not affected
by buffer sizing problems that affect sprintf, realpath.
openat does not have the race conditions that open has. Etc.

Reliability: Gnulib provides functions that combine a call to a system
function with a check of the result. Examples are xalloc,
xprintf, xstrtod, xgetcwd.

Structure: Gnulib offers a way to structure code into modules, typically
one include file, one source code file, and one autoconf macro for each
functionality. Modularity helps maintainability.

2.2 Library vs. Reusable Code

Classical libraries are installed as binary object code. Gnulib is
different: It is used as a source code library. Each package that uses
Gnulib thus ships with part of the Gnulib source code. The used portion
of Gnulib is tailored to the package: A build tool, called
gnulib-tool, is provided that copies a tailored subset of Gnulib
into the package.

2.3 Portability and Application Code

One of the goals of Gnulib is to make portable programming easy, on
the basis of the standards relevant for GNU (and Unix). The objective
behind that is to avoid a fragmentation of the user community into
disjoint user communities according to the operating system, and
instead allow synergies between users on different operating systems.

Another goal of Gnulib is to provide application code that can be shared
between several applications. Some people wonder: "What? glibc doesn’t
have a function to copy a file?" Indeed, the scope of a system’s libc is
to implement the relevant standards (ISO C, POSIX) and to provide
access functions to the kernel’s system calls, and little more.

There is no clear borderline between both areas.

For example, Gnulib has a facility for generating the name of backup
files. While this task is entirely at the application level—no
standard specifies an API for it—the naïve code has
some portability problems because on some platforms the length of file
name components is limited to 30 characters or so. Gnulib handles
that.

Similarly, Gnulib has a facility for executing a command in a
subprocess. It is at the same time a portability enhancement (it
works on GNU, Unix, and Windows, compared to the classical
fork/exec idiom which is not portable to Windows), as well
as an application aid: it takes care of redirecting stdin and/or
stdout if desired, and emits an error message if the subprocess
failed.

2.4 Target Platforms

Gnulib supports a number of platforms that we call the “reasonable
portability targets”. This class consists of widespread operating systems,
for three years after their last availability, or—for proprietary
operating systems—as long as the vendor provides commercial support for
it. Already existing Gnulib code for older operating systems is usually
left in place for longer than these three years. So it comes that programs
that use Gnulib run pretty well also on these older operating systems.

Some operating systems are not very widespread, but are Free Software and
are actively developed. Such platforms are also supported by Gnulib, if
that OS’s developers community keeps in touch with the Gnulib developers,
by providing bug reports, analyses, or patches. For such platforms, Gnulib
supports only the versions of the last year or the last few months,
depending on the maturity of said OS project, the number of its users, and
how often these users upgrade.

Niche operating systems are generally unsupported by Gnulib, unless some
of their developers or users contribute support to Gnulib.

The degree of support Gnulib guarantees for a platform depends on the
amount of testing it gets from volunteers. Platforms on which Gnulib
is frequently tested are the best supported. Then come platforms with
occasional testing, then platforms which are rarely tested. Usually,
we fix bugs when they are reported. Except that some rarely tested
platforms are also low priority; bug fixes for these platforms can
take longer.

As of 2011, the list of supported platforms is the following:

glibc systems. With glibc 2.8 or newer, they are frequently tested. With
glibc 2.3 or newer, they are occasionally tested.

mingw is frequently tested. But note that some modules are currently
unsupported on mingw: mgetgroups, getugroups, idcache,
userspec, openpty, login_tty, forkpty,
pt_chown, grantpt, pty, savewd,
mkancesdirs, mkdir-p, euidaccess, faccessat.
The versions of Windows that are supported are Windows XP and newer.
Only the latest version of mingw is tested; older versions are not supported.

Native Windows, with MSVC as compiler, is rarely tested and low priority.

Gnulib supports these operating systems only in an unvirtualized environment.
When you run an OS inside a virtual machine, you have to be aware that the
virtual machine can bring in bugs of its own. For example, floating-point
operations on Solaris can behave slightly differently in QEMU than on real
hardware. And Haiku’s bash program misbehaves in VirtualBox 3,
whereas it behaves fine in VirtualBox 4.

Similarly, running native Windows binaries on GNU/Linux under WINE is
rarely tested and low priority: WINE has a set of behaviours and bugs that
is slightly different from native Windows.

The following platforms are not supported by Gnulib. The cost of
supporting them would exceed the benefit because they are rarely used, or
poorly documented, or have been supplanted by other platforms, or diverge
too much from POSIX, or some combination of these and other factors.
Please don’t bother sending us patches for them.

2.5 Modules

Gnulib is divided into modules. Every module implements a single
facility. Modules can depend on other modules.

A module consists of a number of files and a module description. The
files are copied by gnulib-tool into the package that will use it,
usually verbatim, without changes. Source code files (.h, .c files)
reside in the lib/ subdirectory. Autoconf macro files reside in
the m4/ subdirectory. Build scripts reside in the
build-aux/ subdirectory.

The module description contains the list of files; gnulib-tool
copies these files. It contains the module’s
dependencies; gnulib-tool installs them as well. It also
contains the autoconf macro invocation (usually a single line or
nothing at all); gnulib-tool ensures this is invoked from the
package’s configure.ac file. And also a Makefile.am
snippet; gnulib-tool collects these into a Makefile.am
for the tailored Gnulib part. The module description and include file
specification are for documentation purposes; they are combined into
MODULES.html.

The module system serves two purposes:

It ensures consistency of the used autoconf macros and Makefile.am
rules with the source code. For example, source code which uses the
getopt_long function—this is a common way to implement parsing
of command line options in a way that complies with the GNU standards—needs
the source code (lib/getopt.c and others), the autoconf macro
which detects whether the system’s libc already has this function (in
m4/getopt.m4), and a few Makefile.am lines that create the
substitute getopt.h if not. These three pieces belong together.
They cannot be used without each other. The module description and
gnulib-tool ensure that they are copied altogether into the
destination package.

It allows for scalability. It is well-known since the inception of the
MODULA-2 language around 1978 that dissection into modules with
dependencies allows for building large sets of code in a maintainable way.
The maintainability comes from the facts that:

Every module has a single purpose; you don’t worry about other parts of
the program while creating, reading or modifying the code of a module.

The code you have to read in order to understand a module is limited to
the source of the module and the .h files of the modules listed as
dependencies. It is for this reason also that we recommend to put the
comments describing the functions exported by a module into its .h file.

In other words, the module is the elementary unit of code in Gnulib,
comparable to a class in object-oriented languages like Java or C#.

The module system is the basis of gnulib-tool. When
gnulib-tool copies a part of Gnulib into a package, it first
compiles a module list, starting with the requested modules and adding all
the dependencies, and then collects the files, configure.ac
snippets and Makefile.am snippets.

2.6 Various Kinds of Modules

There are modules of various kinds in Gnulib. For a complete list of the
modules, see in MODULES.html.

2.6.1 Support for ISO C or POSIX functions.

When a function is not implemented by a system, the Gnulib module provides
an implementation under the same name. Examples are the ‘snprintf’
and ‘readlink’ modules.

Similarly, when a function is not correctly implemented by a system,
Gnulib provides a replacement. For functions, we use the pattern

#if !HAVE_WORKING_FOO
# define foo rpl_foo
#endif

and implement the foo function under the name rpl_foo. This
renaming is needed to avoid conflicts at compile time (in case the system
header files declare foo) and at link/run time (because the code
making use of foo could end up residing in a shared library, and
the executable program using this library could be defining foo
itself).

For header files, such as stdbool.h or stdint.h, we provide
the substitute only if the system doesn’t provide a correct one. The
template of this replacement is distributed in a slightly different name,
with ‘.in’ inserted before the ‘.h’ extension, so that on
systems which do provide a correct
header file the system’s one is used.

2.6.2 Enhancements of ISO C or POSIX functions

These are sometimes POSIX functions with GNU extensions also found in
glibc—examples: ‘getopt’, ‘fnmatch’—and often new
APIs—for example, for all functions that allocate memory in one way
or the other, we have variants which also include the error checking
against the out-of-memory condition.

2.6.3 Portable general use facilities

Examples are a module for copying a file—the portability problems
relate to the copying of the file’s modification time, access rights,
and extended attributes—or a module for extracting the tail
component of a file name—here the portability to native Windows
requires a different API than the classical POSIX basename function.

2.6.4 Reusable application code

Examples are an error reporting function, a module that allows output of
numbers with K/M/G suffixes, or cryptographic facilities.

2.6.5 Object oriented classes

Examples are data structures like ‘list’, or abstract output stream
classes that work around the fact that an application cannot implement an
stdio FILE with its logic. Here, while staying in C, we use
implementation techniques like tables of function pointers, known from the
C++ language or from the Linux kernel.

2.6.6 Interfaces to external libraries

Examples are the ‘iconv’ module, which interfaces to the
iconv facility, regardless whether it is contained in libc or in
an external libiconv. Or the ‘readline’ module, which
interfaces to the GNU readline library.

2.6.7 Build / maintenance infrastructure

An example is the ‘maintainer-makefile’ module, which provides extra
Makefile tags for maintaining a package.

2.7 Collaborative Development

Gnulib is maintained collaboratively. The mailing list is
<bug-gnulib at gnu dot org>. Be warned that some people on the
list may be very active at some times and unresponsive at other times.

Every module has one or more maintainers. While issues are discussed
collaboratively on the list, the maintainer of a module nevertheless has
a veto right regarding changes in his module.

All patches should be posted the list, regardless whether they are
proposed patches or whether they are committed immediately by the
maintainer of the particular module. The purpose is not only to inform
the other users of the module, but mainly to allow peer review. It is not
uncommon that several people contribute comments or spot bugs after a
patch was proposed.

Conversely, if you are using Gnulib, and a patch is posted that affects
one of the modules that your package uses, you have an interest in
proofreading the patch.

2.8 Copyright

Most modules are under the GPL. Some, mostly modules which can
reasonably be used in libraries, are under LGPL. The source files
always say "GPL", but the real license specification is in the module
description file. If the module description file says "GPL", it means
"GPLv3+" (GPLv3 or newer, at the licensee’s choice); if it says "LGPL",
it means "LGPLv3+" (LGPLv3 or newer, at the licensee’s choice).

More precisely, the license specification in the module description
file applies to the files in lib/ and build-aux/. Different
licenses apply to files in special directories:

If a license statement is not present in a test module, the test files are
under GPL. Even if the corresponding source module is under LGPL, this is
not a problem, since compiled tests are not installed by “make install”.

If you want to use some Gnulib modules under LGPL, you can do so by
passing the option ‘--lgpl’ to gnulib-tool. This will
replace the GPL header with an LGPL header while copying the source
files to your package. Similarly, if you want some Gnulib modules
under LGPLv2+ (Lesser GPL version 2.1 or newer), you can do so by
passing the option ‘--lgpl=2’ to gnulib-tool.

Keep in mind that when you submit patches to files in Gnulib, you should
license them under a compatible license. This means that sometimes the
contribution will have to be LGPL, if the original file is available
under LGPL. You can find out about it by looking for a "License: LGPL"
information in the corresponding module description.

If you are willing to report an occasional regression, we recommend to
use the newest version always, except in periods of major changes. Most
Gnulib users do this. If you prefer stable releases, please use the
newest stable release.

3 Invoking gnulib-tool

The gnulib-tool command is the recommended way to import
Gnulib modules. It is possible to borrow Gnulib modules in a package
without using gnulib-tool, relying only on the
meta-information stored in the modules/* files, but with a
growing number of modules this becomes tedious. gnulib-tool
simplifies the management of source files, Makefile.ams and
configure.ac in packages incorporating Gnulib modules.

gnulib-tool is not installed in a standard directory that is
contained in the PATH variable. It needs to be run directly in
the directory that contains the Gnulib source code. You can do this
either by specifying the absolute filename of gnulib-tool, or
you can also use a symbolic link from a place inside your PATH
to the gnulib-tool file of your preferred and most up-to-date
Gnulib checkout, like this:

$ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool

Run ‘gnulib-tool --help’ for information. To get familiar with
gnulib-tool without affecting your sources, you can also try
some commands with the option ‘--dry-run’; then
gnulib-tool will only report which actions it would perform in
a real run without changing anything.

3.2 Initial import

Gnulib assumes that your project uses Autoconf. When using Gnulib, you
will need to have Autoconf and Automake among your build tools. Note that
while the use of Automake in your project’s top level directory is an
easy way to fulfil the Makefile conventions of the GNU coding standards,
Gnulib does not require it. But when you use Gnulib, Automake will be
used at least in a subdirectory of your project.

Invoking ‘gnulib-tool --import’ will copy source files, create a
Makefile.am to build them, generate a file gnulib-comp.m4 with
Autoconf M4 macro declarations used by configure.ac, and generate
a file gnulib-cache.m4 containing the cached specification of how
Gnulib is used.

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 and C99 (which don’t have strdup).

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. 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. The option to specify for this is ‘--symlink’, or
‘-s’ for short. This can be useful to save a few kilobytes of disk
space. But it is likely to introduce bugs when gnulib is updated;
it is more reliable to use ‘gnulib-tool --update’ (see below)
to update to newer versions of gnulib. Furthermore it requires
extra effort to create self-contained tarballs, and it may disturb some
mechanism the maintainer applies to the sources. For these reasons,
this option is generally discouraged.

gnulib-tool will overwrite any pre-existing files, in
particular Makefile.am. It is also possible to separate the
generated Makefile.am content (for building the gnulib library)
into a separate file, say gnulib.mk, that can be included by your
handwritten Makefile.am, but this is a more advanced use of
gnulib-tool.

Consequently, it is a good idea to choose directories that are not
already used by your projects, to separate gnulib imported files from
your own files. This approach is also useful if you want to avoid
conflicts between other tools (e.g., gettextize 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.

After the ‘--import’ option on the command line comes the list of
Gnulib modules that you want to incorporate in your package. The names
of the modules coincide with the filenames in Gnulib’s modules/
directory.

Some Gnulib modules depend on other Gnulib modules. gnulib-tool
will automatically add the needed modules as well; you need not list
them explicitly. gnulib-tool will also memorize which dependent
modules it has added, so that when someday a dependency is dropped, the
implicitly added module is dropped as well (unless you have explicitly
requested that module).

If you want to cut a dependency, i.e., not add a module although one of
your requested modules depends on it, you may use the option
‘--avoid=module’ to do so. Multiple uses of this option are
possible. Of course, you will then need to implement the same interface
as the removed module.

A few manual steps are required to finish the initial import.
gnulib-tool printed a summary of these steps.

First, you must ensure Autoconf can find the macro definitions in
gnulib-comp.m4. Use the ACLOCAL_AMFLAGS specifier in
your top-level Makefile.am file, as in:

ACLOCAL_AMFLAGS = -I m4

You are now ready to call the M4 macros in gnulib-comp.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
...

If you are using AC_PROG_CC_STDC, the macro gl_EARLY must
be called after it, like this:

...
AC_PROG_CC
AC_PROG_CC_STDC
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. It must come after
other checks which may affect the compiler invocation, such as
AC_MINIX. 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 macros 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 ...)

You must also make sure that make will recurse into the gnulib
directory. To achieve this, 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

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:

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

In the usual case where Autoconf is creating a config.h file,
you should include config.h first, before any other include
file. That way, for example, if config.h defines
‘restrict’ to be the empty string on a pre-C99 host, or a macro
like ‘_FILE_OFFSET_BITS’ that affects the layout of data
structures, the definition is consistent for all include files.
Also, on some platforms macros like ‘_FILE_OFFSET_BITS’ and
‘_GNU_SOURCE’ may be ineffective, or may have only a limited
effect, if defined after the first system header file is included.

Finally, note that you cannot use AC_LIBOBJ or
AC_REPLACE_FUNCS in your configure.ac and expect the
resulting object files to be automatically added to lib/libgnu.a.
This is because your AC_LIBOBJ and AC_REPLACE_FUNCS invocations
from configure.ac augment a variable @LIBOBJS@ (and/or
@LTLIBOBJS@ if using Libtool), whereas lib/libgnu.a
is built from the contents of a different variable, usually
@gl_LIBOBJS@ (or @gl_LTLIBOBJS@ if using Libtool).

3.3 Modified imports

You can at any moment decide to use Gnulib differently than the last time.

There are two ways to change how Gnulib is used. Which one you’ll use,
depends on where you keep track of options and module names that you pass
to gnulib-tool.

If you store the options and module names in a file under your own
control, such as autogen.sh, bootstrap,
bootstrap.conf, or similar, simply invoke gnulib-tool
again, with modified options and more or fewer module names.

gnulib-tool remembers which modules were used last time. If you
want to rely on gnulib-tool’s own memory of the last used
options and module names, you can use the commands
gnulib-tool --add-import and
gnulib-tool --remove-import.

So, if you only want to use more Gnulib modules, simply invoke
gnulib-tool --add-import new-modules. The list of
modules that you pass after ‘--add-import’ is added to the
previous list of modules.

Similarly, if you want to use fewer Gnulib modules, simply invoke
gnulib-tool --remove-import unneeded-modules. The list
of modules that you pass after ‘--remove-import’ is removed
from the previous list of modules. Note that if a module is then still
needed as dependency of other modules, it will be used nevertheless.
If you want to really not use a module any more, regardless of
whether other modules may need it, you need to use the ‘--avoid’
option.

For other changes, such as different choices of ‘--lib’,
‘--source-base’ or ‘--aux-dir’, the normal way is to
modify manually the file gnulib-cache.m4 in the M4 macros
directory, then launch ‘gnulib-tool --add-import’.

The only change for which this doesn’t work is a change of the
‘--m4-base’ directory. Because, when you pass a different value of
‘--m4-base’, gnulib-tool will not find the previous
gnulib-cache.m4 file any more. A possible solution is to
manually copy the gnulib-cache.m4 into the new M4 macro directory.

In the gnulib-cache.m4 file, the macros have the following meaning:

gl_MODULES

The argument is a space separated list of the requested modules, not including
dependencies.

gl_AVOID

The argument is a space separated list of modules that should not be used,
even if they occur as dependencies. Corresponds to the ‘--avoid’
command line argument.

gl_SOURCE_BASE

The argument is the relative file name of the directory containing the gnulib
source files (mostly *.c and *.h files). Corresponds to the
‘--source-base’ command line argument.

gl_M4_BASE

The argument is the relative file name of the directory containing the gnulib
M4 macros (*.m4 files). Corresponds to the ‘--m4-base’ command line
argument.

gl_TESTS_BASE

The argument is the relative file name of the directory containing the gnulib
unit test files. Corresponds to the ‘--tests-base’ command line argument.

gl_LIB

The argument is the name of the library to be created. Corresponds to the
‘--lib’ command line argument.

gl_LGPL

The presence of this macro without arguments corresponds to the ‘--lgpl’
command line argument. The presence of this macro with an argument (whose
value must be 2 or 3) corresponds to the ‘--lgpl=arg’ command line
argument.

gl_LIBTOOL

The presence of this macro corresponds to the ‘--libtool’ command line
argument and to the absence of the ‘--no-libtool’ command line argument.
It takes no arguments.

gl_MACRO_PREFIX

The argument is the prefix to use for macros in the gnulib-comp.m4
file. Corresponds to the ‘--macro-prefix’ command line argument.

3.4 Simple update

When you want to update to a more recent version of Gnulib, without
changing the list of modules or other parameters, a simple call
does it:

$ gnulib-tool --add-import

This will create, update or remove files, as needed.

Note: From time to time, changes are made in Gnulib that are not backward
compatible. When updating to a more recent Gnulib, you should consult
Gnulib’s NEWS file to check whether the incompatible changes affect
your project.

3.5 Changing your sources for use with Gnulib

Gnulib contains some header file overrides. This means that when building
on systems with deficient header files in /usr/include/, it may create
files named string.h, stdlib.h, stdint.h or similar in
the build directory. In the other source directories of your package you
will usually pass ‘-I’ options to the compiler, so that these Gnulib
substitutes are visible and take precedence over the files in
/usr/include/.

These Gnulib substitute header files rely on <config.h> being
already included. Furthermore <config.h> must be the first include
in every compilation unit. This means that to all your source files
and likely also to all your tests source files you need to add an
‘#include <config.h>’ at the top. Which source files are affected?
Exactly those whose compilation includes a ‘-I’ option that refers to
the Gnulib library directory.

This is annoying, but inevitable: On many systems, <config.h> is
used to set system dependent flags (such as _GNU_SOURCE on GNU systems),
and these flags have no effect after any system header file has been included.

3.6 Caveat: gettextize and autopoint users

The programs gettextize and autopoint, part of
GNU gettext, import or update the internationalization infrastructure.
Some of this infrastructure, namely ca. 20 autoconf macro files and the
config.rpath file, is also contained in Gnulib and may be imported
by gnulib-tool. The use of gettextize or autopoint
will therefore overwrite some of the files that gnulib-tool has
imported, and vice versa.

Avoiding to use gettextize (manually, as package maintainer) or
autopoint (as part of a script like autoreconf or
autogen.sh) is not the solution: These programs also import the
infrastructure in the po/ and optionally in the intl/ directory.

The copies of the conflicting files in Gnulib are more up-to-date than
the copies brought in by gettextize and autopoint. When a
new gettext release is made, the copies of the files in Gnulib will
be updated immediately.

The choice of which version of gettext to require depends on the needs
of your package. For a package that wants to comply to GNU Coding
Standards, the steps are:

When you run gettextize, always use the gettextize from the
matching GNU gettext release. For the most recent Gnulib checkout, this is
the newest release found on http://ftp.gnu.org/gnu/gettext/. For an
older Gnulib snapshot, it is the release that was the most recent release
at the time the Gnulib snapshot was taken.

After running gettextize, invoke gnulib-tool and import
the gettext module. Also, copy the latest version of gnulib’s
build-aux/po/Makefile.in.in to your po/ directory (this
is done for you if you use gnulib’s bootstrap script).

If you get an error message like
*** error: gettext infrastructure mismatch:
using a Makefile.in.in from gettext version ...
but the autoconf macros are from gettext version ...,
it means that a new GNU gettext release was made, and its autoconf macros
were integrated into Gnulib and now mismatch the po/ infrastructure.
In this case, fetch and install the new GNU gettext release and run
gettextize followed by gnulib-tool.

On the other hand, if your package is not as concerned with compliance
to the latest standards, but instead favors development on stable
environments, the steps are:

Determine the oldest version of gettext that you intend to
support during development (at this time, gnulib recommends going no
older than version 0.17). Run autopoint (not
gettextize) to copy infrastructure into place (newer versions
of gettext will install the older infrastructure that you requested).

Invoke gnulib-tool, and import the gettext-h module.

Regardless of which approach you used to get the infrastructure in
place, the following steps must then be used to preserve that
infrastructure (gnulib’s bootstrap script follows these rules):

When a script of yours run autopoint, invoke gnulib-tool
afterwards.

When you invoke autoreconf after gnulib-tool, make sure to
not invoke autopoint a second time, by setting the AUTOPOINT
environment variable, like this:

3.7 Handling Gnulib’s own message translations

Gnulib provides some functions that emit translatable messages using GNU
gettext. The ‘gnulib’ domain at the
Translation Project collects
translations of these messages, which you should incorporate into your
own programs.

There are two basic ways to achieve this. The first, and older, method
is to list all the source files you use from Gnulib in your own
po/POTFILES.in file. This will cause all the relevant
translatable strings to be included in your POT file. When you send
this POT file to the Translation Project, translators will normally fill
in the translations of the Gnulib strings from their “translation
memory”, and send you back updated PO files.

However, this process is error-prone: you might forget to list some
source files, or the translator might not be using a translation memory
and provide a different translation than another translator, or the
translation might not be kept in sync between Gnulib and your package.
It is also slow and causes substantial extra work, because a human
translator must be in the loop for each language and you will need to
incorporate their work on request.

For these reasons, a new method was designed and is now recommended. If
you pass the --po-base=directory and --po-domain=domain
options to gnulib-tool, then gnulib-tool will create a
separate directory with its own POTFILES.in, and fetch current
translations directly from the Translation Project (using
rsync or wget, whichever is available).
The POT file in this directory will be called
domain-gnulib.pot, depending on the domain you gave to the
--po-domain option (typically the same as the package name).
This causes these translations to reside in a separate message domain,
so that they do not clash either with the translations for the main part
of your package nor with those of other packages on the system that use
possibly different versions of Gnulib.
When you use these options, the functions in Gnulib are built
in such a way that they will always use this domain regardless of the
default domain set by textdomain.

In order to use this method, you must—in each program that might use
Gnulib code—add an extra line to the part of the program that
initializes locale-dependent behavior. Where you would normally write
something like:

3.8 Issues with Version Control Systems

If a project stores its source files in a version control system (VCS),
such as CVS, Subversion, or Git, one needs to decide which files to commit.

In principle, all files created by gnulib-tool, except
gnulib-cache.m4, can be treated like generated source files,
like for example a parser.c file generated from
parser.y. Alternatively, they can be considered source files
and updated manually.

Here are the three different approaches in common use. Each has its
place, and you should use whichever best suits your particular project
and development methods.

In projects which commit all source files, whether generated or not,
into their VCS, the gnulib-tool generated files should all be
committed. In this case, you should pass the option
‘--no-vc-files’ to gnulib-tool, which avoids alteration of
VCS-related files such as .gitignore.

Gnulib also contains files generated by make (and removed by
make clean), using information determined by
configure. For a Gnulib source file of the form
lib/foo.in.h, the corresponding lib/foo.h is such a
make-generated file. These should not be checked
into the VCS, but instead added to .gitignore or equivalent.

In projects which customarily omit from their VCS all files that are
generated from other source files, none of these files and directories
are added into the VCS. As described in Modified imports, there
are two ways to keep track of options and module names that are passed
to gnulib-tool. The command for restoring the omitted files
depends on it:

If they are stored in a file other than gnulib-cache.m4, such as
autogen.sh, bootstrap, bootstrap.conf, or similar,
the restoration command is the entire gnulib-tool ... --import ...
invocation with all options and module names.

If the project relies on gnulib-tool’s memory of the last used
options and module names, then the file gnulib-cache.m4 in the M4
macros directory must be added to the VCS, and the restoration command
is:

$ gnulib-tool --update

The ‘--update’ option operates much like the ‘--add-import’
option, but it does not offer the possibility to change the way Gnulib is
used. Also it does not report in the ChangeLogs the files that it had to
add because they were missing.

Gnulib includes the file build-aux/bootstrap to aid a developer
in using this setup. Furthermore, in projects that use git for
version control, it is possible to use a git submodule containing the
precise commit of the gnulib repository, so that each developer
running bootstrap will get the same version of all
gnulib-provided files. The location of the submodule can be chosen to
fit the package’s needs; here’s how to initially create the submodule
in the directory .gnulib:

Thereafter, bootstrap can run this command to update the
submodule to the recorded checkout level:

git submodule update --init $dir

and a developer can use this sequence to update to a newer version of
gnulib:

$ git syncsub
$ git add $dir
$ ./bootstrap

Some projects take a “middle road”: they do commit Gnulib source
files as in the first approach, but they do not commit other derived
files, such as a Makefile.in generated by Automake. This
increases the size and complexity of the repository, but can help
occasional contributors by not requiring them to have a full Gnulib
checkout to do a build, and all developers by ensuring that all
developers are working with the same version of Gnulib in the
repository. It also supports multiple Gnulib instances within a
project. It remains important not to commit the
make-generated files, as described above.

3.9 Bundling the unit tests of the Gnulib modules

You can bundle the unit tests of the Gnulib modules together with your
package, through the ‘--with-tests’ option. Together with
‘--with-tests’, you also specify the directory for these tests
through the ‘--tests-base’ option. Of course, you need to add this
directory to the SUBDIRS variable in the Makefile.am of
the parent directory.

The advantage of having the unit tests bundled is that when your program
has a problem on a particular platform, running the unit tests may help
determine quickly if the problem is on Gnulib’s side or on your package’s
side. Also, it helps verifying Gnulib’s portability, of course.

The unit tests will be compiled and run when the user runs ‘make check’.
When the user runs only ‘make’, the unit tests will not be compiled.

In the SUBDIRS variable, it is useful to put the Gnulib tests directory
after the directory containing the other tests, not before:

SUBDIRS = gnulib-lib src man tests gnulib-tests

This will ensure that on platforms where there are test failures in either
directory, users will see and report the failures from the tests of your
program.

Note: In packages which use more than one invocation of gnulib-tool
in the scope of the same configure.ac, you cannot use
‘--with-tests’. You will have to use a separate configure.ac
in this case.

3.10 Avoiding unnecessary checks and compilations

In some cases, a module is needed by another module only on specific
platforms. But when a module is present, its autoconf checks are always
executed, and its Makefile.am additions are always enabled. So
it can happen that some autoconf checks are executed and some source files
are compiled, although no other module needs them on this particular
platform, just in case some other module would need them.

The option ‘--conditional-dependencies’ enables an optimization of
configure checks and Makefile.am snippets that avoids this. With
this option, whether a module is considered “present” is no longer decided
when gnulib-tool is invoked, but later, when configure is run.
This applies to modules that were added as dependencies while
gnulib-tool was run; modules that were passed on the command line
explicitly are always “present”.

For example, the timegm module needs, on platforms
where the system’s timegm function is missing or buggy, a replacement
that is based on a function mktime_internal. The module
mktime-internal that provides this function provides it on all
platforms. So, by default, the file mktime-internal.c will be
compiled on all platforms, even on glibc and BSD systems which have a
working timegm function. When the option
‘--conditional-dependencies’ is given, on the other hand, and if
mktime-internal was not explicitly required on the command line,
the file mktime-internal.c will only be compiled on the platforms
where the timegm needs them.

Conditional dependencies are specified in the module description by putting
the condition on the same line as the dependent module, enclosed in brackets.
The condition is a boolean shell expression that can assume that the
configure.ac snippet from the module description has already been
executed. In the example above, the dependency from timegm to
mktime-internal is written like this:

Note: The option ‘--conditional-dependencies’ cannot be used together
with the option ‘--with-tests’. It also cannot be used when a package
uses gnulib-tool for several subdirectories, with different values
of ‘--source-base’, in the scope of a single configure.ac file.

4 Writing modules

This chapter explains how to write modules of your own, either to
extend Gnulib for your own package (see Extending Gnulib), or for
inclusion in gnulib proper.

The guidelines in this chapter do not necessarily need to be followed for
using gnulib-tool. They merely represent a set of good practices.
Following them will result in a good structure of your modules and in
consistency with gnulib.

4.1 Source code files

Every API (C functions or variables) provided should be declared in a header
file (.h file) and implemented in one or more implementation files (.c files).
The separation has the effect that users of your module need to read only
the contents of the .h file and the module description in order to understand
what the module is about and how to use it—not the entire implementation.
Furthermore, users of your module don’t need to repeat the declarations of
the functions in their code, and are likely to receive notification through
compiler errors if you make incompatible changes to the API (like, adding a
parameter or changing the return type of a function).

4.2 Header files

The .h file should declare the C functions and variables that the module
provides.

The .h file should be stand-alone. That is, it does not require other .h files
to be included before. Rather, it includes all necessary .h files by itself.

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:

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:

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.

Note that putting a #include in an extern "C" { ... }
block yields a syntax error in C++ mode on some platforms (e.g., glibc
systems with g++ v3.3 to v4.2, AIX, OSF/1, IRIX). For this reason, it
is recommended to place the #include before the extern
"C" block.

4.3 Implementation files

The .c file or files implement the functions and variables declared in the
.h file.

Include ordering

Every implementation file must start with ‘#include <config.h>’.
This is necessary for activating the preprocessor macros that are defined
on behalf of the Autoconf macros. Some of these preprocessor macros,
such as _GNU_SOURCE, would have no effect if defined after a system
header file has already been included.

Then comes the ‘#include "..."’ specifying the header file that is
being implemented. Putting this right after ‘#include <config.h>’
has the effect that it verifies that the header file is self-contained.

Then come the system and application headers. It is customary to put all the
system headers before all application headers, so as to minimize the risk
that a preprocessor macro defined in an application header confuses the system
headers on some platforms.

In summary:

First comes #include <config.h>.

Second 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 application headers, in
arbitrary order.

4.5 Module description

For the module description, you can start from an existing module’s
description, or from a blank one: module/TEMPLATE for a normal module,
or module/TEMPLATE-TESTS for a unit test module. Some more fields
are possible but rarely used. Use module/TEMPLATE-EXTENDED if you
want to use one of them.

Module descriptions have the following fields. Absent fields are equivalent
to fields with empty contents.

Description

This field should contain a concise description of the module’s functionality.
One sentence is enough. For example, if it defines a single function
‘frob’, the description can be ‘frob() function: frobnication.’
Gnulib’s documentation generator will automatically convert the first part
to a hyperlink when it has this form.

Status

This field is either empty/absent, or contains the word ‘obsolete’. In
the latter case, gnulib-tool will, unless the option
--with-obsolete is given, omit it when it used as a dependency. It is
good practice to also notify the user about an obsolete module. This is done
by putting into the ‘Notice’ section (see below) text like
‘This module is obsolete.’

Notice

This field contains text that gnulib-tool will show to the user
when the module is used. This can be a status indicator like
‘This module is obsolete.’ or additional advice. Do not abuse this
field.

Applicability

This field is either empty/absent, or contains the word ‘all’. It
describes to which Makefile.am the module is applied. By default,
a normal module is applied to source_base/Makefile.am
(normally lib/Makefile.am), whereas a module ending in -tests
is applied to tests_base/Makefile.am (normally
tests/Makefile.am). If this field is ‘all’, it is applied to
both Makefile.ams. This is useful for modules which provide
Makefile.am macros rather than compiled source code.

Files

This field contains a newline separated list of the files that are part of
the module. gnulib-tool copies these files into the package that
uses the module.

This list is typically ordered by importance: First comes the header file,
then the implementation files, then other files.

It is possible to have the same file mentioned in multiple modules. That is,
if the maintainers of that module agree on the purpose and future of said
file.

Depends-on

This field contains a newline separated list of the modules that are required
for the proper working of this module. gnulib-tool includes each
required module automatically, unless it is specified with option
--avoid or it is marked as obsolete and the option
--with-obsolete is not given.

A test modules foo-tests implicitly depends on the corresponding non-test
module foo. foo implicitly depends on foo-tests if the
latter exists and if the option --with-tests has been given.

Tests modules can depend on non-tests modules. Non-tests modules should not
depend on tests modules. (Recall that tests modules are built in a separate
directory.)

Each listed required module may be declared a conditional dependency. This
is indicated by placing the condition for the dependency on the same line,
enclosed in brackets, after the name of the required module. The condition
is a shell expression that is run after the module’s configure.ac
statements. For example:

strtoull [test $ac_cv_func_strtoumax = no]

Lines starting with # are recognized as comments and are ignored.

configure.ac-early

This field contains configure.ac stuff (Autoconf macro invocations and
shell statements) that are logically placed early in the configure.ac
file: right after the AC_PROG_CC invocation. This section is adequate
for statements that modify CPPFLAGS, as these can affect the results of
other Autoconf macros.

It is forbidden to add items to the CPPFLAGS variable here, other than
temporarily, as these could affect the results of other Autoconf macros.

We avoid adding items to the LIBS variable, other than temporarily.
Instead, the module can export an Autoconf-substituted variable that contains
link options. The user of the module can then decide to which executables
to apply which link options. Recall that a package can build executables of
different kinds and purposes; having all executables link against all
libraries is inappropriate.

If the statements in this section grow larger than a couple of lines, we
recommend moving them to a .m4 file of their own.

Makefile.am

This field contains Makefile.am statements. Variables like
lib_SOURCES are transformed to match the name of the library
being built in that directory. For example, lib_SOURCES may become
libgnu_a_SOURCES (for a plain library) or libgnu_la_SOURCES
(for a libtool library). Therefore, the normal way of having an
implementation file lib/foo.c compiled unconditionally is to write

lib_SOURCES += foo.c

Include

This field contains the preprocessor statements that users of the module
need to add to their source code files. Typically it’s a single include
statement. A shorthand is allowed: You don’t need to write the word
“#include”, just the name of the include file in the way it will appear
in an include statement. Example:

"foo.h"

Link

This field contains the set of libraries that are needed when linking
libraries or executables that use this module. Often this will be
written as a reference to a Makefile variable. Please write them
one per line, so that gnulib-tool can remove duplicates
when presenting a summary to the user.
Example:

4.6 Autoconf macros

For a module foo, an Autoconf macro file m4/foo.m4 is typically
created when the Autoconf macro invocations for the module are longer than
one or two lines.

The name of the main entry point into this Autoconf macro file is typically
gl_FOO. For modules outside Gnulib that are not likely to be moved
into Gnulib, please use a prefix specific to your package: gt_ for
GNU gettext, cu_ for GNU coreutils, etc.

For modules that define a function foo, the entry point is called
gl_FUNC_FOO instead of gl_FOO. For modules that provide a
header file with multiple functions, say foo.h, the entry point is
called gl_FOO_H or gl_HEADER_FOO_H. This convention is useful
because sometimes a header and a function name coincide (for example,
fcntl and fcntl.h).

For modules that provide a replacement, it is useful to split the Autoconf
macro into two macro definitions: one that detects whether the replacement
is needed and requests the replacement using AC_LIBOBJ (this is the
entry point, say gl_FUNC_FOO), and one that arranges for the macros
needed by the replacement code lib/foo.c (typically called
gl_PREREQ_FOO). The reason of this separation is

to make it easy to update the Autoconf macros when you have modified the
source code file: after changing lib/foo.c, all you have to review
is the Depends-on section of the module description and the
gl_PREREQ_FOO macro in the Autoconf macro file.

The Autoconf macros are often large enough that splitting them eases
maintenance.

Second comes the include of the header file that declares the API being tested.
Including it here verifies that said header file is self-contained.

Then come other includes. In particular, the file macros.h is often
used here. It contains a convenient ASSERT macro.

The body of the test, then, contains many ASSERT invocations. When
a test fails, the ASSERT macro prints the line number of the failing
statement, thus giving you, the developer, an idea of which part of the test
failed, even when you don’t have access to the machine where the test failed
and the reporting user cannot run a debugger.

Sometimes it is convenient to write part of the test as a shell script.
(For example, in areas related to process control or interprocess
communication, or when different locales should be tried.) In these cases,
the typical module description is like this:

Here, the TESTS_ENVIRONMENT variable can be used to pass values
determined by configure or by the Makefile to the shell
script, as environment variables. The values of EXEEXT and of
srcdir, from Autoconf and Automake, are already provided as
environment variables, through an initial value of TESTS_ENVIRONMENT
that gnulib-tool puts in place.

Regardless of the specific form of the unit test, the following guidelines
should be respected:

A test indicates success by exiting with exit code 0. It should normally
not produce output in this case. (Output to temporary files that are
cleaned up at the end of the test are possible, of course.)

A test indicates failure by exiting with an exit code different from 0 and 77,
typically 1. It is useful to print a message about the failure in this case.
The ASSERT macro already does so.

A test indicates "skip", that is, that most of its interesting functionality
could not be performed, through a return code of 77. A test should also
print a message to stdout or stderr about the reason for skipping.
For example:

5 Extending Gnulib

Gnulib modules are intended to be suitable for widespread use. Most
problems with Gnulib can and should be fixed in a generic way, so that
all of Gnulib’s users can benefit from the change. But occasionally a
problem arises that is difficult or undesirable to fix generically, or
a project that uses Gnulib may need to work around an issue before the
Gnulib maintainers commit a final fix. Maintainers may also want to
add their own pools of modules to projects as Gnulib “staging
areas.”

The obvious way to make local changes to Gnulib modules is to use
gnulib-tool to check out pristine modules, then to modify
the results in-place. This works well enough for short-lived
experiments. It is harder to keep modified versions of Gnulib modules
for a long time, even though Git (or another distributed version
control systems) can help out a lot with this during the development
process.

Git, however, doesn’t address the distribution issue. When a package
“foobar” needs a modified version of, say, stdint.in.h, it
either has to put a comment into foobar/autogen.sh saying
“Attention! This doesn’t work with a pristine Gnulib, you need this
and that patch after checking out Gnulib,” or it has to use the
‘--avoid=stdint’ option and provide the modified stdint
module in a different directory.

The --local-dir option to gnulib-tool solves this
problem. It allows the package to override or augment Gnulib. This
means:

You can store files that are to override Gnulib files or modules.

You can store context diffs to be applied to Gnulib files.

You can add modules of your own, that are not (yet) in Gnulib.

You can also add unstructured amounts of code to the library, by
grouping the non-Gnulib files of the library in a single kitchen-sink
“module.” (This kind of kitchen-sink module is not needed when you
use the gnulib-tool option ‘--makefile-name’.)

In a release tarball, you can distribute the contents of this
--local-dir directory that will be combinable with newer
versions of Gnulib, barring incompatible changes to Gnulib.

If the ‘--local-dir=directory’ option is specified, then
gnulib-tool looks in directory whenever it
reads a file from the Gnulib directory. Suppose gnulib-tool
is looking for file. Then:

If directory/file exists, then ‘gnulib-tool’ uses
it instead of the file included in Gnulib.

Otherwise, if directory/file.diff exists, then
gnulib-tool uses the file from Gnulib after applying the diff
using the patch program.

Otherwise, gnulib-tool uses the file included in Gnulib.

Please make wise use of this option. It also allows you to easily
hold back modifications you make to Gnulib macros in cases it may be
better to share them.

6.1 Out of memory handling

The gnulib API does not have a standard error code for the out of memory
error condition. Instead of adding a non-standard error code, gnulib
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 improves code readability and robustness.

For most applications, aborting the application with an error message
when the out of memory situation occurs is the best that can be wished
for. This is how the library behaves by default (using
the ‘xalloc-die’ module).

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

extern void (*xalloc_die) (void);

Gnulib will invoke this function if an out of memory error occurs. Note
that the function should not return. Of course, care must be taken to
not allocate more memory, as that will likely also fail.

6.2 Obsolete modules

Modules can be marked obsolete. This means that the problems they fix
don’t occur any more on the platforms that are reasonable porting targets
now. gnulib-tool warns when obsolete modules are mentioned on the
command line, and by default ignores dependencies from modules to obsolete
modules. When you pass the option --with-obsolete to
gnulib-tool, dependencies to obsolete modules will be included,
however, unless blocked through an --avoid option. This option
is useful if your package should be portable even to very old platforms.

In order to mark a module obsolete, you need to add this to the module
description:

6.3 Extra tests modules

Test modules can be marked with some special status attributes. When a
test module has such an attribute, gnulib-tool --import will not
include it by default.

The supported status attributes are:

c++-test

Indicates that the test is testing C++ interoperability. Such a test is
useful in a C++ or mixed C/C++ package, but is useless in a C package.

longrunning-test

Indicates that the test takes a long time to compile or execute (more
than five minutes or so). Such a test is better avoided in a release
that is made for the general public.

privileged-test

Indicates that the test will request special privileges, for example,
ask for the superuser password. Such a test may hang when run
non-interactively and is therefore better avoided in a release that is
made for the general public.

unportable-test

Indicates that the test is known to fail on some systems, and that
there is no workaround about it. Such a test is better avoided in a
release that is made for the general public.

gnulib-tool --import --with-tests will not include tests marked with
these attributes by default. When gnulib-tool is invoked with one
of the options --with-c++-tests, --with-longrunning-tests,
--with-privileged-tests, --with-unportable-tests, it
will include tests despite the corresponding special status attribute.
When gnulib-tool receives the option --with-all-tests,
it will include all tests regardless of their status attributes.

gnulib-tool --create-testdir --with-tests and
gnulib-tool --create-megatestdir --with-tests by default include all
tests of modules specified on the command line, regardless of their status
attributes. Tests of modules occurring as dependencies are not included
by default if they have one of these status attributes. The options
--with-c++-tests, --with-longrunning-tests,
--with-privileged-tests, --with-unportable-tests are
recognized here as well. Additionally, gnulib-tool also
understands the options --without-c++-tests,
--without-longrunning-tests, --without-privileged-tests,
--without-unportable-tests.

In order to mark a module with a status attribute, you need to add it
to the module description, like this:

Status:
longrunning-test

If only a part of a test deserves a particular status attribute, you
can split the module into a primary and a secondary test module,
say foo-tests and foo-extra-tests. Then add a dependency
from foo-tests to foo-extra-tests, and mark the
foo-extra-tests with the particular status attribute.

6.4 A C++ namespace for gnulib

The function definitions provided by Gnulib (.c code) are meant
to be compiled by a C compiler. The header files (.h files),
on the other hand, can be used in either C or C++.

By default, when used in a C++ compilation unit, the .h files
declare the same symbols and overrides as in C mode, except that functions
defined by Gnulib or by the system are declared as ‘extern "C"’.

It is also possible to indicate to Gnulib to provide many of its symbols
in a dedicated C++ namespace. If you define the macro
GNULIB_NAMESPACE to an identifier, many functions will be defined
in the namespace specified by the identifier instead of the global
namespace. For example, after you have defined

#define GNULIB_NAMESPACE gnulib

at the beginning of a compilation unit, Gnulib’s <fcntl.h> header
file will make available the open function as gnulib::open.
The symbol open will still refer to the system’s open function,
with its platform specific bugs and limitations.

The symbols provided in the Gnulib namespace are those for which the
corresponding header file contains a _GL_CXXALIAS_RPL or
_GL_CXXALIAS_SYS macro invocation.

The benefits of this namespace mode are:

Gnulib defines fewer symbols as preprocessor macros. For example, on a
platform where open has to be overridden, Gnulib normally does
#define open rpl_open. If your package has a class with a member
open, for example a class foo with a method foo::open,
then if you define this member in a compilation unit that includes
<fcntl.h> and use it in a compilation unit that does not include
<fcntl.h>, or vice versa, you will get a link error. Worse: You
will not notice this problem on the platform where the system’s open
function works fine. This problem goes away in namespace mode.

It provides a safety check whether the set of modules your package requests
from Gnulib is sufficient. For example, if you use the function
gnulib::open in your code, and you forgot to request the module
‘open’ from Gnulib, you will get a compilation error (regardless of
the platform).

The drawback of this namespace mode is that the system provided symbols in
the global namespace are still present, even when they contain bugs that
Gnulib fixes. For example, if you call open (...) in your code,
it will invoke the possibly buggy system function, even if you have
requested the module ‘open’ from gnulib-tool.

You can turn on the namespace mode in some compilation units and keep it
turned off in others. This can be useful if your package consists of
an application layer that does not need to invoke POSIX functions and
an operating system interface layer that contains all the OS function
calls. In such a situation, you will want to turn on the namespace mode
for the application layer—to avoid many preprocessor macro
definitions—and turn it off for the OS interface layer—to avoid
the drawback of the namespace mode, mentioned above.

6.5 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:

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.

6.8 License Texinfo sources

Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
in Texinfo form. (The master location is
http://www.gnu.org/licenses/). These Texinfo documents do not
have any node names and structures built into them; for your manual,
you should @include them in an appropriate @node.

The conventional name for the GPL node is ‘Copying’ and for the FDL
‘GNU Free Documentation License’. The LGPL doesn’t seem to have
a conventional node name.

The command ‘posix-modules’ is found in the same directory as
gnulib-tool.

The resulting directory can be built on a particular platform,
independently of the program being ported. Then you can configure and
build any program, by setting CPPFLAGS and LDFLAGS at
configure time accordingly: set CPPFLAGS="-I.../posixlib/lib", plus
any essential type definitions and flags that you find in
.../posixlib/config.h, and set
LDFLAGS=".../posixlib/lib/libgnu.a".

This way of using Gnulib is useful when you don’t want to modify the program’s
source code, or when the program uses a mix between C and C++ sources
(requiring separate builds of the posixlib for the C compiler and
for the C++ compiler).

8 ISO C and POSIX Header File Substitutes

This chapter describes which header files specified by ISO C or POSIX are
substituted by Gnulib, which portability pitfalls are fixed by Gnulib, and
which (known) portability problems are not worked around by Gnulib.

The notation “Gnulib module: —” means that Gnulib does not provide a
module providing a substitute for the header file. When the list
“Portability problems not fixed by Gnulib” is empty, such a module is
not needed: No portability problems are known. Otherwise, it indicates
that such a module would be useful but is not available: No one so far
found this header file important enough to contribute a substitute for it.
If you need this particular header file, you may write to
<bug-gnulib at gnu dot org>.

8.3 assert.h

The C11 and C++11 static_assert, and the C11
_Static_assert, are not supported by many platforms.
For example, GCC versions before 4.6.0 do not support _Static_assert,
and G++ versions through at least 4.6.0 do not support static_assert.

Portability problems not fixed by Gnulib:

C11 _Static_assert and C++11 static_assert
are keywords that can be used without including <assert.h>.
The Gnulib substitutes are macros that require including <assert.h>.

The C11 static_assert and _Static_assert can also
be used within a struct or union specifier, in place of
an ordinary declaration of a member of the struct or union. The
Gnulib substitute can be used only as an ordinary declaration.

In C99, assert can be applied to any scalar expression.
In C89, the argument to assert is of type int.

‘O_CLOEXEC’, ‘O_DIRECTORY’, ‘O_DSYNC’, ‘O_NOCTTY’,
‘O_NOFOLLOW’, ‘O_RSYNC’, ‘O_SYNC’,
and ‘O_TTY_INIT’ are not defined on some platforms. Gnulib defines
these macros to 0, which is generally safe.

‘O_NONBLOCK’ is not defined on some platforms. If the
‘nonblocking’ module is in use, gnulib guarantees a working
non-zero value; otherwise, the gnulib replacement is 0.

‘O_EXEC’ and ‘O_SEARCH’ are not defined on some platforms.
Gnulib defines these macros to ‘O_RDONLY’, which is typically 0.
The ‘O_PATH’ macro of GNU/Linux is not a suitable substitute, as
fchmod fails with ‘errno==EBADF’ when invoked on a file
descriptor that was opened with ‘O_PATH’.

‘O_ACCMODE’ is not defined on some platforms:
MSVC 9.

The ‘O_ACCMODE’ mask mistakenly omits ‘O_SEARCH’ and
‘O_EXEC’ on some platforms:
Cygwin.

‘O_BINARY’, ‘O_TEXT’ (not specified by POSIX, but essential for
portability to native Windows platforms) are defined on some platforms but
not on others.

‘O_CLOEXEC’, ‘O_NOFOLLOW’, and ‘O_TTY_INIT’
are defined to values that are too large for an int on some platforms:
AIX 7.1 with XL C 12.1.

‘O_DIRECT’, ‘O_IGNORE_CTTY’, ‘O_NDELAY’,
‘O_NOATIME’, ‘O_NOLINK’, ‘O_NOLINKS’, and
‘O_NOTRANS’ (not specified by POSIX) are defined
on some platforms but not on others.

‘FD_CLOEXEC’, ‘F_DUPFD’, and ‘F_GETFD’ are not defined
on some platforms:
mingw, MSVC 9.

8.12 float.h

The conversion from int to long double in incorrect on some
platforms:
glibc 2.7 on Linux/SPARC64.

The values of LDBL_* macros are incorrect on some platforms:
On OpenBSD 4.0, MirBSD 10, and BeOS, they are the same as the values of the
DBL_* macros, although ‘long double’ is a larger type than
‘double’.
On FreeBSD/x86 6.4, they represent the incorrect 53-bit precision assumptions
in the compiler, not the real 64-bit precision at runtime.
On Linux/PowerPC with GCC 4.4, on AIX 7.1 with GCC 4.2, and on IRIX 6.5,
they don’t reflect the “double double” representation of long double
correctly.

Portability problems not fixed by Gnulib:

The macro FLT_ROUNDS is a constant expression and does not represent
the current rounding mode on some platforms:
glibc 2.11, HP-UX 11, mingw.

8.35 pthread.h

This header pollutes the namespace with some broken macro
implementations for various functions such as strtok_r and
gmtime_r:
mingw 3.0.

Portability problems not fixed by Gnulib:

This header file is missing on some platforms; the replacement does
not offer threads, so much as lightweight stubs that make conditional
compilation easier for fallbacks to single-threaded programs.
Minix 3.1.8, mingw 2.x, MSVC 9, BeOS.

The alignof and _Alignof macros return too large values for
the types double and long long in GCC 4.7.0.

Portability problems not fixed by Gnulib:

In ISO C11, the operand of alignof/_Alignof must be a
parenthesized type. Recent versions of GCC support an extension in
which the operand can also be a unary expression, as with
sizeof. The Gnulib substitute does not support this extension.

_Alignas and alignas are not always supported;
on platforms lacking support, the
macro __alignas_is_defined is not defined.
Supported compilers include GCC, IBM C, Sun C 5.11 and later,
and MSVC 7.0 and later.

Some compilers do not support alignment via
alignas/_Alignas of auto variables (i.e.,
variables on the stack). They diagnose and ignore the alignment: Sun
C 5.11.

Some linkers do not support operands of _Alignas/alignas
that are greater than 8: mingw.

Some compilers require the operand of _Alignas/alignas
to be a single integer constant, not an expression: MSVC 7.0 through
at least 10.0.

The Sun C 5.11 compiler sometimes mishandles the alignment of multiple
external variables that are declared close together with
_Alignas/alignas. This compiler bug causes the Gnulib
module stdalign-tests to fail. The Sun Studio Developer Bug
Report Review Team assigned the internal review ID 2125432 (dated
2011-11-01) to this issue.

<stdalign.h> must be #included before _Alignas and
_Alignof can be used.

You cannot assume that _Alignas and _Alignof are reserved words;
they might be macros.

8.47 stddef.h

Some platforms provide a NULL macro that cannot be used in arbitrary
expressions:
NetBSD 5.0

Portability problems not fixed by Gnulib:

Some platforms provide an offsetof macro that cannot be used in
arbitrary expressions:
Solaris 11 2011-11
This problem can be worked around by parenthesizing the
offsetof expression in the unlikely case you use it with
sizeof or ‘[]’.

The values of SIG_ATOMIC_MIN and SIG_ATOMIC_MAX are incorrect
on some platforms:
FreeBSD 6.2 / ia64.

The value of WINT_MAX is incorrect on some platforms:
mingw.

The values of INT8_MAX, UINT8_MAX etc. are not usable in
preprocessor expressions on some platforms:
HP-UX 11.23.

The macros WCHAR_MIN and WCHAR_MAX are not defined in
<stdint.h> (only in <wchar.h>) on some platforms:
Dragonfly, BSDI.

On some hosts that predate C++11, when using C++ one must define
__STDC_CONSTANT_MACROS to make visible the definitions of
constant macros such as INTMAX_C, and one must define
__STDC_LIMIT_MACROS to make visible the definitions of limit
macros such as INTMAX_MAX.

Portability problems not fixed by Gnulib:

{uint,int}_fast{8,16,32,64}_t may not correspond to the fastest
types available on the system.
Other <stdint.h> substitutes may define these types differently,
so public header files should avoid these types.

Macros are used instead of typedefs.

Some C preprocessors mishandle constants that do not fit in long int.
For example, as of 2007, Sun C mishandles #if LLONG_MIN < 0 on
a platform with 32-bit long int and 64-bit long long int.
Some older preprocessors mishandle constants ending in LL.
To work around these problems, compute the value of expressions like
LONG_MAX < LLONG_MAX at configure-time rather than at
#if-time.

The stdint.h module uses #include_next. If you wish to install
the generated stdint.h file under another name, typically in order to
be able to use some of the types defined by stdint.h in your public
header file, you could use the following Makefile.am-snippet:

You cannot assume that _Noreturn is a reserved word;
it might be a macro.

On MSVC 9, noreturn expands to the empty token sequence, to avoid
problems with standard headers that use __declspec (noreturn)
directly. Although the resulting code operates correctly, the
compiler is not informed whether noreturn functions do not
return, so it may generate incorrect warnings at compile-time, or code
that is slightly less optimized. This problem does not occur with
_Noreturn.

Circa 2012 bleeding-edge GCC with -Werror=old-style-declaration
requires _Noreturn or noreturn before the returned type
in a declaration, and therefore rejects valid but unusually-worded
declarations such as void _Noreturn foo (void);.

This header file does not define the type struct iovec on some platforms:
OpenBSD 4.4.

This header file is lacking the SHUT_RD, SHUT_WR,
SHUT_RDWR macros on some platforms, despite having the shutdown
functions:
emx+gcc.

The struct sockaddr_storage type does not have a member ss_family
on some platforms:
AIX 7.1.

Portability problems not fixed by Gnulib:

This header file does not declare the msg_control and
msg_controllen members of struct msghdr on some
platforms. This can be detected by the absence of the
CMSG_FIRSTHDR macro:
gnulib replacement header, old BSD

Some platforms define macros, such as S_ISDOOR, that are not defined
on other platforms.

The functions lstat and mkdir are not declared on some platforms:
mingw, MSVC 9.

The macros UTIME_NOW and UTIME_OMIT are missing on some
platforms.

On some platforms, struct stat does not include st_atim,
st_mtim, or st_ctim members. Use the gnulib module
‘stat-time’ for accessors to portably get at subsecond resolution.

Portability problems not fixed by Gnulib:

The macro S_IFBLK is missing on some platforms:
MSVC 9.

On Windows platforms (excluding Cygwin), st_ino is always 0.

On OpenVMS, st_ino is an array of three ino_t values,
not a single value.

To partially work around the previous two problems, you can test for
nonzero st_ino and use the Gnulib same-inode module to
compare nonzero values. For example, (a.st_ino && SAME_INODE
(a, b)) is true if the struct stat values a and
b are known to represent the same file, (a.st_ino &&
!SAME_INODE (a, b)) is true if they are known to represent different
files, and !a.st_ino is true if it is not known whether they
represent different files.

On some platforms, two different files may have the same st_dev
and st_ino values, even when st_ino is nonzero:

GNU/Linux NFS servers that export all local file systems as a single
NFS file system, if a local st_dev exceeds 255, or if a local
st_ino exceeds 16777215.

‘struct timeval’ is defined with a tv_sec type that is
narrower than time_t
on some native Windows platforms:
mingw64 in 64-bit mode,
mingw64 in 32-bit mode when __MINGW_USE_VC2005_COMPAT is defined,
MSVC 9 in 64-bit mode,
MSVC 9 in 32-bit mode when _USE_32BIT_TIME_T is not defined.

Portability problems not fixed by Gnulib:

‘struct timeval’ is defined with a tv_sec type that is
wider than time_t:
OpenBSD 5.1 in 64-bit mode.

8.85 wchar.h

This header file cannot be included on some platforms:
Linux uClibc built without wide character support.

This header file is not self-contained on some platforms:
OSF/1 with Desktop Toolkit C, BSD/OS 4.0.1.

The type wint_t and macro WEOF are missing on some platforms:
IRIX 5.3.

The type wint_t is incorrect on some platforms:
MSVC 9.

Some platforms provide a NULL macro that cannot be used in arbitrary
expressions:
NetBSD 5.0

Portability problems not fixed by Gnulib:

This header file leads to link errors and endless recursions or endless loops
on some platforms:
glibc version 2.5 or older, together with gcc version 4.3 or newer and the
option ‘-std=c99’ or ‘-std=gnu99’.

9 ISO C and POSIX Function Substitutes

This chapter describes which functions and function-like macros specified by
ISO C or POSIX are substituted by Gnulib, which portability pitfalls are
fixed by Gnulib, and which (known) portability problems are not worked around
by Gnulib.

The notation “Gnulib module: —” means that Gnulib does not provide a
module providing a substitute for the function. When the list
“Portability problems not fixed by Gnulib” is empty, such a module is
not needed: No portability problems are known. Otherwise, it indicates
that such a module would be useful but is not available: No one so far
found this function important enough to contribute a substitute for it.
If you need this particular function, you may write to
<bug-gnulib at gnu dot org>.

9.7 _longjmp

This function is missing on some platforms:
Solaris 2.5.1, mingw, MSVC 9.

Note: A future revision of POSIX later than the 2008/2009 one may drop the
functions _setjmp and _longjmp. Still, in 2008, on all
systems which have _setjmp, it is the fastest way to save the
registers but not the signal mask (up to 30 times faster than setjmp
on some systems).

Note: A future revision of POSIX later than the 2008/2009 one may drop the
functions _setjmp and _longjmp. Still, in 2008, on all
systems which have _setjmp, it is the fastest way to save the
registers but not the signal mask (up to 30 times faster than setjmp
on some systems).

9.14 accept

On Windows platforms (excluding Cygwin), the descriptors returned by
the accept function cannot be used in calls to read,
write, and close; you have to use recv, send,
closesocket in these cases instead.

On Windows platforms (excluding Cygwin), error codes for accept
are not placed in errno, and WSAGetLastError must be
used instead.

Portability problems not fixed by Gnulib:

On BeOS, the descriptors returned by the accept function cannot be used
in calls to read, write, and close; you have to use
recv, send, closesocket in these cases instead.

Some platforms don’t have a socklen_t type; in this case this function’s
third argument type is ‘int *’.

On some platforms, this function’s third argument type is ‘void *’,
not ‘socklen_t *’:
Solaris 10.

9.15 access

This function uses the effective id instead of the real id on some
platforms:
Cygwin 1.5.x.

Other problems of this function:

There is an inherent race between calling this function and performing
some action based on the results; you should think twice before trusting
this function, especially in a set-uid or set-gid program.

This function does not have an option for not following symbolic links
(like stat versus lstat). If you need this option, use
the Gnulib module faccessat with the AT_EACCESS flag.

9.168 ctime

This function may overflow its internal buffer if an invalid year is passed.

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.

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

9.169 ctime_r

This function has an incompatible declaration on some platforms:
Solaris 11 2011-11 (when _POSIX_PTHREAD_SEMANTICS is not defined).

Portability problems not fixed by Gnulib:

This function is missing on some platforms:
mingw, MSVC 9.

This function may put more than 26 bytes into the argument buffer if an
invalid year is passed.

ctime_r takes a pre-allocated buffer and length of the buffer,
and returns 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 returns 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.

9.210 execl

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.211 execle

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.212 execlp

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.213 execv

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.214 execve

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.215 execvp

On some platforms, a script without executable permission is still run:
Cygwin 1.5.x.

On Windows platforms (excluding Cygwin), this function operates by spawning
and then by exiting the current process, which means the current
process’s parent may incorrectly proceed as if its child had exited.

9.229 faccessat

This function is missing on some platforms:
glibc 2.3.6, Mac OS X 10.5, FreeBSD 6.0, NetBSD 5.0, OpenBSD 3.8, Minix 3.1.8,
AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, MSVC 9,
Interix 3.5, BeOS.
However, the replacement does not always take into account ACLs. Also,
it is not safe to be used in libraries and is not multithread-safe.

Portability problems not fixed by Gnulib:

Other problems of this function:

There is an inherent race between calling this function and performing
some action based on the results; you should think twice before trusting
this function, especially in a set-uid or set-gid program.

Some platforms do not allow changing the access bits on symbolic
links. POSIX states that fchmodat(…,AT_SYMLINK_NOFOLLOW)
may fail with EOPNOTSUPP when called on a symlink, but some
platforms, as well as the gnulib replacement, fail for any use of
AT_SYMLINK_NOFOLLOW even if the target was not a symlink:
glibc, Cygwin.

When reading from a non-blocking pipe whose buffer is empty, this function
fails with errno being set to EINVAL instead of EAGAIN on
some platforms:
mingw, MSVC 9.

Portability problems not fixed by Gnulib:

C99 and POSIX.1-2001 and later require end-of-file to be sticky, that
is, they require this function to act as if it reads end-of-file if
feof would return nonzero. However, on some systems this
function attempts to read from the underlying file descriptor even if
the stream’s end-of-file indicator is set. These systems include
glibc and default Solaris.

On Windows platforms (excluding Cygwin), this function does not set errno
upon failure.

This function crashes if the stream’s file descriptor has already been
closed, if MSVC_INVALID_PARAMETER_HANDLING is
HAIRY_LIBRARY_HANDLING or SANE_LIBRARY_HANDLING,
on some platforms:
MSVC 9.

When reading from a non-blocking pipe whose buffer is empty, this function
fails with errno being set to EINVAL instead of EAGAIN on
some platforms:
mingw, MSVC 9.

Portability problems not fixed by Gnulib:

C99 and POSIX.1-2001 and later require end-of-file to be sticky, that
is, they require this function to act as if it reads end-of-file if
feof would return nonzero. However, on some systems this
function attempts to read from the underlying file descriptor even if
the stream’s end-of-file indicator is set. These systems include
glibc and default Solaris.

On Windows platforms (excluding Cygwin), this function does not set errno
upon failure.

9.286 fopen

This function does not fail when the file name argument ends in a slash
and (without the slash) names a nonexistent file or a file that is not a
directory, on some platforms:
HP-UX 11.00, AIX 7.1, Solaris 9, Irix 5.3.

On platforms where off_t is a 32-bit type, fopen may not work
correctly with files larger than 2 GB. (Cf. AC_SYS_LARGEFILE.)

On Windows platforms (excluding Cygwin), this function does usually not
recognize the /dev/null filename.

Portability problems not fixed by Gnulib:

On Windows platforms (excluding Cygwin), this function does not set errno
upon failure.

On Windows, this function returns a file stream in “text” mode by default;
this means that it translates '\n' to CR/LF by default. Use the
"b" flag if you need reliable binary I/O.

On Windows platforms (excluding Cygwin), this function fails to open
directories for reading. Such streams have implementation-defined
semantics on other platforms. To avoid directory streams with a
consistent error message, use fstat after open and
fdopen, rather than fopen and fileno.

On some platforms, fork followed by a call of the exec family
(execl, execlp, execle, execv, execvp,
or execve) is less efficient than vfork followed by the same
call. vfork is a variant of fork that has been introduced to
optimize the fork/exec pattern.

On Windows platforms (excluding Cygwin), this function is not implemented; use
spawnvp instead.