2006-07-14 Simon Josefsson <jas@extundo.com>

[gnulib.git] / doc / gnulib.texi

\input texinfo   @c -*-texinfo-*-
@comment $Id: gnulib.texi,v 1.25 2006-07-14 09:32:13 jas Exp $
@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
@syncodeindex fn cp
@syncodeindex pg cp
@comment %**end of header

@set UPDATED $Date: 2006-07-14 09:32:13 $

@copying
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 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@dircategory Software development
@direntry
* Gnulib: (gnulib).             Source files to share among distributions.
@end direntry

@titlepage
@title GNU Gnulib
@subtitle updated @value{UPDATED}
@author @email{bug-gnulib@@gnu.org}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Gnulib

@insertcopying
@end ifnottex

@menu
* Gnulib::
* Invoking gnulib-tool::
* Copying This Manual::
* Index::
@end menu


@node Gnulib
@chapter Gnulib

This manual contains some bare-bones documentation, but not much more.
It's mostly been a place to store notes until someone (you?)@ gets
around to writing a coherent manual.

Getting started:

@itemize
@item Gnulib is hosted at Savannah:
      @url{http://savannah.gnu.org/projects/gnulib}.  Get the sources
      through CVS from there.
@item The Gnulib home page:
      @url{http://www.gnu.org/software/gnulib/}.
@end itemize

@menu
* Comments::
* Header files::
* Quoting::
* ctime::
* inet_ntoa::
* gcd::
* Out of memory handling::
* Library version handling::
* Regular expressions::
* Windows sockets::
* Libtool and Windows::
@end menu


@node Comments
@section Comments

@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.


@node Header files
@section Header files

@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
file more than once, which might cause warnings.  The trick is to wrap
the content of the header file (say, @file{foo.h}) in a block, as in:

@example
#ifndef FOO_H
# define FOO_H
...
body of header file goes here
...
#endif /* FOO_H */
@end example

Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
style.  The C89 and C99 standards reserve all identifiers that begin with an
underscore and either an uppercase letter or another underscore, for
any use.  Thus, in theory, an application might not safely assume that
@code{_FOO_H} has not already been defined by a library.  On the other
hand, using @code{FOO_H} will likely lead the higher risk of
collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
macro function).  Your preference may depend on whether you consider
the header file under discussion as part of the application (which has
its own namespace for CPP symbols) or a supporting library (that
shouldn't interfere with the application's CPP symbol namespace).

@cindex C++ header files
@cindex Header files and C++
Adapting C header files for use in C++ applications can use another
CPP trick, as in:

@example
# ifdef __cplusplus
extern "C"
@{
# endif
...
body of header file goes here
...
# ifdef __cplusplus
@}
# endif
@end example

The idea here is that @code{__cplusplus} is defined only by C++
implementations, which will wrap the header file in an @samp{extern "C"}
block.  Again, whether to use this trick is a matter of taste and
style.  While the above can be seen as harmless, it could be argued
that the header file is written in C, and any C++ application using it
should explicitly use the @samp{extern "C"} block itself.  Your
preference might depend on whether you consider the API exported by
your header file as something available for C programs only, or for C
and C++ programs alike.

@subheading Include ordering

When writing a gnulib module, or even in general, a good way to order
the @samp{#include} directives is the following.

@itemize
@item First 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
arbitrary order.
@end itemize


@include quote.texi

@include ctime.texi

@include gcd.texi

@include inet_ntoa.texi


@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 improve code readability and robustness.

@cindex Aborting execution
For most applications, aborting the application with an error message
when the out of memory situation occur 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 support
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
declared as follows.

@example
extern void (*xalloc_fail_func) (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.


@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 Regular expressions
@section Regular expressions

Gnulib supports many different types of regular expressions; although
the underlying features are the same or identical, the syntax used
varies.  The descriptions given here for the different types are
generated automatically.

@include regexprops-generic.texi


@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 to (partial) getaddrinfo
implementation.

If you want to support Windows 2000, don't do anything, but be aware
that gnulib will use its own (partial) getaddrinfo implementation even
on Windows XP.  Currently the code does not attempt to determine if
the getaddrinfo function is available during runtime.

Todo: Make getaddrinfo.c open the WS2_32.DLL and check for the
getaddrinfo symbol and use it if present, otherwise fall back to our
own implementation.

@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 put:

@example
AC_LIBTOOL_WIN32_DLL
@end example

in your @file{configure.ac}.

The effect of this is that the names of the @code{OBJDUMP},
@code{DLLTOOL}, and @code{AS} tools are set up correct.

If you are building a library, you will also need to pass
@code{-no-undefined} to make sure Libtool produce a DLL for your
library.  From a @file{Makefile.am}:

@example
libgsasl_la_LDFLAGS += -no-undefined
@end example

@include gnulib-tool.texi


@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::  License for copying this manual.
@end menu

@include fdl.texi


@node Index
@unnumbered Index

@printindex cp

@bye