@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
+@c Define a new index for the magic constants in regex.texi.
+@defcodeindex cn
@syncodeindex fn cp
+@syncodeindex ky cp
@syncodeindex pg cp
+@syncodeindex tp cp
+@syncodeindex vr cp
+@syncodeindex cn cp
@ifclear texi2html
@firstparagraphindent insert
@end ifclear
which is a library of common routines intended to be shared at the
source level.
-Copyright @copyright{} 2004-2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2013 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
@end ifnottex
@menu
-* Introduction::
+* Brief Overview::
+* Philosophy::
* Invoking gnulib-tool::
+* Writing modules::
+* Extending Gnulib::
* Miscellaneous Notes::
* POSIX Substitutes Library:: Building as a separate substitutes library.
* Header File Substitutes:: Overriding system headers.
* Glibc Header File Substitutes:: Overriding system headers.
* Glibc Function Substitutes:: Replacing system functions.
* Particular Modules:: Documentation of individual modules.
+* Regular expressions:: The regex module.
* GNU Free Documentation License:: Copying and sharing this manual.
* Index::
@end menu
@end macro
-@node Introduction
-@chapter Introduction
+@node Brief Overview
+@chapter Brief Overview
-Gnulib is a source code library. It provides basic functionalities to
-programs and libraries. Currently (as of October 2006) more than 30
-packages make use of Gnulib.
+Gnulib is a source code library that provides basic functionality to
+programs and libraries. Many software packages make use of Gnulib
+to avoid reinventing the portability wheel.
Resources:
@itemize
@item Gnulib is hosted at Savannah:
@url{http://savannah.gnu.org/projects/gnulib}. Get the sources
- through Git or CVS from there.
+ through Git from there.
@item The Gnulib home page:
@url{http://www.gnu.org/software/gnulib/}.
@end itemize
+@include gnulib-readme.texi
+
+@node Philosophy
+@chapter Philosophy
+
+Gnulib's design and development philosophy is organized around steady,
+collaborative, and open development of reusable modules that are
+suitable for a reasonably wide variety of platforms.
+
@menu
* Benefits::
* Library vs Reusable Code::
* Portability and Application Code::
+* Target Platforms::
* Modules::
* Various Kinds of Modules::
* Collaborative Development::
@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::
-* Obsolete modules::
-* 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} implicitly 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.)
+
+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 @code{configure.ac}
+statements. For example:
+@smallexample
+strtoull [test $ac_cv_func_strtoumax = no]
+@end smallexample
+
+Lines starting with @code{#} are recognized as comments and are ignored.
+
+@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, 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:
+
+@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
@cindex Out of Memory handling
@cindex Memory allocation failure
-The GSS API does not have a standard error code for the out of memory
-error condition. Instead of adding a non-standard error code, this
-library has chosen to adopt a different strategy. Out of memory
-handling happens in rare situations, but performing the out of memory
-error handling after almost all API function invocations pollute your
-source code and might make it harder to spot more serious problems.
-The strategy chosen improves code readability and robustness.
+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.
@cindex Aborting execution
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.
-
-@vindex xalloc_fail_func
-However, we realize that some applications may not want to have the
-GSS library abort execution in any situation. The GSS library 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 @code{void} prototype, i.e., no return
-value and no parameters) and set the library variable
-@code{xalloc_fail_func} to that function. The variable should be
+for. This is how the library behaves by default (using
+the @samp{xalloc-die} module).
+
+@vindex xalloc_die
+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 @code{void} prototype, i.e., no return value and no
+parameters) and set the library variable
+@code{xalloc_die} to that function. The variable should be
declared as follows.
@example
-extern void (*xalloc_fail_func) (void);
+extern void (*xalloc_die) (void);
@end example
-The GSS library will invoke this function if an out of memory error
-occurs. Note that after this the GSS library is in an undefined
-state, so you must unload or restart the application to continue call
-GSS library functions. The hook is only intended to allow the
-application to log the situation in a special way. Of course, care
-must be taken to not allocate more memory, as that will likely also
-fail.
+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.
@node Obsolete modules
@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 --with-tests} 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 --with-tests} and
+@code{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
+@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
Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}.
Thus, if you want to assume Windows XP or later, you can add
-AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo
+AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo
implementation.
If you want to support Windows 2000, don't do anything. The
@item Create gnulib directory
On a machine with recent automake, autoconf, m4 installed and with a
-gnulib git or cvs checkout (typically a Linux machine), use
+gnulib git checkout (typically a Linux machine), use
@example
gnulib-tool --create-megatestdir --with-tests --dir=...
@item Build modules
On the build machine, run ./do-autobuild (or "nohup ./do-autobuild").
-It creates a directory 'logs/' with a log file for each module.
+It creates a directory @file{logs/} with a log file for each module.
@item Submit build logs
* setjmp.h::
* signal.h::
* spawn.h::
+* stdalign.h::
* stdarg.h::
* stdbool.h::
* stddef.h::
* stdint.h::
* stdio.h::
* stdlib.h::
+* stdnoreturn.h::
* string.h::
* strings.h::
* stropts.h::
* tgmath.h::
* time.h::
* trace.h::
+* uchar.h::
* ucontext.h::
* ulimit.h::
* unistd.h::
@include posix-headers/setjmp.texi
@include posix-headers/signal.texi
@include posix-headers/spawn.texi
+@include posix-headers/stdalign.texi
@include posix-headers/stdarg.texi
@include posix-headers/stdbool.texi
@include posix-headers/stddef.texi
@include posix-headers/stdint.texi
@include posix-headers/stdio.texi
@include posix-headers/stdlib.texi
+@include posix-headers/stdnoreturn.texi
@include posix-headers/string.texi
@include posix-headers/strings.texi
@include posix-headers/stropts.texi
@include posix-headers/tgmath.texi
@include posix-headers/time.texi
@include posix-headers/trace.texi
+@include posix-headers/uchar.texi
@include posix-headers/ucontext.texi
@include posix-headers/ulimit.texi
@include posix-headers/unistd.texi
* aio_suspend::
* aio_write::
* alarm::
+* aligned_alloc::
* alphasort::
* asctime::
* asctime_r::
* bind::
* bsearch::
* btowc::
+* c16rtomb::
+* c32rtomb::
* cabs::
* cabsf::
* cabsl::
* malloc::
* mblen::
* mbrlen::
+* mbrtoc16::
+* mbrtoc32::
* mbrtowc::
* mbsinit::
* mbsnrtowcs::
* putwchar::
* pwrite::
* qsort::
+* quick_exit::
* raise::
* rand::
* rand_r::
@include posix-functions/aio_suspend.texi
@include posix-functions/aio_write.texi
@include posix-functions/alarm.texi
+@include posix-functions/aligned_alloc.texi
@include posix-functions/alphasort.texi
@include posix-functions/asctime.texi
@include posix-functions/asctime_r.texi
@include posix-functions/bind.texi
@include posix-functions/bsearch.texi
@include posix-functions/btowc.texi
+@include posix-functions/c16rtomb.texi
+@include posix-functions/c32rtomb.texi
@include posix-functions/cabs.texi
@include posix-functions/cabsf.texi
@include posix-functions/cabsl.texi
@include posix-functions/malloc.texi
@include posix-functions/mblen.texi
@include posix-functions/mbrlen.texi
+@include posix-functions/mbrtoc16.texi
+@include posix-functions/mbrtoc32.texi
@include posix-functions/mbrtowc.texi
@include posix-functions/mbsinit.texi
@include posix-functions/mbsnrtowcs.texi
@include posix-functions/putwchar.texi
@include posix-functions/pwrite.texi
@include posix-functions/qsort.texi
+@include posix-functions/quick_exit.texi
@include posix-functions/raise.texi
@include posix-functions/rand.texi
@include posix-functions/rand_r.texi
@chapter Past POSIX Function Substitutes
This chapter describes which functions and function-like macros specified by
-older versions of POSIX (POSIX:2001) are substituted by Gnulib, which
+older versions of POSIX are substituted by Gnulib, which
portability pitfalls are fixed by Gnulib, and which (known) portability
problems are not worked around by Gnulib.
* fstab.h::
* fts.h::
* getopt.h::
+* gshadow.h::
* ieee754.h::
* ifaddrs.h::
* libintl.h::
@include glibc-headers/fstab.texi
@include glibc-headers/fts.texi
@include glibc-headers/getopt.texi
+@include glibc-headers/gshadow.texi
@include glibc-headers/ieee754.texi
@include glibc-headers/ifaddrs.texi
@include glibc-headers/libintl.texi
* Glibc glob.h::
* Glibc gnu/libc-version.h::
* Glibc grp.h::
+* Glibc gshadow.h::
* Glibc ifaddrs.h::
* Glibc libintl.h::
* Glibc link.h::
* Glibc obstack.h::
* Glibc printf.h::
* Glibc pthread.h::
+* Glibc pty.h::
* Glibc pwd.h::
* Glibc regex.h::
* Glibc regexp.h::
* Glibc string.h::
* Glibc sys/capability.h::
* Glibc sys/epoll.h::
+* Glibc sys/fanotify.h::
* Glibc sys/file.h::
* Glibc sys/fsuid.h::
* Glibc sys/gmon.h::
* Glibc sys/ptrace.h::
* Glibc sys/quota.h::
* Glibc sys/reboot.h::
+* Glibc sys/resource.h::
* Glibc sys/sem.h::
* Glibc sys/sendfile.h::
* Glibc sys/socket.h::
* Glibc sys/sysmacros.h::
* Glibc sys/time.h::
* Glibc sys/timex.h::
+* Glibc sys/uio.h::
* Glibc sys/ustat.h::
* Glibc sys/vlimit.h::
* Glibc sys/vm86.h::
@menu
* getdirentries::
+* scandirat::
* versionsort::
@end menu
@include glibc-functions/getdirentries.texi
+@include glibc-functions/scandirat.texi
@include glibc-functions/versionsort.texi
@node Glibc dlfcn.h
@menu
* fallocate::
+* name_to_handle_at::
* readahead::
+* open_by_handle_at::
@end menu
@include glibc-functions/fallocate.texi
+@include glibc-functions/name_to_handle_at.texi
@include glibc-functions/readahead.texi
+@include glibc-functions/open_by_handle_at.texi
@node Glibc fenv.h
@section Glibc Extensions to @code{<fenv.h>}
@include glibc-functions/putgrent.texi
@include glibc-functions/setgroups.texi
+@node Glibc gshadow.h
+@section Glibc @code{<gshadow.h>}
+
+@menu
+* endsgent::
+* fgetsgent::
+* fgetsgent_r::
+* getsgent::
+* getsgent_r::
+* getsgnam::
+* getsgnam_r::
+* putsgent::
+* setsgent::
+* sgetsgent::
+* sgetsgent_r::
+@end menu
+
+@include glibc-functions/endsgent.texi
+@include glibc-functions/fgetsgent.texi
+@include glibc-functions/fgetsgent_r.texi
+@include glibc-functions/getsgent.texi
+@include glibc-functions/getsgent_r.texi
+@include glibc-functions/getsgnam.texi
+@include glibc-functions/getsgnam_r.texi
+@include glibc-functions/putsgent.texi
+@include glibc-functions/setsgent.texi
+@include glibc-functions/sgetsgent.texi
+@include glibc-functions/sgetsgent_r.texi
+
@c @node Glibc iconv.h
@c @section Glibc Extensions to @code{<iconv.h>}
* mallinfo::
* malloc_get_state::
* malloc_set_state::
+* malloc_info::
* malloc_stats::
* malloc_trim::
* malloc_usable_size::
@include glibc-functions/mallinfo.texi
@include glibc-functions/malloc_get_state.texi
@include glibc-functions/malloc_set_state.texi
+@include glibc-functions/malloc_info.texi
@include glibc-functions/malloc_stats.texi
@include glibc-functions/malloc_trim.texi
@include glibc-functions/malloc_usable_size.texi
* inet6_option_init::
* inet6_option_next::
* inet6_option_space::
+* inet6_opt_append::
+* inet6_opt_find::
+* inet6_opt_finish::
+* inet6_opt_get_val::
+* inet6_opt_init::
+* inet6_opt_next::
+* inet6_opt_set_val::
+* inet6_rth_add::
+* inet6_rth_getaddr::
+* inet6_rth_init::
+* inet6_rth_reverse::
+* inet6_rth_segments::
+* inet6_rth_space::
* setipv4sourcefilter::
* setsourcefilter::
@end menu
@include glibc-functions/inet6_option_init.texi
@include glibc-functions/inet6_option_next.texi
@include glibc-functions/inet6_option_space.texi
+@include glibc-functions/inet6_opt_append.texi
+@include glibc-functions/inet6_opt_find.texi
+@include glibc-functions/inet6_opt_finish.texi
+@include glibc-functions/inet6_opt_get_val.texi
+@include glibc-functions/inet6_opt_init.texi
+@include glibc-functions/inet6_opt_next.texi
+@include glibc-functions/inet6_opt_set_val.texi
+@include glibc-functions/inet6_rth_add.texi
+@include glibc-functions/inet6_rth_getaddr.texi
+@include glibc-functions/inet6_rth_init.texi
+@include glibc-functions/inet6_rth_reverse.texi
+@include glibc-functions/inet6_rth_segments.texi
+@include glibc-functions/inet6_rth_space.texi
@include glibc-functions/setipv4sourcefilter.texi
@include glibc-functions/setsourcefilter.texi
* printf_size::
* printf_size_info::
* register_printf_function::
+* register_printf_modifier::
+* register_printf_specifier::
+* register_printf_type::
@end menu
@include glibc-functions/parse_printf_format.texi
@include glibc-functions/printf_size.texi
@include glibc-functions/printf_size_info.texi
@include glibc-functions/register_printf_function.texi
+@include glibc-functions/register_printf_modifier.texi
+@include glibc-functions/register_printf_specifier.texi
+@include glibc-functions/register_printf_type.texi
@node Glibc pthread.h
@section Glibc Extensions to @code{<pthread.h>}
@menu
+* pthread_attr_getaffinity_np::
+* pthread_attr_setaffinity_np::
+* pthread_getaffinity_np::
* pthread_getattr_np::
+* pthread_getname_np::
* pthread_kill_other_threads_np::
+* pthread_mutex_consistent_np::
+* pthread_mutexattr_getrobust_np::
+* pthread_mutexattr_setrobust_np::
* pthread_rwlockattr_getkind_np::
* pthread_rwlockattr_setkind_np::
+* pthread_setaffinity_np::
+* pthread_setname_np::
+* pthread_sigqueue::
+* pthread_timedjoin_np::
+* pthread_tryjoin_np::
* pthread_yield::
@end menu
+@include glibc-functions/pthread_attr_getaffinity_np.texi
+@include glibc-functions/pthread_attr_setaffinity_np.texi
+@include glibc-functions/pthread_getaffinity_np.texi
@include glibc-functions/pthread_getattr_np.texi
+@include glibc-functions/pthread_getname_np.texi
@include glibc-functions/pthread_kill_other_threads_np.texi
+@include glibc-functions/pthread_mutex_consistent_np.texi
+@include glibc-functions/pthread_mutexattr_getrobust_np.texi
+@include glibc-functions/pthread_mutexattr_setrobust_np.texi
@include glibc-functions/pthread_rwlockattr_getkind_np.texi
@include glibc-functions/pthread_rwlockattr_setkind_np.texi
+@include glibc-functions/pthread_setaffinity_np.texi
+@include glibc-functions/pthread_setname_np.texi
+@include glibc-functions/pthread_sigqueue.texi
+@include glibc-functions/pthread_timedjoin_np.texi
+@include glibc-functions/pthread_tryjoin_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>}
* clone::
* sched_getaffinity::
* sched_setaffinity::
+* setns::
@end menu
@include glibc-functions/clone.texi
@include glibc-functions/sched_getaffinity.texi
@include glibc-functions/sched_setaffinity.texi
+@include glibc-functions/setns.texi
@node Glibc search.h
@section Glibc Extensions to @code{<search.h>}
* qfcvt::
* qfcvt_r::
* qgcvt::
+* qsort_r::
* random_r::
* rpmatch::
+* secure_getenv::
* seed48_r::
* setstate_r::
* srand48_r::
@include glibc-functions/qfcvt.texi
@include glibc-functions/qfcvt_r.texi
@include glibc-functions/qgcvt.texi
+@include glibc-functions/qsort_r.texi
@include glibc-functions/random_r.texi
@include glibc-functions/rpmatch.texi
+@include glibc-functions/secure_getenv.texi
@include glibc-functions/seed48_r.texi
@include glibc-functions/setstate_r.texi
@include glibc-functions/srand48_r.texi
@include glibc-functions/epoll_ctl.texi
@include glibc-functions/epoll_wait.texi
+@node Glibc sys/fanotify.h
+@section Glibc @code{<sys/fanotify.h>}
+
+@menu
+* fanotify_init::
+* fanotify_mark::
+@end menu
+
+@include glibc-functions/fanotify_init.texi
+@include glibc-functions/fanotify_mark.texi
+
@node Glibc sys/file.h
@section Glibc @code{<sys/file.h>}
@include glibc-functions/reboot.texi
-@c @node Glibc sys/resource.h
-@c @section Glibc Extensions to @code{<sys/resource.h>}
+@node Glibc sys/resource.h
+@section Glibc Extensions to @code{<sys/resource.h>}
+
+@menu
+* prlimit::
+@end menu
+
+@include glibc-functions/prlimit.texi
@c @node Glibc sys/select.h
@c @section Glibc Extensions to @code{<sys/select.h>}
@menu
* accept4::
* isfdtype::
+* recvmmsg::
+* sendmmsg::
@end menu
@include glibc-functions/accept4.texi
@include glibc-functions/isfdtype.texi
+@include glibc-functions/recvmmsg.texi
+@include glibc-functions/sendmmsg.texi
@node Glibc sys/stat.h
@section Glibc Extensions to @code{<sys/stat.h>}
* adjtimex::
* ntp_adjtime::
* ntp_gettime::
+* ntp_gettimex::
@end menu
@include glibc-functions/adjtimex.texi
@include glibc-functions/ntp_adjtime.texi
@include glibc-functions/ntp_gettime.texi
+@include glibc-functions/ntp_gettimex.texi
@c @node Glibc sys/types.h
@c @section Glibc Extensions to @code{<sys/types.h>}
-@c @node Glibc sys/uio.h
-@c @section Glibc Extensions to @code{<sys/uio.h>}
+@node Glibc sys/uio.h
+@section Glibc Extensions to @code{<sys/uio.h>}
+
+@menu
+* preadv::
+* process_vm_readv::
+* process_vm_writev::
+* pwritev::
+@end menu
+
+@include glibc-functions/preadv.texi
+@include glibc-functions/process_vm_readv.texi
+@include glibc-functions/process_vm_writev.texi
+@include glibc-functions/pwritev.texi
@c @node Glibc sys/un.h
@c @section Glibc Extensions to @code{<sys/un.h>}
@section Glibc Extensions to @code{<time.h>}
@menu
+* clock_adjtime::
* dysize::
* getdate_r::
* stime::
* strptime_l::
* timegm::
* timelocal::
+* timespec_get::
@end menu
+@include glibc-functions/clock_adjtime.texi
@include glibc-functions/dysize.texi
@include glibc-functions/getdate_r.texi
@include glibc-functions/stime.texi
@include glibc-functions/strptime_l.texi
@include glibc-functions/timegm.texi
@include glibc-functions/timelocal.texi
+@include glibc-functions/timespec_get.texi
@c @node Glibc trace.h
@c @section Glibc Extensions to @code{<trace.h>}
@include glibc-functions/getttynam.texi
@include glibc-functions/setttyent.texi
+@c @node Glibc uchar.h
+@c @section Glibc Extensions to @code{<uchar.h>}
+
@c @node Glibc ucontext.h
@c @section Glibc Extensions to @code{<ucontext.h>}
* setresgid::
* setresuid::
* setusershell::
+* syncfs::
* syscall::
* ttyslot::
* vhangup::
@include glibc-functions/setresgid.texi
@include glibc-functions/setresuid.texi
@include glibc-functions/setusershell.texi
+@include glibc-functions/syncfs.texi
@include glibc-functions/syscall.texi
@include glibc-functions/ttyslot.texi
@include glibc-functions/vhangup.texi
* setutent::
* updwtmp::
* utmpname::
+* login::
+* 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.texi
+@include glibc-functions/login_tty.texi
@node Glibc utmpx.h
@section Glibc Extensions to @code{<utmpx.h>}
* alloca::
* alloca-opt::
* Safe Allocation Macros::
+* Compile-time Assertions::
+* Integer Properties::
+* extern inline::
* 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::
+* configmake::
* warnings::
* manywarnings::
+* Running self-tests under valgrind::
+* stat-size::
@end menu
@node alloca
@include safe-alloc.texi
+@include verify.texi
+
+@include intprops.texi
+
+@include extern-inline.texi
+
@node String Functions in C Locale
@section Character and String Functions in C Locale
@include gcd.texi
-@node Regular expressions
-@section Regular expressions
-
-Gnulib supports many different types of regular expressions; although
-the underlying features are the same or identical, the syntax used
-varies. The descriptions given here for the different types are
-generated automatically.
-
-@include regexprops-generic.texi
-
@include havelib.texi
@include lib-symbol-visibility.texi
@include func.texi
+@include configmake.texi
+
@include warnings.texi
@include manywarnings.texi
+@include valgrind-tests.texi
+
+@include stat-size.texi
+
+
+@node Regular expressions
+@chapter Regular expressions
+
+@menu
+* Overview::
+* Regular Expression Syntax::
+* Common Operators::
+* GNU Operators::
+* GNU Emacs Operators::
+* What Gets Matched?::
+* Programming with Regex::
+* Regular expression syntaxes::
+@end menu
+
+@lowersections
+@include regex.texi
+@raisesections
+
+@node Regular expression syntaxes
+@section Regular expression syntaxes
+
+Gnulib supports many different types of regular expressions; although
+the underlying features are the same or identical, the syntax used
+varies. The descriptions given here for the different types are
+generated automatically.
+
+@include regexprops-generic.texi
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
projects / gnulib.git / blobdiff