X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=1ff7720d5980d0840cee78d6b92a3b1f90b9d3b0;hb=fa1db0dd22768f09a507674a30beb5b8a87bb35f;hp=fc623b5adadc366e0988a6c42bae5c678f7ccab3;hpb=032310a69161066be953842f2dc69efae2f745a1;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index fc623b5ad..1ff7720d5 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2,8 +2,14 @@ @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 @@ -17,7 +23,7 @@ This manual is for GNU Gnulib (updated @value{UPDATED}), 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 @@ -51,8 +57,11 @@ Documentation License''. @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. @@ -61,6 +70,7 @@ Documentation License''. * 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 @@ -78,27 +88,37 @@ If you need this particular \thing\, you may write to @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:: @@ -113,38 +133,53 @@ Resources: @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 @@ -207,59 +242,532 @@ systems with g++ v3.3 to v4.2, AIX, OSF/1, IRIX). For this reason, it 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 }. +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 } +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 . +@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 }. + +@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 @@ -287,6 +795,147 @@ 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 --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{} 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{} and use it in a compilation unit that does not include +@code{}, 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 @@ -362,7 +1011,7 @@ XP. The function declaration is present if @code{WINVER >= 0x0501}. 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 @@ -424,7 +1073,7 @@ your favorite platform, you may perform these steps: @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=... @@ -448,7 +1097,7 @@ And then transferring the @file{dummy-0.tar.gz} file. @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 @@ -548,12 +1197,14 @@ which (known) portability problems are not worked around by Gnulib. * 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:: @@ -581,6 +1232,7 @@ which (known) portability problems are not worked around by Gnulib. * tgmath.h:: * time.h:: * trace.h:: +* uchar.h:: * ucontext.h:: * ulimit.h:: * unistd.h:: @@ -634,12 +1286,14 @@ which (known) portability problems are not worked around by Gnulib. @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 @@ -667,6 +1321,7 @@ which (known) portability problems are not worked around by Gnulib. @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 @@ -716,6 +1371,7 @@ by Gnulib. * aio_suspend:: * aio_write:: * alarm:: +* aligned_alloc:: * alphasort:: * asctime:: * asctime_r:: @@ -744,6 +1400,8 @@ by Gnulib. * bind:: * bsearch:: * btowc:: +* c16rtomb:: +* c32rtomb:: * cabs:: * cabsf:: * cabsl:: @@ -1229,6 +1887,8 @@ by Gnulib. * malloc:: * mblen:: * mbrlen:: +* mbrtoc16:: +* mbrtoc32:: * mbrtowc:: * mbsinit:: * mbsnrtowcs:: @@ -1517,6 +2177,7 @@ by Gnulib. * putwchar:: * pwrite:: * qsort:: +* quick_exit:: * raise:: * rand:: * rand_r:: @@ -1909,6 +2570,7 @@ by Gnulib. @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 @@ -1937,6 +2599,8 @@ by Gnulib. @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 @@ -2422,6 +3086,8 @@ by Gnulib. @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 @@ -2710,6 +3376,7 @@ by Gnulib. @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 @@ -3076,7 +3743,7 @@ by Gnulib. @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. @@ -3166,6 +3833,7 @@ not worked around by Gnulib. * fstab.h:: * fts.h:: * getopt.h:: +* gshadow.h:: * ieee754.h:: * ifaddrs.h:: * libintl.h:: @@ -3199,6 +3867,7 @@ not worked around by Gnulib. @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 @@ -3252,6 +3921,7 @@ This list of functions is sorted according to the header that declares them. * Glibc glob.h:: * Glibc gnu/libc-version.h:: * Glibc grp.h:: +* Glibc gshadow.h:: * Glibc ifaddrs.h:: * Glibc libintl.h:: * Glibc link.h:: @@ -3265,6 +3935,7 @@ This list of functions is sorted according to the header that declares them. * Glibc obstack.h:: * Glibc printf.h:: * Glibc pthread.h:: +* Glibc pty.h:: * Glibc pwd.h:: * Glibc regex.h:: * Glibc regexp.h:: @@ -3290,6 +3961,7 @@ This list of functions is sorted according to the header that declares them. * Glibc rpcsvc/ypupd.h:: * Glibc sched.h:: * Glibc search.h:: +* Glibc selinux/selinux.h:: * Glibc shadow.h:: * Glibc signal.h:: * Glibc stdio.h:: @@ -3297,6 +3969,7 @@ This list of functions is sorted according to the header that declares them. * 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:: @@ -3311,6 +3984,7 @@ This list of functions is sorted according to the header that declares them. * 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:: @@ -3323,6 +3997,7 @@ This list of functions is sorted according to the header that declares them. * 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:: @@ -3519,10 +4194,12 @@ This list of functions is sorted according to the header that declares them. @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 @@ -3632,10 +4309,16 @@ This list of functions is sorted according to the header that declares them. @section Glibc Extensions to @code{} @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{} @@ -3757,6 +4440,35 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/putgrent.texi @include glibc-functions/setgroups.texi +@node Glibc gshadow.h +@section Glibc @code{} + +@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{} @@ -3833,6 +4545,7 @@ This list of functions is sorted according to the header that declares them. * mallinfo:: * malloc_get_state:: * malloc_set_state:: +* malloc_info:: * malloc_stats:: * malloc_trim:: * malloc_usable_size:: @@ -3844,6 +4557,7 @@ This list of functions is sorted according to the header that declares them. @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 @@ -4092,6 +4806,19 @@ This list of functions is sorted according to the header that declares them. * 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 @@ -4107,6 +4834,19 @@ This list of functions is sorted according to the header that declares them. @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 @@ -4144,32 +4884,70 @@ This list of functions is sorted according to the header that declares them. * 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{} @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{} +@node Glibc pty.h +@section Glibc @code{} + +@menu +* forkpty:: +* openpty:: +@end menu + +@include glibc-functions/forkpty.texi +@include glibc-functions/openpty.texi @node Glibc pwd.h @section Glibc Extensions to @code{} @@ -4883,11 +5661,13 @@ This list of functions is sorted according to the header that declares them. * 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{} @@ -4904,6 +5684,20 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/hsearch_r.texi @include glibc-functions/tdestroy.texi +@node Glibc selinux/selinux.h +@section Glibc Extensions to @code{} + +@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{} @@ -5061,7 +5855,10 @@ This list of functions is sorted according to the header that declares them. * jrand48_r:: * lcong48_r:: * lrand48_r:: +* mkostemp:: +* mkostemps:: * mrand48_r:: +* mkstemps:: * nrand48_r:: * on_exit:: * ptsname_r:: @@ -5070,8 +5867,10 @@ This list of functions is sorted according to the header that declares them. * qfcvt:: * qfcvt_r:: * qgcvt:: +* qsort_r:: * random_r:: * rpmatch:: +* secure_getenv:: * seed48_r:: * setstate_r:: * srand48_r:: @@ -5101,7 +5900,10 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5110,8 +5912,10 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5188,6 +5992,17 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/epoll_ctl.texi @include glibc-functions/epoll_wait.texi +@node Glibc sys/fanotify.h +@section Glibc @code{} + +@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{} @@ -5337,8 +6152,14 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/reboot.texi -@c @node Glibc sys/resource.h -@c @section Glibc Extensions to @code{} +@node Glibc sys/resource.h +@section Glibc Extensions to @code{} + +@menu +* prlimit:: +@end menu + +@include glibc-functions/prlimit.texi @c @node Glibc sys/select.h @c @section Glibc Extensions to @code{} @@ -5368,10 +6189,16 @@ This list of functions is sorted according to the header that declares them. @section Glibc Extensions to @code{} @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{} @@ -5461,12 +6288,14 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5483,17 +6312,31 @@ This list of functions is sorted according to the header that declares them. * 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{} -@c @node Glibc sys/uio.h -@c @section Glibc Extensions to @code{} +@node Glibc sys/uio.h +@section Glibc Extensions to @code{} + +@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{} @@ -5606,20 +6449,24 @@ This list of functions is sorted according to the header that declares them. @section Glibc Extensions to @code{} @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{} @@ -5639,6 +6486,9 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/getttynam.texi @include glibc-functions/setttyent.texi +@c @node Glibc uchar.h +@c @section Glibc Extensions to @code{} + @c @node Glibc ucontext.h @c @section Glibc Extensions to @code{} @@ -5653,8 +6503,10 @@ This list of functions is sorted according to the header that declares them. * brk:: * chroot:: * daemon:: +* dup3:: * endusershell:: * euidaccess:: +* execvpe:: * get_current_dir_name:: * getdomainname:: * getdtablesize:: @@ -5664,6 +6516,7 @@ This list of functions is sorted according to the header that declares them. * getresuid:: * getusershell:: * group_member:: +* pipe2:: * profil:: * revoke:: * sbrk:: @@ -5674,6 +6527,7 @@ This list of functions is sorted according to the header that declares them. * setresgid:: * setresuid:: * setusershell:: +* syncfs:: * syscall:: * ttyslot:: * vhangup:: @@ -5683,8 +6537,10 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5694,6 +6550,7 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5704,6 +6561,7 @@ This list of functions is sorted according to the header that declares them. @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 @@ -5726,6 +6584,8 @@ This list of functions is sorted according to the header that declares them. * setutent:: * updwtmp:: * utmpname:: +* login:: +* login_tty:: @end menu @include glibc-functions/endutent.texi @@ -5739,6 +6599,8 @@ This list of functions is sorted according to the header that declares them. @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{} @@ -5814,17 +6676,25 @@ This list of functions is sorted according to the header that declares them. @menu * 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:: -* Safe Allocation Macros:: +* Running self-tests under valgrind:: +* stat-size:: @end menu @node alloca @@ -5837,6 +6707,14 @@ This list of functions is sorted according to the header that declares them. @findex alloca @include alloca-opt.texi +@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 @@ -5895,27 +6773,56 @@ ASCII characters. @include gcd.texi -@node Regular expressions -@section Regular expressions +@include havelib.texi -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 lib-symbol-visibility.texi -@include regexprops-generic.texi +@include ld-version-script.texi -@include havelib.texi +@include ld-output-def.texi @include relocatable-maint.texi @include func.texi +@include configmake.texi + @include warnings.texi @include manywarnings.texi -@include safe-alloc.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