\input texinfo @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.44 2007-09-09 13:20:45 haible Exp $
@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
which is a library of common routines intended to be shared at the
source level.
-Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 Free Software
-Foundation, Inc.
+Copyright @copyright{} 2004-2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@menu
* Introduction::
* Invoking gnulib-tool::
+* Writing modules::
+* Extending Gnulib::
* Miscellaneous Notes::
* POSIX Substitutes Library:: Building as a separate substitutes library.
* Header File Substitutes:: Overriding system headers.
@include gnulib-tool.texi
-@node Miscellaneous Notes
-@chapter Miscellaneous Notes
+@node Writing modules
+@chapter Writing modules
+
+This chapter explains how to write modules of your own, either to
+extend Gnulib for your own package (@pxref{Extending Gnulib}), or for
+inclusion in gnulib proper.
+
+The guidelines in this chapter do not necessarily need to be followed for
+using @code{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.
@menu
-* Comments::
+* Source code files::
* Header files::
-* Out of memory handling::
-* Library version handling::
-* Windows sockets::
-* Libtool and Windows::
-* License Texinfo sources::
-* Build robot for gnulib::
+* Implementation files::
+* Specification::
+* Module description::
+* Autoconf macros::
+* Unit test modules::
+* Incompatible changes::
@end menu
-@node Comments
-@section Comments
+@node Source code files
+@section Source code files
-@cindex comments describing functions
-@cindex describing functions, locating
-Where to put comments describing functions: Because of risk of
-divergence, we prefer to keep most function describing comments in
-only one place: just above the actual function definition. Some
-people prefer to put that documentation in the .h file. In any case,
-it should appear in just one place unless you can ensure that the
-multiple copies will always remain identical.
+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).
@node Header files
@section 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.
+
@cindex double inclusion of header files
@cindex header file include protection
It is a tradition to use CPP tricks to avoid parsing the same header
is recommended to place the @code{#include} before the @code{extern
"C"} block.
+@node Implementation files
+@section Implementation files
+
+The .c file or files implement the functions and variables declared in the
+.h file.
+
@subheading Include ordering
-When writing a gnulib module, or even in general, a good way to order
-the @samp{#include} directives is the following.
+Every implementation file must start with @samp{#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 @code{_GNU_SOURCE}, would have no effect if defined after a system
+header file has already been included.
+
+Then comes the @samp{#include "..."} specifying the header file that is
+being implemented. Putting this right after @samp{#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:
@itemize
-@item First comes the #include "..." specifying the module being implemented.
-@item Then come all the #include <...> of system or system-replacement headers,
+@item
+First comes #include <config.h>.
+@item
+Second comes the #include "..." specifying the module being implemented.
+@item
+Then come all the #include <...> of system or system-replacement headers,
in arbitrary order.
-@item Then come all the #include "..." of gnulib and private headers, in
+@item
+Then come all the #include "..." of gnulib and application headers, in
arbitrary order.
@end itemize
+@node Specification
+@section Specification
+
+The specification of a function should answer at least the following
+questions:
+@itemize
+@item
+What is the purpose of the function?
+@item
+What are the arguments?
+@item
+What is the return value?
+@item
+What happens in case of failure? (Exit? A specific return value? Errno set?)
+@item
+Memory allocation policy: If pointers to memory are returned, are they freshly
+allocated and supposed to be freed by the caller?
+@end itemize
+
+@cindex specification
+@cindex comments describing functions
+@cindex describing functions, locating
+Where to put the specification describing exported functions? Three practices
+are used in gnulib:
+
+@itemize
+@item
+The specification can be as comments in the header file, just above the
+function declaration.
+@item
+The specification can be as comments in the implementation file, just above
+the function definition.
+@item
+The specification can be in texinfo format, so that it gets included in the
+gnulib manual.
+@end itemize
+
+In any case, the specification should appear in just one place, unless you can
+ensure that the multiple copies will always remain identical.
+
+The advantage of putting it in the header file is that the user only has to
+read the include file normally never needs to peek into the implementation
+file(s).
+
+The advantage of putting it in the implementation file is that when reviewing
+or changing the implementation, you have both elements side by side.
+
+The advantage of texinfo formatted documentation is that it is easily
+published in HTML or Info format.
+
+Currently (as of 2010), half of gnulib uses the first practice, nearly half
+of gnulib uses the second practice, and a small minority uses the texinfo
+practice.
+
+
+@node Module description
+@section Module description
+
+For the module description, you can start from an existing module's
+description, or from a blank one: @file{module/TEMPLATE} for a normal module,
+or @file{module/TEMPLATE-TESTS} for a unit test module. Some more fields
+are possible but rarely used. Use @file{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.
+
+@table @asis
+@item 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
+@samp{frob}, the description can be @samp{frob() function: frobnication.}
+Gnulib's documentation generator will automatically convert the first part
+to a hyperlink when it has this form.
+
+@item Status
+This field is either empty/absent, or contains the word @samp{obsolete}. In
+the latter case, @command{gnulib-tool} will, unless the option
+@code{--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 @samp{Notice} section (see below) text like
+@samp{This module is obsolete.}
+
+@item Notice
+This field contains text that @command{gnulib-tool} will show to the user
+when the module is used. This can be a status indicator like
+@samp{This module is obsolete.} or additional advice. Do not abuse this
+field.
+
+@item Applicability
+This field is either empty/absent, or contains the word @samp{all}. It
+describes to which @code{Makefile.am} the module is applied. By default,
+a normal module is applied to @code{@var{source_base}/Makefile.am}
+(normally @code{lib/Makefile.am}), whereas a module ending in @code{-tests}
+is applied to @code{@var{tests_base}/Makefile.am} (normally
+@code{tests/Makefile.am}). If this field is @samp{all}, it is applied to
+both @code{Makefile.am}s. This is useful for modules which provide
+Makefile.am macros rather than compiled source code.
+
+@item Files
+This field contains a newline separated list of the files that are part of
+the module. @code{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.
+
+@item Depends-on
+This field contains a newline separated list of the modules that are required
+for the proper working of this module. @code{gnulib-tool} includes each
+required module automatically, unless it is specified with option
+@code{--avoid} or it is marked as obsolete and the option
+@code{--with-obsolete} is not given.
+
+A test modules @code{foo-tests} implicity depends on the corresponding non-test
+module @code{foo}. @code{foo} implicitly depends on @code{foo-tests} if the
+latter exists and if the option @code{--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.)
+
+@item configure.ac-early
+This field contains @file{configure.ac} stuff (Autoconf macro invocations and
+shell statements) that are logically placed early in the @file{configure.ac}
+file: right after the @code{AC_PROG_CC} invocation. This section is adequate
+for statements that modify @code{CPPFLAGS}, as these can affect the results of
+other Autoconf macros.
+
+@item configure.ac
+This field contains @file{configure.ac} stuff (Autoconf macro invocations and
+shell statements).
+
+It is forbidden to add items to the @code{CPPFLAGS} variable here, other than
+temporarily, as these could affect the results of other Autoconf macros.
+
+We avoid adding items to the @code{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 @code{.m4} file of their own.
+
+@item Makefile.am
+This field contains @code{Makefile.am} statements. Variables like
+@code{lib_SOURCES} are transformed to match the name of the library
+being built in that directory. For example, @code{lib_SOURCES} may become
+@code{libgnu_a_SOURCES} (for a plain library) or @code{libgnu_la_SOURCES}
+(for a libtool library). Therefore, the normal way of having an
+implementation file @code{lib/foo.c} compiled unconditionally is to write
+@smallexample
+lib_SOURCES += foo.c
+@end smallexample
+
+@item 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:
+@smallexample
+"foo.h"
+@end smallexample
+
+@item 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 @command{gnulib-tool} can remove duplicates
+when presenting a summary to the user.
+Example:
+@smallexample
+$(POW_LIBM)
+$(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise
+@end smallexample
+
+@item License
+This field specifies the license that governs the source code parts of
+this module. See @ref{Copyright} for details.
+
+@item Maintainer
+This field specifies the persons who have a definitive say about proposed
+changes to this module. You don't need to mention email addresses here:
+they can be inferred from the @code{ChangeLog} file.
+
+Please put at least one person here. We don't like unmaintained modules.
+@end table
+
+
+@node Autoconf macros
+@section Autoconf macros
+
+For a module @code{foo}, an Autoconf macro file @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
+@code{gl_FOO}. For modules outside Gnulib that are not likely to be moved
+into Gnulib, please use a prefix specific to your package: @code{gt_} for
+GNU gettext, @code{cu_} for GNU coreutils, etc.
+
+For modules that define a function @code{foo}, the entry point is called
+@code{gl_FUNC_FOO} instead of @code{gl_FOO}. For modules that provide a
+header file with multiple functions, say @code{foo.h}, the entry point is
+called @code{gl_FOO_H} or @code{gl_HEADER_FOO_H}. This convention is useful
+because sometimes a header and a function name coincide (for example,
+@code{fcntl} and @code{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 @code{AC_LIBOBJ} (this is the
+entry point, say @code{gl_FUNC_FOO}), and one that arranges for the macros
+needed by the replacement code @code{lib/foo.c} (typically called
+@code{gl_PREREQ_FOO}). The reason of this separation is
+@enumerate
+@item
+to make it easy to update the Autoconf macros when you have modified the
+source code file: after changing @code{lib/foo.c}, all you have to review
+is the @code{Depends-on} section of the module description and the
+@code{gl_PREREQ_FOO} macro in the Autoconf macro file.
+@item
+The Autoconf macros are often large enough that splitting them eases
+maintenance.
+@end enumerate
+
+
+@node Unit test modules
+@section Unit test modules
+
+A unit test that is a simple C program usually has a module description as
+simple as this:
+
+@smallexample
+Files:
+tests/test-foo.c
+tests/macros.h
+
+Depends-on:
+
+configure.ac:
+
+Makefile.am:
+TESTS += test-foo
+check_PROGRAMS += test-foo
+@end smallexample
+
+The test program @file{tests/test-foo.c} often has the following structure:
+
+@itemize
+@item
+First comes the obligatory @samp{#include <config.h>}.
+
+@item
+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.
+
+@item
+Then come other includes. In particular, the file @file{macros.h} is often
+used here. It contains a convenient @code{ASSERT} macro.
+@end itemize
+
+The body of the test, then, contains many @code{ASSERT} invocations. When
+a test fails, the @code{ASSERT} macro prints the line number of the failing
+statement, thus giving you as a developer a idea 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:
+
+@smallexample
+Files:
+tests/test-foo.sh
+tests/test-foo.c
+tests/macros.h
+
+Depends-on:
+
+configure.ac:
+
+Makefile.am:
+TESTS += test-foo.sh
+TESTS_ENVIRONMENT += FOO_BAR='@@FOO_BAR@@'
+check_PROGRAMS += test-foo
+@end smallexample
+
+Here, the @code{TESTS_ENVIRONMENT} variable can be used to pass values
+determined by @code{configure} or by the @code{Makefile} to the shell
+script, as environment variables. The values of @code{EXEEXT} and of
+@code{srcdir}, from Autoconf and Automake, are already provided as
+environment variables, through an initial value of @code{TESTS_ENVIRONMENT}
+that @code{gnulib-tool} puts in place.
+
+Regardless of the specific form of the unit test, the following guidelines
+should be respected:
+
+@itemize
+@item
+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.)
+@item
+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 @code{ASSERT} macro already does so.
+@item
+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:
+@smallexample
+ fputs ("Skipping test: multithreading not enabled\n", stderr);
+ return 77;
+@end smallexample
+Such a message helps detecting bugs in the autoconf macros: A simple message
+@samp{SKIP: test-foo} does not sufficiently catch the attention of the user.
+@end itemize
+
+
+@node Incompatible changes
+@section Incompatible changes
+
+Incompatible changes to Gnulib modules should be mentioned in Gnulib's
+@file{NEWS} file. Incompatible changes here mean that existing source code
+may not compile or work any more.
+
+We don't mean changes in the binary interface (ABI), since
+@enumerate
+@item
+Gnulib code is used in source-code form.
+@item
+The user who distributes libraries that contain Gnulib code is supposed to
+bump the version number in the way described in the Libtool documentation
+before every release.
+@end enumerate
+
+
+@node Extending Gnulib
+@chapter 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
+@command{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, @file{stdint.in.h}, it
+either has to put a comment into @file{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
+@samp{--avoid=stdint} option and provide the modified @code{stdint}
+module in a different directory.
+
+The @option{--local-dir} option to @command{gnulib-tool} solves this
+problem. It allows the package to override or augment Gnulib. This
+means:
+
+@itemize @bullet
+@item
+You can store files that are to override Gnulib files or modules.
+
+@item
+You can store context diffs to be applied to Gnulib files.
+
+@item
+You can add modules of your own, that are not (yet) in Gnulib.
+
+@item
+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 @command{gnulib-tool} option @samp{--makefile-name}.)
+@end itemize
+
+In a release tarball, you can distribute the contents of this
+@option{--local-dir} directory that will be combinable with newer
+versions of Gnulib, barring incompatible changes to Gnulib.
+
+If the @samp{--local-dir=@var{directory}} option is specified, then
+@command{gnulib-tool} looks in @file{@var{directory}} whenever it
+reads a file from the Gnulib directory. Suppose @command{gnulib-tool}
+is looking for @var{file}. Then:
+
+@itemize @bullet
+@item
+If @file{@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses
+it instead of the file included in Gnulib.
+
+@item
+Otherwise, if @file{@var{directory}/@var{file}.diff} exists, then
+@command{gnulib-tool} uses the file from Gnulib after applying the diff
+using the @command{patch} program.
+
+@item
+Otherwise, @command{gnulib-tool} uses the file included in Gnulib.
+@end itemize
+
+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.
+
+
+
+@node Miscellaneous Notes
+@chapter Miscellaneous Notes
+
+@menu
+* Out of memory handling::
+* Obsolete modules::
+* Extra tests modules::
+* A C++ namespace for gnulib:: A different way of using Gnulib in C++
+* Library version handling::
+* Windows sockets::
+* Libtool and Windows::
+* License Texinfo sources::
+* Build robot for gnulib::
+@end menu
+
+
@node Out of memory handling
@section Out of memory handling
fail.
+@node Obsolete modules
+@section Obsolete modules
+
+@cindex 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. @code{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 @code{--with-obsolete} to
+@code{gnulib-tool}, dependencies to obsolete modules will be included,
+however, unless blocked through an @code{--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:
+
+@example
+Status:
+obsolete
+
+Notice:
+This module is obsolete.
+@end example
+
+
+@node Extra tests modules
+@section Extra tests modules
+
+@cindex Extra tests modules
+@cindex C++ tests modules
+@cindex tests modules, C++
+@cindex long-running tests modules
+@cindex tests modules, long-running
+@cindex privileged tests modules
+@cindex tests modules, privileged
+@cindex unportable tests modules
+@cindex tests modules, unportable
+Test modules can be marked with some special status attributes. When a
+test module has such an attribute, @code{gnulib-tool --import} will not
+include it by default.
+
+The supported status attributes are:
+
+@table @code
+@item 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.
+
+@item 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.
+
+@item 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.
+
+@item 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.
+@end table
+
+@code{gnulib-tool --import} will not include tests marked with these
+attributes by default. When @code{gnulib-tool} is invoked with one
+of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests}, it
+will include tests despite the corresponding special status attribute.
+When @code{gnulib-tool} receives the option @code{--with-all-tests},
+it will include all tests regardless of their status attributes.
+
+@code{gnulib-tool --create-testdir} and
+@code{gnulib-tool --create-megatestdir} 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
+@code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests} are
+recognized here as well. Additionally, @code{gnulib-tool} also
+understands the options @code{--without-c++-tests},
+@code{--without-longrunning-tests}, @code{--without-privileged-tests},
+@code{--without-unportable-tests}.
+
+In order to mark a module with a status attribute, you need to add it
+to the module description, like this:
+
+@example
+Status:
+longrunning-test
+@end example
+
+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 @code{foo-tests} and @code{foo-extra-tests}. Then add a dependency
+from @code{foo-tests} to @code{foo-extra-tests}, and mark the
+@code{foo-extra-tests} with the particular status attribute.
+
+
+@node A C++ namespace for gnulib
+@section A C++ namespace for gnulib
+
+The function definitions provided by Gnulib (@code{.c} code) are meant
+to be compiled by a C compiler. The header files (@code{.h} files),
+on the other hand, can be used in either C or C++.
+
+By default, when used in a C++ compilation unit, the @code{.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 @samp{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
+@code{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
+@smallexample
+#define GNULIB_NAMESPACE gnulib
+@end smallexample
+@noindent
+at the beginning of a compilation unit, Gnulib's @code{<fcntl.h>} header
+file will make available the @code{open} function as @code{gnulib::open}.
+The symbol @code{open} will still refer to the system's @code{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 @code{_GL_CXXALIAS_RPL} or
+@code{_GL_CXXALIAS_SYS} macro invocation.
+
+The benefits of this namespace mode are:
+@itemize
+@item
+Gnulib defines fewer symbols as preprocessor macros. For example, on a
+platform where @code{open} has to be overridden, Gnulib normally does
+@code{#define open rpl_open}. If your package has a class with a member
+@code{open}, for example a class @code{foo} with a method @code{foo::open},
+then if you define this member in a compilation unit that includes
+@code{<fcntl.h>} and use it in a compilation unit that does not include
+@code{<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 @code{open}
+function works fine. This problem goes away in namespace mode.
+
+@item
+It provides a safety check whether the set of modules your package requests
+from Gnulib is sufficient. For example, if you use the function
+@code{gnulib::open} in your code, and you forgot to request the module
+@samp{open} from Gnulib, you will get a compilation error (regardless of
+the platform).
+@end itemize
+
+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 @code{open (...)} in your code,
+it will invoke the possibly buggy system function, even if you have
+requested the module @samp{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.
+
+
@node Library version handling
@section Library version handling
* fabs::
* fabsf::
* fabsl::
+* faccessat::
* fattach::
* fchdir::
* fchmod::
+* fchmodat::
* fchown::
+* fchownat::
* fclose::
* fcntl::
* fdatasync::
* fdimf::
* fdiml::
* fdopen::
+* fdopendir::
* feclearexcept::
* fegetenv::
* fegetexceptflag::
* fseeko::
* fsetpos::
* fstat::
+* fstatat::
* fstatvfs::
* fsync::
* ftell::
* ftrylockfile::
* ftw::
* funlockfile::
+* futimens::
* fwide::
* fwprintf::
* fwrite::
* lgammaf::
* lgammal::
* link::
+* linkat::
* lio_listio::
* listen::
* llabs::
* memmove::
* memset::
* mkdir::
+* mkdirat::
* mkdtemp::
* mkfifo::
+* mkfifoat::
* mknod::
+* mknodat::
* mkstemp::
* mktime::
* mlock::
* ntohl::
* ntohs::
* open::
+* openat::
* opendir::
* openlog::
* open_memstream::
+* open_wmemstream::
* optarg::
* opterr::
* optind::
* pread::
* printf::
* pselect::
+* psiginfo::
* psignal::
* pthread_atfork::
* pthread_attr_destroy::
* pthread_key_create::
* pthread_key_delete::
* pthread_kill::
+* pthread_mutex_consistent::
* pthread_mutex_destroy::
* pthread_mutex_getprioceiling::
* pthread_mutex_init::
* pthread_mutexattr_getprioceiling::
* pthread_mutexattr_getprotocol::
* pthread_mutexattr_getpshared::
+* pthread_mutexattr_getrobust::
* pthread_mutexattr_gettype::
* pthread_mutexattr_init::
* pthread_mutexattr_setprioceiling::
* pthread_mutexattr_setprotocol::
* pthread_mutexattr_setpshared::
+* pthread_mutexattr_setrobust::
* pthread_mutexattr_settype::
* pthread_once::
* pthread_rwlock_destroy::
* readdir::
* readdir_r::
* readlink::
+* readlinkat::
* readv::
* realloc::
* realpath::
* remquof::
* remquol::
* rename::
+* renameat::
* rewind::
* rewinddir::
* rint::
* strcspn::
* strdup::
* strerror::
+* strerror_l::
* strerror_r::
* strfmon::
* strfmon_l::
* swprintf::
* swscanf::
* symlink::
+* symlinkat::
* sync::
* sysconf::
* syslog::
* ungetc::
* ungetwc::
* unlink::
+* unlinkat::
* unlockpt::
* unsetenv::
* uselocale::
* utime::
+* utimensat::
* utimes::
* va_arg::
* va_copy::
@include posix-functions/fabs.texi
@include posix-functions/fabsf.texi
@include posix-functions/fabsl.texi
+@include posix-functions/faccessat.texi
@include posix-functions/fattach.texi
@include posix-functions/fchdir.texi
@include posix-functions/fchmod.texi
+@include posix-functions/fchmodat.texi
@include posix-functions/fchown.texi
+@include posix-functions/fchownat.texi
@include posix-functions/fclose.texi
@include posix-functions/fcntl.texi
@include posix-functions/fdatasync.texi
@include posix-functions/fdimf.texi
@include posix-functions/fdiml.texi
@include posix-functions/fdopen.texi
+@include posix-functions/fdopendir.texi
@include posix-functions/feclearexcept.texi
@include posix-functions/fegetenv.texi
@include posix-functions/fegetexceptflag.texi
@include posix-functions/fseeko.texi
@include posix-functions/fsetpos.texi
@include posix-functions/fstat.texi
+@include posix-functions/fstatat.texi
@include posix-functions/fstatvfs.texi
@include posix-functions/fsync.texi
@include posix-functions/ftell.texi
@include posix-functions/ftrylockfile.texi
@include posix-functions/ftw.texi
@include posix-functions/funlockfile.texi
+@include posix-functions/futimens.texi
@include posix-functions/fwide.texi
@include posix-functions/fwprintf.texi
@include posix-functions/fwrite.texi
@include posix-functions/lgammaf.texi
@include posix-functions/lgammal.texi
@include posix-functions/link.texi
+@include posix-functions/linkat.texi
@include posix-functions/lio_listio.texi
@include posix-functions/listen.texi
@include posix-functions/llabs.texi
@include posix-functions/memmove.texi
@include posix-functions/memset.texi
@include posix-functions/mkdir.texi
+@include posix-functions/mkdirat.texi
@include posix-functions/mkdtemp.texi
@include posix-functions/mkfifo.texi
+@include posix-functions/mkfifoat.texi
@include posix-functions/mknod.texi
+@include posix-functions/mknodat.texi
@include posix-functions/mkstemp.texi
@include posix-functions/mktime.texi
@include posix-functions/mlock.texi
@include posix-functions/ntohl.texi
@include posix-functions/ntohs.texi
@include posix-functions/open.texi
+@include posix-functions/openat.texi
@include posix-functions/opendir.texi
@include posix-functions/openlog.texi
@include posix-functions/open_memstream.texi
+@include posix-functions/open_wmemstream.texi
@include posix-functions/optarg.texi
@include posix-functions/opterr.texi
@include posix-functions/optind.texi
@include posix-functions/pread.texi
@include posix-functions/printf.texi
@include posix-functions/pselect.texi
+@include posix-functions/psiginfo.texi
@include posix-functions/psignal.texi
@include posix-functions/pthread_atfork.texi
@include posix-functions/pthread_attr_destroy.texi
@include posix-functions/pthread_key_create.texi
@include posix-functions/pthread_key_delete.texi
@include posix-functions/pthread_kill.texi
+@include posix-functions/pthread_mutex_consistent.texi
@include posix-functions/pthread_mutex_destroy.texi
@include posix-functions/pthread_mutex_getprioceiling.texi
@include posix-functions/pthread_mutex_init.texi
@include posix-functions/pthread_mutexattr_getprioceiling.texi
@include posix-functions/pthread_mutexattr_getprotocol.texi
@include posix-functions/pthread_mutexattr_getpshared.texi
+@include posix-functions/pthread_mutexattr_getrobust.texi
@include posix-functions/pthread_mutexattr_gettype.texi
@include posix-functions/pthread_mutexattr_init.texi
@include posix-functions/pthread_mutexattr_setprioceiling.texi
@include posix-functions/pthread_mutexattr_setprotocol.texi
@include posix-functions/pthread_mutexattr_setpshared.texi
+@include posix-functions/pthread_mutexattr_setrobust.texi
@include posix-functions/pthread_mutexattr_settype.texi
@include posix-functions/pthread_once.texi
@include posix-functions/pthread_rwlock_destroy.texi
@include posix-functions/readdir.texi
@include posix-functions/readdir_r.texi
@include posix-functions/readlink.texi
+@include posix-functions/readlinkat.texi
@include posix-functions/readv.texi
@include posix-functions/realloc.texi
@include posix-functions/realpath.texi
@include posix-functions/remquof.texi
@include posix-functions/remquol.texi
@include posix-functions/rename.texi
+@include posix-functions/renameat.texi
@include posix-functions/rewind.texi
@include posix-functions/rewinddir.texi
@include posix-functions/rint.texi
@include posix-functions/strcspn.texi
@include posix-functions/strdup.texi
@include posix-functions/strerror.texi
+@include posix-functions/strerror_l.texi
@include posix-functions/strerror_r.texi
@include posix-functions/strfmon.texi
@include posix-functions/strfmon_l.texi
@include posix-functions/swprintf.texi
@include posix-functions/swscanf.texi
@include posix-functions/symlink.texi
+@include posix-functions/symlinkat.texi
@include posix-functions/sync.texi
@include posix-functions/sysconf.texi
@include posix-functions/syslog.texi
@include posix-functions/ungetc.texi
@include posix-functions/ungetwc.texi
@include posix-functions/unlink.texi
+@include posix-functions/unlinkat.texi
@include posix-functions/unlockpt.texi
@include posix-functions/unsetenv.texi
@include posix-functions/uselocale.texi
@include posix-functions/utime.texi
+@include posix-functions/utimensat.texi
@include posix-functions/utimes.texi
@include posix-functions/va_arg.texi
@include posix-functions/va_copy.texi
* Glibc obstack.h::
* Glibc printf.h::
* Glibc pthread.h::
+* Glibc pty.h::
* Glibc pwd.h::
* Glibc regex.h::
* Glibc regexp.h::
* Glibc rpcsvc/ypupd.h::
* Glibc sched.h::
* Glibc search.h::
+* Glibc selinux/selinux.h::
* Glibc shadow.h::
* Glibc signal.h::
* Glibc stdio.h::
@section Glibc Extensions to @code{<fcntl.h>}
@menu
+* fallocate::
* readahead::
@end menu
+@include glibc-functions/fallocate.texi
@include glibc-functions/readahead.texi
@node Glibc fenv.h
@include glibc-functions/pthread_rwlockattr_setkind_np.texi
@include glibc-functions/pthread_yield.texi
-@c @node Glibc pty.h
-@c @section Glibc @code{<pty.h>}
+@node Glibc pty.h
+@section Glibc @code{<pty.h>}
+
+@menu
+* forkpty::
+* openpty::
+@end menu
+
+@include glibc-functions/forkpty.texi
+@include glibc-functions/openpty.texi
@node Glibc pwd.h
@section Glibc Extensions to @code{<pwd.h>}
@include glibc-functions/hsearch_r.texi
@include glibc-functions/tdestroy.texi
+@node Glibc selinux/selinux.h
+@section Glibc Extensions to @code{<selinux/selinux.h>}
+
+@menu
+* fgetfilecon::
+* getfilecon::
+* lgetfilecon::
+@end menu
+
+@include glibc-functions/getfilecon-desc.texi
+@include glibc-functions/fgetfilecon.texi
+@include glibc-functions/getfilecon.texi
+@include glibc-functions/lgetfilecon.texi
+
@c @node Glibc semaphore.h
@c @section Glibc Extensions to @code{<semaphore.h>}
* jrand48_r::
* lcong48_r::
* lrand48_r::
+* mkostemp::
+* mkostemps::
* mrand48_r::
+* mkstemps::
* nrand48_r::
* on_exit::
* ptsname_r::
@include glibc-functions/jrand48_r.texi
@include glibc-functions/lcong48_r.texi
@include glibc-functions/lrand48_r.texi
+@include glibc-functions/mkostemp.texi
+@include glibc-functions/mkostemps.texi
@include glibc-functions/mrand48_r.texi
+@include glibc-functions/mkstemps.texi
@include glibc-functions/nrand48_r.texi
@include glibc-functions/on_exit.texi
@include glibc-functions/ptsname_r.texi
@section Glibc Extensions to @code{<sys/socket.h>}
@menu
+* accept4::
* isfdtype::
@end menu
+@include glibc-functions/accept4.texi
@include glibc-functions/isfdtype.texi
@node Glibc sys/stat.h
@menu
* adjtime::
* futimes::
+* futimesat::
* lutimes::
* settimeofday::
@end menu
@include glibc-functions/adjtime.texi
@include glibc-functions/futimes.texi
+@include glibc-functions/futimesat.texi
@include glibc-functions/lutimes.texi
@include glibc-functions/settimeofday.texi
* brk::
* chroot::
* daemon::
+* dup3::
* endusershell::
* euidaccess::
+* execvpe::
* get_current_dir_name::
* getdomainname::
* getdtablesize::
* getresuid::
* getusershell::
* group_member::
+* pipe2::
* profil::
* revoke::
* sbrk::
@include glibc-functions/brk.texi
@include glibc-functions/chroot.texi
@include glibc-functions/daemon.texi
+@include glibc-functions/dup3.texi
@include glibc-functions/endusershell.texi
@include glibc-functions/euidaccess.texi
+@include glibc-functions/execvpe.texi
@include glibc-functions/get_current_dir_name.texi
@include glibc-functions/getdomainname.texi
@include glibc-functions/getdtablesize.texi
@include glibc-functions/getresuid.texi
@include glibc-functions/getusershell.texi
@include glibc-functions/group_member.texi
+@include glibc-functions/pipe2.texi
@include glibc-functions/profil.texi
@include glibc-functions/revoke.texi
@include glibc-functions/sbrk.texi
* setutent::
* updwtmp::
* utmpname::
+* login_tty::
@end menu
@include glibc-functions/endutent.texi
@include glibc-functions/setutent.texi
@include glibc-functions/updwtmp.texi
@include glibc-functions/utmpname.texi
+@include glibc-functions/login_tty.texi
@node Glibc utmpx.h
@section Glibc Extensions to @code{<utmpx.h>}
@menu
* alloca::
* alloca-opt::
+* Safe Allocation Macros::
* String Functions in C Locale::
* Quoting::
* error and progname::
* gcd::
* Regular expressions::
+* Searching for Libraries::
+* Exported Symbols of Shared Libraries::
+* LD Version Scripts::
+* Visual Studio Compatibility::
* Supporting Relocation::
* func::
* warnings::
* manywarnings::
+* Running self-tests under valgrind::
@end menu
@node alloca
@findex alloca
@include alloca-opt.texi
+@include safe-alloc.texi
+
@node String Functions in C Locale
@section Character and String Functions in C Locale
@include c-strtold.texi
@include quote.texi
+
@include error.texi
+
@include gcd.texi
-@include relocatable-maint.texi
@node Regular expressions
@section Regular expressions
@include regexprops-generic.texi
+@include havelib.texi
+
+@include lib-symbol-visibility.texi
+
+@include ld-version-script.texi
+
+@include ld-output-def.texi
+
+@include relocatable-maint.texi
+
@include func.texi
@include warnings.texi
@include manywarnings.texi
+@include valgrind-tests.texi
@node GNU Free Documentation License
@appendix GNU Free Documentation License
projects / gnulib.git / blobdiff