X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;ds=inline;f=doc%2Fgnulib.texi;h=fdab409ef64a9c2c77e57f17005013f7c13809a3;hb=c35f7836a95cd9875af1ff8a59a33a8e19f4d873;hp=203b074141195f0cef13300d94cfcca339d56c32;hpb=62810d7234f56ec733a28840a50f86757875cf65;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 203b07414..fdab409ef 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,20 +1,24 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.39 2007-05-01 15:14:20 haible Exp $ +@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 @syncodeindex fn cp @syncodeindex pg cp +@ifclear texi2html +@firstparagraphindent insert +@end ifclear @comment %**end of header -@set UPDATED $Date: 2007-05-01 15:14:20 $ +@set UPDATED $Date: 2007-09-09 13:20:45 $ @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, 2007 Free Software Foundation, Inc. +Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 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.1 or @@ -51,10 +55,12 @@ Texts. A copy of the license is included in the section entitled * Introduction:: * Invoking gnulib-tool:: * Miscellaneous Notes:: -* Header File Substitutes:: -* Function Substitutes:: -* Particular Modules:: Documentation of Individual Modules -* Copying This Manual:: +* POSIX Substitutes Library:: Building as a separate substitutes library. +* Header File Substitutes:: Overriding system headers. +* Function Substitutes:: Replacing system functions. +* Glibc Header File Substitutes:: Overriding system headers. +* Particular Modules:: Documentation of individual modules. +* GNU Free Documentation License:: Copying and sharing this manual. * Index:: @end menu @@ -70,13 +76,13 @@ Resources: @itemize @item Gnulib is hosted at Savannah: @url{http://savannah.gnu.org/projects/gnulib}. Get the sources - through git or CVS from there. + through Git or CVS from there. @item The Gnulib home page: @url{http://www.gnu.org/software/gnulib/}. @end itemize @menu -* Library vs. Reusable Code:: +* Library vs Reusable Code:: * Portability and Application Code:: * Modules:: * Various Kinds of Modules:: @@ -349,14 +355,17 @@ libgsasl_la_LDFLAGS += -no-undefined 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 have -various node names and structures built into them; for your manual, -you might like to change these. It's ok to do this, and a convenient -way to do so is to use a context diff and the @option{--local-dir} -option to @command{gnulib-tool}. +@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. + @node Build robot for gnulib @section Build robot for gnulib @@ -415,6 +424,35 @@ autobuild-submit logs/* @end enumerate +@node POSIX Substitutes Library +@chapter Building the ISO C and POSIX Substitutes + +This section shows a radically different way to use Gnulib. + +You can extract the ISO C / POSIX substitutes part of gnulib by running +the command +@smallexample +gnulib-tool --create-testdir --source-base=lib \ + --dir=/tmp/posixlib `posix-modules` +@end smallexample + +@noindent +The command @samp{posix-modules} is found in the same directory as +@code{gnulib-tool}. + +The resulting directory can be built on a particular platform, +independently of the program being ported. Then you can configure and +build any program, by setting @code{CPPFLAGS} and @code{LDFLAGS} at +configure time accordingly: set @code{CPPFLAGS="-I.../posixlib/lib"}, plus +any essential type definitions and flags that you find in +@code{.../posixlib/config.h}, and set +@code{LDFLAGS=".../posixlib/lib/libgnu.a"}. + +This way of using Gnulib is useful when you don't want to modify the program's +source code, or when the program uses a mix between C and C++ sources +(requiring separate builds of the @code{posixlib} for the C compiler and +for the C++ compiler). + @node Header File Substitutes @chapter ISO C and POSIX Header File Substitutes @@ -602,6 +640,15 @@ ISO C or POSIX are substituted by Gnulib, which portability pitfalls are fixed by Gnulib, and which (known) portability problems are not worked around by Gnulib. +The notation ``Gnulib module: ---'' means that Gnulib does not provide a +module providing a substitute for the function. When the list +``Portability problems not fixed by Gnulib'' is empty, such a module is +not needed: No portability problems are known. Otherwise, it indicates +that such a module would be useful but is not available: Noone so far +found this function important enough to contribute a substitute for it. +If you need this particular function, you may write to +@code{}. + @menu * FD_CLR:: * FD_ISSET:: @@ -926,6 +973,7 @@ by Gnulib. * getcontext:: * getcwd:: * getdate:: +* getdelim:: * getegid:: * getenv:: * geteuid:: @@ -942,6 +990,7 @@ by Gnulib. * gethostid:: * gethostname:: * getitimer:: +* getline:: * getlogin:: * getlogin_r:: * getmsg:: @@ -1127,6 +1176,7 @@ by Gnulib. * memchr:: * memcmp:: * memcpy:: +* memmem:: * memmove:: * memset:: * mkdir:: @@ -1543,7 +1593,9 @@ by Gnulib. * sscanf:: * stat:: * statvfs:: +* stderr:: * stdin:: +* stdout:: * strcasecmp:: * strcat:: * strchr:: @@ -1723,7 +1775,7 @@ by Gnulib. @include functions/FD_ISSET.texi @include functions/FD_SET.texi @include functions/FD_ZERO.texi -@include functions/_Exit.texi +@include functions/_Exit_C99.texi @include functions/_exit.texi @include functions/_longjmp.texi @include functions/_setjmp.texi @@ -2042,6 +2094,7 @@ by Gnulib. @include functions/getcontext.texi @include functions/getcwd.texi @include functions/getdate.texi +@include functions/getdelim.texi @include functions/getegid.texi @include functions/getenv.texi @include functions/geteuid.texi @@ -2058,6 +2111,7 @@ by Gnulib. @include functions/gethostid.texi @include functions/gethostname.texi @include functions/getitimer.texi +@include functions/getline.texi @include functions/getlogin.texi @include functions/getlogin_r.texi @include functions/getmsg.texi @@ -2659,7 +2713,9 @@ by Gnulib. @include functions/sscanf.texi @include functions/stat.texi @include functions/statvfs.texi +@include functions/stderr.texi @include functions/stdin.texi +@include functions/stdout.texi @include functions/strcasecmp.texi @include functions/strcat.texi @include functions/strchr.texi @@ -2834,10 +2890,85 @@ by Gnulib. @include functions/y1.texi @include functions/yn.texi +@node Glibc Header File Substitutes +@chapter Glibc Header File Substitutes + +This chapter describes which header files contained in GNU libc but not +specified by ISO C or POSIX are substituted by Gnulib, which portability +pitfalls are fixed by Gnulib, and which (known) portability problems are +not worked around by Gnulib. + +@menu +* a.out.h:: +* aliases.h:: +* alloca.h:: +* ar.h:: +* argp.h:: +* argz.h:: +* byteswap.h:: +* crypt.h:: +* endian.h:: +* envz.h:: +* err.h:: +* error.h:: +* execinfo.h:: +* fpu_control.h:: +* fstab.h:: +* fts.h:: +* getopt.h:: +* ieee754.h:: +* ifaddrs.h:: +* libintl.h:: +* mcheck.h:: +* mntent.h:: +* obstack.h:: +* paths.h:: +* printf.h:: +* pty.h:: +* resolv.h:: +* shadow.h:: +* sysexits.h:: +* ttyent.h:: +@end menu + +@include glibc-headers/a.out.texi +@include glibc-headers/aliases.texi +@include glibc-headers/alloca.texi +@include glibc-headers/ar.texi +@include glibc-headers/argp.texi +@include glibc-headers/argz.texi +@include glibc-headers/byteswap.texi +@include glibc-headers/crypt.texi +@include glibc-headers/endian.texi +@include glibc-headers/envz.texi +@include glibc-headers/err.texi +@include glibc-headers/error.texi +@include glibc-headers/execinfo.texi +@include glibc-headers/fpu_control.texi +@include glibc-headers/fstab.texi +@include glibc-headers/fts.texi +@include glibc-headers/getopt.texi +@include glibc-headers/ieee754.texi +@include glibc-headers/ifaddrs.texi +@include glibc-headers/libintl.texi +@include glibc-headers/mcheck.texi +@include glibc-headers/mntent.texi +@include glibc-headers/obstack.texi +@include glibc-headers/paths.texi +@include glibc-headers/printf.texi +@include glibc-headers/pty.texi +@include glibc-headers/resolv.texi +@include glibc-headers/shadow.texi +@include glibc-headers/sysexits.texi +@include glibc-headers/ttyent.texi + @node Particular Modules @chapter Particular Modules @menu +* alloca:: +* alloca-opt:: +* String Functions in C Locale:: * Quoting:: * error and progname:: * gcd:: @@ -2845,6 +2976,68 @@ by Gnulib. * Supporting Relocation:: @end menu +@node alloca +@section alloca +@findex alloca +@include alloca.texi + +@node alloca-opt +@section alloca-opt +@findex alloca +@include alloca-opt.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 quote.texi @include error.texi @include gcd.texi @@ -2861,12 +3054,8 @@ generated automatically. @include regexprops-generic.texi -@node Copying This Manual -@appendix Copying This Manual - -@menu -* GNU Free Documentation License:: License for copying this manual. -@end menu +@node GNU Free Documentation License +@appendix GNU Free Documentation License @include fdl.texi @@ -2877,3 +3066,8 @@ generated automatically. @printindex cp @bye + +@c Local Variables: +@c indent-tabs-mode: nil +@c whitespace-check-buffer-indent: nil +@c End: