better to share them.
-
@node Miscellaneous Notes
@chapter Miscellaneous Notes
* Build robot for gnulib::
@end menu
+@include out-of-memory.texi
-@node Out of memory handling
-@section Out of memory handling
-
-@cindex Out of Memory handling
-@cindex Memory allocation failure
-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 (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_die) (void);
-@end example
-
-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 --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 Modules that modify the way other modules work
-@section Modules that modify the way other modules work
-
-The normal way to design modules is that each module has its own code,
-and the module dependencies provide the facilities on which this code
-can rely. But sometimes it is necessary to use more advanced
-techniques. For example:
-@itemize
-@item
-You may want to have optional module dependencies: Let module A use
-facilities provided by module B, if module B is present, but without
-requiring that module B is present.
-@item
-A module can indicate support for particular behaviours. For example,
-Gnulib has a module @samp{sigpipe} that requests POSIX compatible
-SIGPIPE behaviour from all other modules -- something that is not
-enabled by default. Or consider the @samp{nonblocking} module, that is
-an indicator that all I/O functions should handle non-blocking file
-descriptors -- something that, equally, is not enabled by default.
-@item
-A module can indicate to other modules that they can rely on certain
-guarantees, and thus omit specific code. For example, when Gnulib's
-@samp{malloc-gnu} module is present, you can omit code that test
-@code{n} against zero when you call @code{malloc (n)}.
-@end itemize
-
-Be aware that these advanced techniques likely cause breakage in the
-situation of multiple @code{gnulib-tool} invocations in the scope of a
-single @code{configure} file. This is because the question ``is module
-B present?'' does not have a unique answer in such situations.
-@code{gnulib-tool} has support for these techniques in the situation of
-@code{--create-testdir --single-configure}, which basically has two
-@code{gnulib-tool} invocations, one for a set of modules that end up in
-@code{gllib}, and one for the set of modules that end up in
-@code{gltests}. But you should be aware that this does not cover the
-general situation.
-
-Which technique to use, depends on the answer to the question: ``If my
-module occurs among the modules of @code{gltests}, should it have an
-effect on the modules in @code{gllib}?''
-
-If the answer is ``no'', your module description should invoke the
-Autoconf macro @code{gl_MODULE_INDICATOR}. This Autoconf macro takes
-one argument: the name of your module. The effect of
-@code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in
-@code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates
-whether your macro is considered to be present. This works even when
-your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}}
-will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}.
-
-If the answer is ``yes'', you have two techniques available. The first
-one is to invoke a similar Autoconf macro, named
-@code{gl_MODULE_INDICATOR_FOR_TESTS}. It works similarly. However,
-when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}}
-will evaluate to 1 both in @code{gltests} and in @code{gllib}.
-
-The second one is to define a shell variable in the @code{configure}
-file that tells whether your module is present, through use of
-@code{m4_divert_text}. The Autoconf macros of a dependency module will
-initialize this shell variable, through
-@samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}. The
-Autoconf macros of your module will override this value, through
-@samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}. Then
-you can use @code{@var{my_shell_var}} in the Autoconf macros of both
-modules. You can find more details about this technique in the Gnulib
-module @code{getopt-gnu}.
-
-Reminder: These techniques are advanced. They have the potential to
-cause lots of headaches if you apply them incorrectly.
-
-
-@node A C++ namespace for gnulib
-@section A C++ namespace for gnulib
-
-The function definitions provided by Gnulib (@code{.c} code) are meant
-to be compiled by a C compiler. The header files (@code{.h} files),
-on the other hand, can be used in either C or C++.
-
-By default, when used in a C++ compilation unit, the @code{.h} files
-declare the same symbols and overrides as in C mode, except that functions
-defined by Gnulib or by the system are declared as @samp{extern "C"}.
-
-It is also possible to indicate to Gnulib to provide many of its symbols
-in a dedicated C++ namespace. If you define the macro
-@code{GNULIB_NAMESPACE} to an identifier, many functions will be defined
-in the namespace specified by the identifier instead of the global
-namespace. For example, after you have defined
-@smallexample
-#define GNULIB_NAMESPACE gnulib
-@end smallexample
-@noindent
-at the beginning of a compilation unit, Gnulib's @code{<fcntl.h>} header
-file will make available the @code{open} function as @code{gnulib::open}.
-The symbol @code{open} will still refer to the system's @code{open} function,
-with its platform specific bugs and limitations.
-
-The symbols provided in the Gnulib namespace are those for which the
-corresponding header file contains a @code{_GL_CXXALIAS_RPL} or
-@code{_GL_CXXALIAS_SYS} macro invocation.
-
-The benefits of this namespace mode are:
-@itemize
-@item
-Gnulib defines fewer symbols as preprocessor macros. For example, on a
-platform where @code{open} has to be overridden, Gnulib normally does
-@code{#define open rpl_open}. If your package has a class with a member
-@code{open}, for example a class @code{foo} with a method @code{foo::open},
-then if you define this member in a compilation unit that includes
-@code{<fcntl.h>} and use it in a compilation unit that does not include
-@code{<fcntl.h>}, or vice versa, you will get a link error. Worse: You
-will not notice this problem on the platform where the system's @code{open}
-function works fine. This problem goes away in namespace mode.
-
-@item
-It provides a safety check whether the set of modules your package requests
-from Gnulib is sufficient. For example, if you use the function
-@code{gnulib::open} in your code, and you forgot to request the module
-@samp{open} from Gnulib, you will get a compilation error (regardless of
-the platform).
-@end itemize
-
-The drawback of this namespace mode is that the system provided symbols in
-the global namespace are still present, even when they contain bugs that
-Gnulib fixes. For example, if you call @code{open (...)} in your code,
-it will invoke the possibly buggy system function, even if you have
-requested the module @samp{open} from gnulib-tool.
-
-You can turn on the namespace mode in some compilation units and keep it
-turned off in others. This can be useful if your package consists of
-an application layer that does not need to invoke POSIX functions and
-an operating system interface layer that contains all the OS function
-calls. In such a situation, you will want to turn on the namespace mode
-for the application layer---to avoid many preprocessor macro
-definitions---and turn it off for the OS interface layer---to avoid
-the drawback of the namespace mode, mentioned above.
-
-
-@node Library version handling
-@section Library version handling
-
-The module @samp{check-version} can be useful when your gnulib
-application is a system library. You will typically wrap the call to
-the @code{check_version} function through a library API, your library
-header file may contain:
-
-@example
-#define STRINGPREP_VERSION "0.5.18"
-...
- extern const char *stringprep_check_version (const char *req_version);
-@end example
-
-To avoid ELF symbol collisions with other libraries that use the
-@samp{check-version} module, add to @file{config.h} through a
-AC_DEFINE something like:
-
-@example
-AC_DEFINE(check_version, stringprep_check_version,
- [Rename check_version.])
-@end example
-
-The @code{stringprep_check_version} function will thus be implemented
-by the @code{check_version} module.
-
-There are two uses of the interface. The first is a way to provide
-for applications to find out the version number of the library it
-uses. The application may contain diagnostic code such as:
-
-@example
- printf ("Stringprep version: header %s library %s",
- STRINGPREP_VERSION,
- stringprep_check_version (NULL));
-@end example
-
-Separating the library and header file version can be useful when
-searching for version mismatch related problems.
-
-The second uses is as a rudimentary test of proper library version, by
-making sure the application get a library version that is the same, or
-newer, than the header file used when building the application. This
-doesn't catch all problems, libraries may change backwards incompatibly
-in later versions, but enable applications to require a certain
-minimum version before it may proceed.
-
-Typical uses look like:
-
-@example
- /* Check version of libgcrypt. */
- if (!gcry_check_version (GCRYPT_VERSION))
- die ("version mismatch\n");
-@end example
-
-
-@node Windows sockets
-@section Windows sockets
-
-There are several issues when building applications that should work
-under Windows. The most problematic part is for applications that use
-sockets.
-
-Hopefully, we can add helpful notes to this section that will help you
-port your application to Windows using gnulib.
-
-@subsection Getaddrinfo and WINVER
-
-This was written for the getaddrinfo module, but may be applicable to
-other functions too.
-
-The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
-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 the (partial) getaddrinfo
-implementation.
-
-If you want to support Windows 2000, don't do anything. The
-replacement function will open @file{WS2_32.DLL} during run-time to
-see if there is a getaddrinfo function available, and use it when
-available.
-
-@node Libtool and Windows
-@section Libtool and Windows
-
-If you want it to be possible to cross-compile your program to MinGW
-and you use Libtool, you need to use the @code{win32-dll} option of
-@code{LT_INIT}. In other words, put:
-
-@example
-LT_INIT([win32-dll])
-@end example
-
-in your @file{configure.ac}. This sets the correct names for the
-@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
+@include obsolete.texi
-If you are building a library, you will also need to pass
-@code{-no-undefined} to make sure Libtool produces a DLL for your
-library. From a @file{Makefile.am}:
-
-@example
-libgsasl_la_LDFLAGS += -no-undefined
-@end example
-
-
-@node License Texinfo sources
-@section License Texinfo sources
-
-Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
-in Texinfo form. (The master location is
-@url{http://www.gnu.org/licenses/}). These Texinfo documents do not
-have any node names and structures built into them; for your manual,
-you should @code{@@include} them in an appropriate @code{@@node}.
-
-The conventional name for the GPL node is @samp{Copying} and for the FDL
-@samp{GNU Free Documentation License}. The LGPL doesn't seem to have
-a conventional node name.
-
-Of course the license texts themselves should not be changed at all.
+@include extra-tests.texi
+@include transversal.texi
-@node Build robot for gnulib
-@section Build robot for gnulib
+@include namespace.texi
-To simplify testing on a wide set of platforms, gnulib is built on
-many platforms every day and the results are uploaded to:
+@include check-version.texi
-@url{http://autobuild.josefsson.org/gnulib/}
+@include windows-sockets.texi
-If you wish to help the gnulib development effort with build logs for
-your favorite platform, you may perform these steps:
+@include windows-libtool.texi
-@enumerate
-
-@item Create gnulib directory
-
-On a machine with GNU development tools installed and with a gnulib
-git checkout, use
-
-@example
-gnulib-tool --create-megatestdir --with-tests --dir=...
-@end example
+@include licenses-texi.texi
-Note: The created directory uses ca. 512 MB on disk.
+@include build-automation.texi
-@item Transfer gnulib directory
-
-Transfer this directory to a build machine (HP-UX, Cygwin, or
-whatever). Often it is easier to transfer one file, and this can be
-achieved by running, inside the directory the following commands:
-
-@example
-./configure
-make dist
-@end example
-
-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 @file{logs/} with a log file for each module.
-
-@item Submit build logs
-
-Submit each log file to Simon's site, either through a
-
-@example
-mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/`
-@end example
-
-or through netcat
-
-@example
-autobuild-submit logs/*
-@end example
-
-@end enumerate
@node POSIX Substitutes Library
@chapter Building the ISO C and POSIX Substitutes
@include extern-inline.texi
-@node String Functions in C Locale
-@section Character and String Functions in C Locale
-
-The functions in this section are similar to the generic string functions
-from the standard C library, except that
-@itemize
-@item
-They behave as if the locale was set to the "C" locale, even when the
-locale is different, and/or
-@item
-They are specially optimized for the case where all characters are plain
-ASCII characters.
-@end itemize
-
-@menu
-* c-ctype::
-* c-strcase::
-* c-strcaseeq::
-* c-strcasestr::
-* c-strstr::
-* c-strtod::
-* c-strtold::
-@end menu
-
-@node c-ctype
-@subsection c-ctype
-@include c-ctype.texi
-
-@node c-strcase
-@subsection c-strcase
-@include c-strcase.texi
-
-@node c-strcaseeq
-@subsection c-strcaseeq
-@include c-strcaseeq.texi
-
-@node c-strcasestr
-@subsection c-strcasestr
-@include c-strcasestr.texi
-
-@node c-strstr
-@subsection c-strstr
-@include c-strstr.texi
-
-@node c-strtod
-@subsection c-strtod
-@include c-strtod.texi
-
-@node c-strtold
-@subsection c-strtold
-@include c-strtold.texi
+@include c-locale.texi
@include quote.texi