X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=a1f54461cf987c13216342262160dfa431864218;hb=89d7698a351cd36d0e7baa44ee4bea3cf56cf459;hp=d9383f6a963616a903298450dadc74d02f77192a;hpb=cfabb63265a6319684bba91e62242e29bcf0e2d7;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index d9383f6a9..a1f54461c 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -17,7 +17,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-2010 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -53,6 +53,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. @@ -113,38 +115,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,20 +224,485 @@ 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.) + +@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 as a developer a idea which part of the test +failed, even when you don't have access to the machine where the test failed +and the reporting user cannot run a debugger. + +Sometimes it is convenient to write part of the test as a shell script. +(For example, in areas related to process control or interprocess +communication, or when different locales should be tried.) In these cases, +the typical module description is like this: + +@smallexample +Files: +tests/test-foo.sh +tests/test-foo.c +tests/macros.h + +Depends-on: + +configure.ac: + +Makefile.am: +TESTS += test-foo.sh +TESTS_ENVIRONMENT += FOO_BAR='@@FOO_BAR@@' +check_PROGRAMS += test-foo +@end smallexample + +Here, the @code{TESTS_ENVIRONMENT} variable can be used to pass values +determined by @code{configure} or by the @code{Makefile} to the shell +script, as environment variables. The values of @code{EXEEXT} and of +@code{srcdir}, from Autoconf and Automake, are already provided as +environment variables, through an initial value of @code{TESTS_ENVIRONMENT} +that @code{gnulib-tool} puts in place. + +Regardless of the specific form of the unit test, the following guidelines +should be respected: + +@itemize +@item +A test indicates success by exiting with exit code 0. It should normally +not produce output in this case. (Output to temporary files that are +cleaned up at the end of the test are possible, of course.) +@item +A test indicates failure by exiting with an exit code different from 0 and 77, +typically 1. It is useful to print a message about the failure in this case. +The @code{ASSERT} macro already does so. +@item +A test indicates "skip", that is, that most of its interesting functionality +could not be performed, through a return code of 77. A test should also +print a message to stdout or stderr about the reason for skipping. +For example: +@smallexample + fputs ("Skipping test: multithreading not enabled\n", stderr); + return 77; +@end smallexample +Such a message helps detecting bugs in the autoconf macros: A simple message +@samp{SKIP: test-foo} does not sufficiently catch the attention of the user. +@end itemize + + +@node Incompatible changes +@section Incompatible changes + +Incompatible changes to Gnulib modules should be mentioned in Gnulib's +@file{NEWS} file. Incompatible changes here mean that existing source code +may not compile or work any more. + +We don't mean changes in the binary interface (ABI), since +@enumerate +@item +Gnulib code is used in source-code form. +@item +The user who distributes libraries that contain Gnulib code is supposed to +bump the version number in the way described in the Libtool documentation +before every release. +@end enumerate + + +@node Extending Gnulib +@chapter Extending Gnulib + +Gnulib modules are intended to be suitable for widespread use. Most +problems with Gnulib can and should be fixed in a generic way, so that +all of Gnulib's users can benefit from the change. But occasionally a +problem arises that is difficult or undesirable to fix generically, or +a project that uses Gnulib may need to work around an issue before the +Gnulib maintainers commit a final fix. Maintainers may also want to +add their own pools of modules to projects as Gnulib ``staging +areas.'' + +The obvious way to make local changes to Gnulib modules is to use +@command{gnulib-tool} to check out pristine modules, then to modify +the results in-place. This works well enough for short-lived +experiments. It is harder to keep modified versions of Gnulib modules +for a long time, even though Git (or another distributed version +control systems) can help out a lot with this during the development +process. + +Git, however, doesn't address the distribution issue. When a package +``foobar'' needs a modified version of, say, @file{stdint.in.h}, it +either has to put a comment into @file{foobar/autogen.sh} saying +``Attention! This doesn't work with a pristine Gnulib, you need this +and that patch after checking out Gnulib,'' or it has to use the +@samp{--avoid=stdint} option and provide the modified @code{stdint} +module in a different directory. + +The @option{--local-dir} option to @command{gnulib-tool} solves this +problem. It allows the package to override or augment Gnulib. This +means: + +@itemize @bullet +@item +You can store files that are to override Gnulib files or modules. + +@item +You can store context diffs to be applied to Gnulib files. + +@item +You can add modules of your own, that are not (yet) in Gnulib. + +@item +You can also add unstructured amounts of code to the library, by +grouping the non-Gnulib files of the library in a single kitchen-sink +``module.'' (This kind of kitchen-sink module is not needed when you +use the @command{gnulib-tool} option @samp{--makefile-name}.) +@end itemize + +In a release tarball, you can distribute the contents of this +@option{--local-dir} directory that will be combinable with newer +versions of Gnulib, barring incompatible changes to Gnulib. + +If the @samp{--local-dir=@var{directory}} option is specified, then +@command{gnulib-tool} looks in @file{@var{directory}} whenever it +reads a file from the Gnulib directory. Suppose @command{gnulib-tool} +is looking for @var{file}. Then: + +@itemize @bullet +@item +If @file{@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses +it instead of the file included in Gnulib. + +@item +Otherwise, if @file{@var{directory}/@var{file}.diff} exists, then +@command{gnulib-tool} uses the file from Gnulib after applying the diff +using the @command{patch} program. + +@item +Otherwise, @command{gnulib-tool} uses the file included in Gnulib. +@end itemize + +Please make wise use of this option. It also allows you to easily +hold back modifications you make to Gnulib macros in cases it may be +better to share them. + + + +@node Miscellaneous Notes +@chapter Miscellaneous Notes + +@menu +* Out of memory handling:: +* Obsolete modules:: +* Extra tests modules:: +* A C++ namespace for gnulib:: A different way of using Gnulib in C++ +* Library version handling:: +* Windows sockets:: +* Libtool and Windows:: +* License Texinfo sources:: +* Build robot for gnulib:: +@end menu + + @node Out of memory handling @section Out of memory handling @@ -287,6 +769,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} 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 @section Library version handling @@ -3265,6 +3888,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 +3914,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:: @@ -3632,9 +4257,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 @@ -4168,8 +4795,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{} @@ -4904,6 +5539,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 +5710,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:: @@ -5101,7 +5753,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 @@ -5368,9 +6023,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 @@ -5461,12 +6118,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 @@ -5653,8 +6312,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 +6325,7 @@ This list of functions is sorted according to the header that declares them. * getresuid:: * getusershell:: * group_member:: +* pipe2:: * profil:: * revoke:: * sbrk:: @@ -5683,8 +6345,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 +6358,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 @@ -5726,6 +6391,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 @@ -5739,6 +6405,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{} @@ -5814,16 +6481,21 @@ This list of functions is sorted according to the header that declares them. @menu * alloca:: * alloca-opt:: +* Safe Allocation Macros:: * String Functions in C Locale:: * Quoting:: * error and progname:: * gcd:: * Regular expressions:: * Searching for Libraries:: +* Exported Symbols of Shared Libraries:: +* LD Version Scripts:: +* Visual Studio Compatibility:: * Supporting Relocation:: * func:: * warnings:: * manywarnings:: +* Running self-tests under valgrind:: @end menu @node alloca @@ -5836,6 +6508,8 @@ This list of functions is sorted according to the header that declares them. @findex alloca @include alloca-opt.texi +@include safe-alloc.texi + @node String Functions in C Locale @section Character and String Functions in C Locale @@ -5906,6 +6580,12 @@ generated automatically. @include havelib.texi +@include lib-symbol-visibility.texi + +@include ld-version-script.texi + +@include ld-output-def.texi + @include relocatable-maint.texi @include func.texi @@ -5914,6 +6594,7 @@ generated automatically. @include manywarnings.texi +@include valgrind-tests.texi @node GNU Free Documentation License @appendix GNU Free Documentation License