X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgnulib.texi;h=6d62e8760b5e3682ade4a57a34d359e986b417d0;hb=4695d9d25dc1b35f8fb9777f9f1637cd161db84f;hp=cc826994def4ad7089ee821996156b217dbd45b1;hpb=f2e592bfe3e001764b5031e38e102dd914c84b5f;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index cc826994d..6d62e8760 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.14 2005-07-27 00:16:01 karl Exp $ +@comment $Id: gnulib.texi,v 1.23 2006-06-21 17:22:32 jas Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib @@ -7,14 +7,14 @@ @syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2005-07-27 00:16:01 $ +@set UPDATED $Date: 2006-06-21 17:22:32 $ @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 Free Software Foundation, Inc. +Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -85,9 +85,11 @@ Getting started: * Quoting:: * ctime:: * inet_ntoa:: +* gcd:: * Out of memory handling:: * Library version handling:: * Regular expressions:: +* Windows sockets:: @end menu @@ -177,79 +179,13 @@ arbitrary order. @end itemize -@node Quoting -@section Quoting +@include quote.texi -@cindex Quoting -@findex quote -@findex quotearg +@include ctime.texi -Gnulib provides @samp{quote} and @samp{quotearg} modules to help with -quoting text, such as file names, in messages to the user. Here's an -example of using @samp{quote}: +@include gcd.texi -@example -#include - ... - error (0, errno, _("cannot change owner of %s"), quote (fname)); -@end example - -This differs from - -@example - error (0, errno, _("cannot change owner of `%s'"), fname); -@end example - -@noindent in that @code{quote} escapes unusual characters in -@code{fname}, e.g., @samp{'} and control characters like @samp{\n}. - -@findex quote_n -However, a caveat: @code{quote} reuses the storage that it returns. -Hence if you need more than one thing quoted at the same time, you -need to use @code{quote_n}. - -@findex quotearg_alloc -Also, the quote module is not suited for multithreaded applications. -In that case, you have to use @code{quotearg_alloc}, defined in the -@samp{quotearg} module, which is decidedly less convenient. - - -@node ctime -@section ctime -@findex ctime - -The @code{ctime} function need not be reentrant, and consequently is -not required to be thread safe. Implementations of @code{ctime} -typically write the time stamp into static buffer. If two threads -call @code{ctime} at roughly the same time, you might end up with the -wrong date in one of the threads, or some undefined string. There is -a re-entrant interface @code{ctime_r}, that take a pre-allocated -buffer and length of the buffer, and return @code{NULL} on errors. -The input buffer should be at least 26 bytes in size. The output -string is locale-independent. However, years can have more than 4 -digits if @code{time_t} is sufficiently wide, so the length of the -required output buffer is not easy to determine. Increasing the -buffer size when @code{ctime_r} return @code{NULL} is not necessarily -sufficient. The @code{NULL} return value could mean some other error -condition, which will not go away by increasing the buffer size. - -A more flexible function is @code{strftime}. However, note that it is -locale dependent. - - -@node inet_ntoa -@section inet_ntoa -@findex inet_ntoa - -The @code{inet_ntoa} function need not be reentrant, and consequently -is not required to be thread safe. Implementations of -@code{inet_ntoa} typically write the time stamp into static buffer. -If two threads call @code{inet_ntoa} at roughly the same time, you -might end up with the wrong date in one of the threads, or some -undefined string. Further, @code{inet_ntoa} is specific for -@acronym{IPv4} addresses. - -A protocol independent function is @code{inet_ntop}. +@include inet_ntoa.texi @node Out of memory handling @@ -312,7 +248,8 @@ To avoid ELF symbol collisions with other libraries that use the AC_DEFINE something like: @example -AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.]) +AC_DEFINE(check_version, stringprep_check_version, + [Rename check_version.]) @end example The @code{stringprep_check_version} function will thus be implemented @@ -358,268 +295,39 @@ generated automatically. @include regexprops-generic.texi -@node Invoking gnulib-tool -@chapter Invoking gnulib-tool - -@pindex gnulib-tool -@cindex invoking @command{gnulib-tool} +@node Windows sockets +@section Windows sockets -Run @samp{gnulib-tool --help}, and use the source. -@command{gnulib-tool} is the way to import Gnulib modules. - -@menu -* Initial import:: First import of Gnulib modules. -* Importing updated files:: Subsequent imports. -* Finishing touches:: Simplifying imports. -@end menu +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. -@node Initial import -@section Initial import -@cindex initial import +@subsection Getaddrinfo and WINVER -Gnulib assumes your project uses Autoconf and Automake. Invoking -@samp{gnulib-tool --import} will copy source files, create a -@file{Makefile.am} to build them, and generate a @file{gnulib.m4} with -Autoconf M4 macro declarations used by @file{configure.ac}. +This was written for the getaddrinfo module, but may be applicable to +other functions too. -Our example will be a library that uses Autoconf, Automake and -Libtool. It calls @code{strdup}, and you wish to use gnulib to make -the package portable to C89 (which doesn't have @code{strdup}). - -@example -~/src/libfoo$ gnulib-tool --import strdup -Module list with included dependencies: - strdup -File list: - lib/strdup.c - lib/strdup.h - m4/onceonly_2_57.m4 - m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... -Finished. - -You may need to add #include directives for the following .h files. - #include "strdup.h" - -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. -~/src/libfoo$ -@end example +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}. -By default, the source code is copied into @file{lib/} and the M4 -macros in @file{m4/}. You can override these paths by using -@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by -adding @samp{gl_SOURCE_BASE(DIRECTORY)} and -@samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}. -Some modules also provide other files necessary -for building. These files are copied into the directory specified -by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the -@code{--aux-dir=DIRECTORY} option. If neither is specified, the -current directory is assumed. - -@code{gnulib-tool} can make symbolic links instead -of copying the source files. Use the @code{--symbolic} -(or @code{-s} for short) option to do this. - -@code{gnulib-tool} will overwrite any pre-existing files, in -particular @file{Makefile.am}. Unfortunately, separating the -generated @file{Makefile.am} content (for building the gnulib library) -into a separate file, say @file{gnulib.mk}, that could be included -by your handwritten @file{Makefile.am} is not possible, due to how -variable assignments are handled by Automake. - -Consequently, it can be a good idea to chose directories that are not -already used by your projects, to separate gnulib imported files from -your own files. This approach can also be useful if you want to avoid -conflicts between other tools (e.g., @code{getextize} that also copy -M4 files into your package. Simon Josefsson successfully uses a source -base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several -packages. - -A few manual steps are required to finish the initial import. - -First, you need to make sure Autoconf can find the macro definitions -in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your -top-level @file{Makefile.am} file, as in: +Thus, if you want to assume Windows XP or later, you can add +AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo +implementation. -@example -ACLOCAL_AMFLAGS = -I m4 -@end example - -Naturally, replace @file{m4} with the value from @code{--m4-base} or -@code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use: - -@example -ACLOCAL_AMFLAGS = -I gl/m4 -@end example - -You are now ready to call the M4 macros in @code{gnulib.m4} from -@file{configure.ac}. The macro @code{gl_EARLY} must be called as soon -as possible after verifying that the C compiler is working. -Typically, this is immediately after @code{AC_PROG_CC}, as in: - -@example -... -AC_PROG_CC -gl_EARLY -... -@end example - -The core part of the gnulib checks are done by the macro -@code{gl_INIT}. Place it further down in the file, typically where -you normally check for header files or functions. Or in a separate -section with other gnulib statements, such as @code{gl_SOURCE_BASE}. -For example: - -@example -... -# For gnulib. -gl_INIT -... -@end example - -@code{gl_INIT} will in turn call the macros related with the -gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} -or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or -@code{AM_FUNC_GETLINE} so there is no need to call those macros yourself -when you use the corresponding gnulib modules. - -You must also make sure that the gnulib library is built. Add the -@code{Makefile} in the gnulib source base directory to -@code{AC_CONFIG_FILES}, as in: - -@example -AC_CONFIG_FILES(... lib/Makefile ...) -@end example - -If your gnulib source base is @file{gl}, you would use: - -@example -AC_CONFIG_FILES(... gl/Makefile ...) -@end example - -You must also make sure that @code{make} work in the gnulib directory. -Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am -statement, as in: - -@example -SUBDIRS = lib -@end example - -or if you, more likely, already have a few entries in @code{SUBDIRS}, -you can add something like: - -@example -SUBDIRS += lib -@end example - -If you are using a gnulib source base of @code{gl}, you would use: - -@example -SUBDIRS += gl -@end example - -Finally, you have to add compiler and linker flags in the appropriate -source directories, so that you can make use -of the gnulib library. For example: - -@example -... -AM_CPPFLAGS = -I$(top_srcdir)/lib -... -LIBADD = lib/libgnu.a -... -@end example - -Don't forget to @code{#include} the various header files. In this -example, you would need to make sure that @samp{#include "strdup.h"} -is evaluated when compiling all source code files, that want to make -use of @code{strdup}. - -When an include file is provided by the gnulib -you shouldn't try to include the corresponding system header files -yourself but let the gnulib header file do it as the ordering -of the definition for some symbols may be significant. - -For example, to use the @code{time_r} gnulib module you should -use include header file provided by the gnulib, and so -@samp{#include "time_r.h"}, but you shouldn't explicitely -@samp{#include } as it is already done in @file{time_r.h} -before the redefinition of some symbols. - -@node Importing updated files -@section Importing updated files - -From time to time, you may want to invoke @samp{gnulib-tool --import} -to update the files in your package. Once you have set up your -package for gnulib, this step is quite simple. For example: - -@example -~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup -Module list with included dependencies: - strdup -File list: - lib/strdup.c - lib/strdup.h - m4/onceonly_2_57.m4 - m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... -Finished. - -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. -~/src/libfoo$ -@end example - -If you don't recall how you invoked the tool last time, the commands -used (and the operations it resulted in) are placed in comments within -the generated @file{Makefile.am} and @file{gnulib.m4}, as in: - -@example -... -# Invoked as: gnulib-tool --import strdup -# Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup -... -@end example - - -@node Finishing touches -@section Finishing touches - -Invoking @samp{gnulib-tool --import} with the proper parameters (e.g., -@samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup -snprintf getline minmax}) can be tedious. To simplify this procedure, -you may put the command line parameters in your @file{configure.ac}. -For example: - -@example -... -AC_PROG_CC -gl_EARLY -... -# For gnulib. -gl_SOURCE_BASE(gl) -gl_M4_BASE(gl/m4) -gl_LIB(libgl) -gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo) -gl_INIT -... -@end example +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. -This illustrate all macros defined in @file{gnulib.m4}. With the -above, importing new files are as simple as running @samp{gnulib-tool ---import} with no additional parameters. +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. -The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and -@code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB} -macro can be used if you wish to change the library name (by default -@file{libgnu.a} or @file{libgnu.la} if you use libtool). The -@code{gl_MODULES} macro is used to specify which modules to import. +@include gnulib-tool.texi @node Copying This Manual