X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=1e1ad40fa03e04e3c5b16c3fb783c61cce580ffd;hb=b7b02f28a67ed112845d6010833dc81858ca7890;hp=429bf4c175c5c68b5df3f1c3903157c0a5f12f87;hpb=17f87c3231d8808b8e873126abf15e6e8b9a0e67;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 429bf4c17..1e1ad40fa 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,10 +1,15 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.44 2007-09-09 13:20:45 haible Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib +@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 @@ -18,8 +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, 2005, 2006, 2007, 2008 Free Software -Foundation, Inc. +Copyright @copyright{} 2004-2011 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 @@ -55,6 +59,8 @@ Documentation License''. @menu * Introduction:: * Invoking gnulib-tool:: +* Writing modules:: +* Extending Gnulib:: * Miscellaneous Notes:: * POSIX Substitutes Library:: Building as a separate substitutes library. * Header File Substitutes:: Overriding system headers. @@ -63,6 +69,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 @@ -101,6 +108,7 @@ Resources: * Benefits:: * Library vs Reusable Code:: * Portability and Application Code:: +* Target Platforms:: * Modules:: * Various Kinds of Modules:: * Collaborative Development:: @@ -115,37 +123,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:: -* 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 @@ -208,59 +232,696 @@ 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} implicity depends on the corresponding non-test +module @code{foo}. @code{foo} implicitly depends on @code{foo-tests} if the +latter exists and if the option @code{--with-tests} has been given. + +Tests modules can depend on non-tests modules. Non-tests modules should not +depend on tests modules. (Recall that tests modules are built in a separate +directory.) + +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 + +@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 +@section Obsolete modules + +@cindex Obsolete modules +Modules can be marked obsolete. This means that the problems they fix +don't occur any more on the platforms that are reasonable porting targets +now. @code{gnulib-tool} warns when obsolete modules are mentioned on the +command line, and by default ignores dependencies from modules to obsolete +modules. When you pass the option @code{--with-obsolete} to +@code{gnulib-tool}, dependencies to obsolete modules will be included, +however, unless blocked through an @code{--avoid} option. This option +is useful if your package should be portable even to very old platforms. + +In order to mark a module obsolete, you need to add this to the module +description: + +@example +Status: +obsolete + +Notice: +This module is obsolete. +@end example + + +@node Extra tests modules +@section Extra tests modules + +@cindex Extra tests modules +@cindex C++ tests modules +@cindex tests modules, C++ +@cindex long-running tests modules +@cindex tests modules, long-running +@cindex privileged tests modules +@cindex tests modules, privileged +@cindex unportable tests modules +@cindex tests modules, unportable +Test modules can be marked with some special status attributes. When a +test module has such an attribute, @code{gnulib-tool --import} will not +include it by default. + +The supported status attributes are: + +@table @code +@item c++-test +Indicates that the test is testing C++ interoperability. Such a test is +useful in a C++ or mixed C/C++ package, but is useless in a C package. + +@item longrunning-test +Indicates that the test takes a long time to compile or execute (more +than five minutes or so). Such a test is better avoided in a release +that is made for the general public. + +@item privileged-test +Indicates that the test will request special privileges, for example, +ask for the superuser password. Such a test may hang when run +non-interactively and is therefore better avoided in a release that is +made for the general public. + +@item unportable-test +Indicates that the test is known to fail on some systems, and that +there is no workaround about it. Such a test is better avoided in a +release that is made for the general public. +@end table + +@code{gnulib-tool --import} will not include tests marked with these +attributes by default. When @code{gnulib-tool} is invoked with one +of the options @code{--with-c++-tests}, @code{--with-longrunning-tests}, +@code{--with-privileged-tests}, @code{--with-unportable-tests}, it +will include tests despite the corresponding special status attribute. +When @code{gnulib-tool} receives the option @code{--with-all-tests}, +it will include all tests regardless of their status attributes. + +@code{gnulib-tool --create-testdir} and +@code{gnulib-tool --create-megatestdir} by default include all tests of +modules specified on the command line, regardless of their status +attributes. Tests of modules occurring as dependencies are not included +by default if they have one of these status attributes. The options +@code{--with-c++-tests}, @code{--with-longrunning-tests}, +@code{--with-privileged-tests}, @code{--with-unportable-tests} are +recognized here as well. Additionally, @code{gnulib-tool} also +understands the options @code{--without-c++-tests}, +@code{--without-longrunning-tests}, @code{--without-privileged-tests}, +@code{--without-unportable-tests}. + +In order to mark a module with a status attribute, you need to add it +to the module description, like this: + +@example +Status: +longrunning-test +@end example + +If only a part of a test deserves a particular status attribute, you +can split the module into a primary and a secondary test module, +say @code{foo-tests} and @code{foo-extra-tests}. Then add a dependency +from @code{foo-tests} to @code{foo-extra-tests}, and mark the +@code{foo-extra-tests} with the particular status attribute. + + +@node A C++ namespace for gnulib +@section A C++ namespace for gnulib + +The function definitions provided by Gnulib (@code{.c} code) are meant +to be compiled by a C compiler. The header files (@code{.h} files), +on the other hand, can be used in either C or C++. + +By default, when used in a C++ compilation unit, the @code{.h} files +declare the same symbols and overrides as in C mode, except that functions +defined by Gnulib or by the system are declared as @samp{extern "C"}. + +It is also possible to indicate to Gnulib to provide many of its symbols +in a dedicated C++ namespace. If you define the macro +@code{GNULIB_NAMESPACE} to an identifier, many functions will be defined +in the namespace specified by the identifier instead of the global +namespace. For example, after you have defined +@smallexample +#define GNULIB_NAMESPACE gnulib +@end smallexample +@noindent +at the beginning of a compilation unit, Gnulib's @code{} 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 @@ -338,7 +999,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 @@ -3241,6 +3902,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:: @@ -3266,6 +3928,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:: @@ -3608,9 +4271,11 @@ This list of functions is sorted according to the header that declares them. @section Glibc Extensions to @code{} @menu +* fallocate:: * readahead:: @end menu +@include glibc-functions/fallocate.texi @include glibc-functions/readahead.texi @node Glibc fenv.h @@ -4144,8 +4809,16 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/pthread_rwlockattr_setkind_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{} @@ -4880,6 +5553,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{} @@ -5037,7 +5724,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:: @@ -5077,7 +5767,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 @@ -5344,9 +6037,11 @@ This list of functions is sorted according to the header that declares them. @section Glibc Extensions to @code{} @menu +* accept4:: * isfdtype:: @end menu +@include glibc-functions/accept4.texi @include glibc-functions/isfdtype.texi @node Glibc sys/stat.h @@ -5437,12 +6132,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 @@ -5629,8 +6326,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:: @@ -5640,6 +6339,7 @@ This list of functions is sorted according to the header that declares them. * getresuid:: * getusershell:: * group_member:: +* pipe2:: * profil:: * revoke:: * sbrk:: @@ -5659,8 +6359,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 @@ -5670,6 +6372,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 @@ -5702,6 +6405,7 @@ This list of functions is sorted according to the header that declares them. * setutent:: * updwtmp:: * utmpname:: +* login_tty:: @end menu @include glibc-functions/endutent.texi @@ -5715,6 +6419,7 @@ 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_tty.texi @node Glibc utmpx.h @section Glibc Extensions to @code{} @@ -5790,15 +6495,23 @@ 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:: * 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:: @end menu @node alloca @@ -5811,6 +6524,12 @@ 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 + @node String Functions in C Locale @section Character and String Functions in C Locale @@ -5864,26 +6583,58 @@ ASCII characters. @include c-strtold.texi @include quote.texi + @include error.texi + @include gcd.texi -@include relocatable-maint.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 ld-output-def.texi + +@include relocatable-maint.texi @include func.texi +@include configmake.texi + @include warnings.texi @include manywarnings.texi +@include valgrind-tests.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