doc/gnulib.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @comment $Id: gnulib.texi,v 1.38 2007-04-27 19:58:15 haible Exp $
   3 @comment %**start of header
   4 @setfilename gnulib.info
   5 @settitle GNU Gnulib
   6 @syncodeindex fn cp
   7 @syncodeindex pg cp
   8 @comment %**end of header
   9
  10 @set UPDATED $Date: 2007-04-27 19:58:15 $
  11
  12 @copying
  13 This manual is for GNU Gnulib (updated @value{UPDATED}),
  14 which is a library of common routines intended to be shared at the
  15 source level.
  16
  17 Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
  18
  19 Permission is granted to copy, distribute and/or modify this document
  20 under the terms of the GNU Free Documentation License, Version 1.1 or
  21 any later version published by the Free Software Foundation; with no
  22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  23 Texts.  A copy of the license is included in the section entitled
  24 ``GNU Free Documentation License.''
  25 @end copying
  26
  27 @dircategory Software development
  28 @direntry
  29 * Gnulib: (gnulib).             Source files to share among distributions.
  30 @end direntry
  31
  32 @titlepage
  33 @title GNU Gnulib
  34 @subtitle updated @value{UPDATED}
  35 @author @email{bug-gnulib@@gnu.org}
  36 @page
  37 @vskip 0pt plus 1filll
  38 @insertcopying
  39 @end titlepage
  40
  41 @contents
  42
  43 @ifnottex
  44 @node Top
  45 @top GNU Gnulib
  46
  47 @insertcopying
  48 @end ifnottex
  49
  50 @menu
  51 * Introduction::
  52 * Invoking gnulib-tool::
  53 * Miscellaneous Notes::
  54 * Header File Substitutes::
  55 * Particular Modules::          Documentation of Individual Modules
  56 * Copying This Manual::
  57 * Index::
  58 @end menu
  59
  60 @node Introduction
  61 @chapter Introduction
  62
  63 Gnulib is a source code library. It provides basic functionalities to
  64 programs and libraries.  Currently (as of October 2006) more than 30
  65 packages make use of Gnulib.
  66
  67 Resources:
  68
  69 @itemize
  70 @item Gnulib is hosted at Savannah:
  71       @url{http://savannah.gnu.org/projects/gnulib}.  Get the sources
  72       through git or CVS from there.
  73 @item The Gnulib home page:
  74       @url{http://www.gnu.org/software/gnulib/}.
  75 @end itemize
  76
  77 @menu
  78 * Library vs. Reusable Code::
  79 * Portability and Application Code::
  80 * Modules::
  81 * Various Kinds of Modules::
  82 * Collaborative Development::
  83 * Copyright::
  84 * Steady Development::
  85 * Openness::
  86 @end menu
  87
  88 @include gnulib-intro.texi
  89
  90
  91 @include gnulib-tool.texi
  92
  93
  94 @node Miscellaneous Notes
  95 @chapter Miscellaneous Notes
  96
  97 @menu
  98 * Comments::
  99 * Header files::
 100 * Out of memory handling::
 101 * Library version handling::
 102 * Windows sockets::
 103 * Libtool and Windows::
 104 * License Texinfo sources::
 105 * Build robot for gnulib::
 106 @end menu
 107
 108
 109 @node Comments
 110 @section Comments
 111
 112 @cindex comments describing functions
 113 @cindex describing functions, locating
 114 Where to put comments describing functions: Because of risk of
 115 divergence, we prefer to keep most function describing comments in
 116 only one place: just above the actual function definition.  Some
 117 people prefer to put that documentation in the .h file.  In any case,
 118 it should appear in just one place unless you can ensure that the
 119 multiple copies will always remain identical.
 120
 121
 122 @node Header files
 123 @section Header files
 124
 125 @cindex double inclusion of header files
 126 @cindex header file include protection
 127 It is a tradition to use CPP tricks to avoid parsing the same header
 128 file more than once, which might cause warnings.  The trick is to wrap
 129 the content of the header file (say, @file{foo.h}) in a block, as in:
 130
 131 @example
 132 #ifndef FOO_H
 133 # define FOO_H
 134 ...
 135 body of header file goes here
 136 ...
 137 #endif /* FOO_H */
 138 @end example
 139
 140 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
 141 style.  The C89 and C99 standards reserve all identifiers that begin with an
 142 underscore and either an uppercase letter or another underscore, for
 143 any use.  Thus, in theory, an application might not safely assume that
 144 @code{_FOO_H} has not already been defined by a library.  On the other
 145 hand, using @code{FOO_H} will likely lead the higher risk of
 146 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
 147 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
 148 macro function).  Your preference may depend on whether you consider
 149 the header file under discussion as part of the application (which has
 150 its own namespace for CPP symbols) or a supporting library (that
 151 shouldn't interfere with the application's CPP symbol namespace).
 152
 153 @cindex C++ header files
 154 @cindex Header files and C++
 155 Adapting C header files for use in C++ applications can use another
 156 CPP trick, as in:
 157
 158 @example
 159 # ifdef __cplusplus
 160 extern "C"
 161 @{
 162 # endif
 163 ...
 164 body of header file goes here
 165 ...
 166 # ifdef __cplusplus
 167 @}
 168 # endif
 169 @end example
 170
 171 The idea here is that @code{__cplusplus} is defined only by C++
 172 implementations, which will wrap the header file in an @samp{extern "C"}
 173 block.  Again, whether to use this trick is a matter of taste and
 174 style.  While the above can be seen as harmless, it could be argued
 175 that the header file is written in C, and any C++ application using it
 176 should explicitly use the @samp{extern "C"} block itself.  Your
 177 preference might depend on whether you consider the API exported by
 178 your header file as something available for C programs only, or for C
 179 and C++ programs alike.
 180
 181 @subheading Include ordering
 182
 183 When writing a gnulib module, or even in general, a good way to order
 184 the @samp{#include} directives is the following.
 185
 186 @itemize
 187 @item First comes the #include "..." specifying the module being implemented.
 188 @item Then come all the #include <...> of system or system-replacement headers,
 189 in arbitrary order.
 190 @item Then come all the #include "..." of gnulib and private headers, in
 191 arbitrary order.
 192 @end itemize
 193
 194
 195 @node Out of memory handling
 196 @section Out of memory handling
 197
 198 @cindex Out of Memory handling
 199 @cindex Memory allocation failure
 200 The GSS API does not have a standard error code for the out of memory
 201 error condition.  Instead of adding a non-standard error code, this
 202 library has chosen to adopt a different strategy.  Out of memory
 203 handling happens in rare situations, but performing the out of memory
 204 error handling after almost all API function invocations pollute your
 205 source code and might make it harder to spot more serious problems.
 206 The strategy chosen improves code readability and robustness.
 207
 208 @cindex Aborting execution
 209 For most applications, aborting the application with an error message
 210 when the out of memory situation occurs is the best that can be wished
 211 for.  This is how the library behaves by default.
 212
 213 @vindex xalloc_fail_func
 214 However, we realize that some applications may not want to have the
 215 GSS library abort execution in any situation.  The GSS library supports
 216 a hook to let the application regain control and perform its own
 217 cleanups when an out of memory situation has occurred.  The application
 218 can define a function (having a @code{void} prototype, i.e., no return
 219 value and no parameters) and set the library variable
 220 @code{xalloc_fail_func} to that function.  The variable should be
 221 declared as follows.
 222
 223 @example
 224 extern void (*xalloc_fail_func) (void);
 225 @end example
 226
 227 The GSS library will invoke this function if an out of memory error
 228 occurs.  Note that after this the GSS library is in an undefined
 229 state, so you must unload or restart the application to continue call
 230 GSS library functions.  The hook is only intended to allow the
 231 application to log the situation in a special way.  Of course, care
 232 must be taken to not allocate more memory, as that will likely also
 233 fail.
 234
 235
 236 @node Library version handling
 237 @section Library version handling
 238
 239 The module @samp{check-version} can be useful when your gnulib
 240 application is a system library.  You will typically wrap the call to
 241 the @code{check_version} function through a library API, your library
 242 header file may contain:
 243
 244 @example
 245 #define STRINGPREP_VERSION "0.5.18"
 246 ...
 247   extern const char *stringprep_check_version (const char *req_version);
 248 @end example
 249
 250 To avoid ELF symbol collisions with other libraries that use the
 251 @samp{check-version} module, add to @file{config.h} through a
 252 AC_DEFINE something like:
 253
 254 @example
 255 AC_DEFINE(check_version, stringprep_check_version,
 256           [Rename check_version.])
 257 @end example
 258
 259 The @code{stringprep_check_version} function will thus be implemented
 260 by the @code{check_version} module.
 261
 262 There are two uses of the interface.  The first is a way to provide
 263 for applications to find out the version number of the library it
 264 uses.  The application may contain diagnostic code such as:
 265
 266 @example
 267   printf ("Stringprep version: header %s library %s",
 268           STRINGPREP_VERSION,
 269           stringprep_check_version (NULL));
 270 @end example
 271
 272 Separating the library and header file version can be useful when
 273 searching for version mismatch related problems.
 274
 275 The second uses is as a rudimentary test of proper library version, by
 276 making sure the application get a library version that is the same, or
 277 newer, than the header file used when building the application.  This
 278 doesn't catch all problems, libraries may change backwards incompatibly
 279 in later versions, but enable applications to require a certain
 280 minimum version before it may proceed.
 281
 282 Typical uses look like:
 283
 284 @example
 285        /* Check version of libgcrypt. */
 286        if (!gcry_check_version (GCRYPT_VERSION))
 287          die ("version mismatch\n");
 288 @end example
 289
 290
 291 @node Windows sockets
 292 @section Windows sockets
 293
 294 There are several issues when building applications that should work
 295 under Windows.  The most problematic part is for applications that use
 296 sockets.
 297
 298 Hopefully, we can add helpful notes to this section that will help you
 299 port your application to Windows using gnulib.
 300
 301 @subsection Getaddrinfo and WINVER
 302
 303 This was written for the getaddrinfo module, but may be applicable to
 304 other functions too.
 305
 306 The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
 307 XP.  The function declaration is present if @code{WINVER >= 0x0501}.
 308 Windows 2000 does not have getaddrinfo in its @file{WS2_32.dll}.
 309
 310 Thus, if you want to assume Windows XP or later, you can add
 311 AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo
 312 implementation.
 313
 314 If you want to support Windows 2000, don't do anything, but be aware
 315 that gnulib will use its own (partial) getaddrinfo implementation even
 316 on Windows XP.  Currently the code does not attempt to determine if
 317 the getaddrinfo function is available during runtime.
 318
 319 Todo: Make getaddrinfo.c open the WS2_32.DLL and check for the
 320 getaddrinfo symbol and use it if present, otherwise fall back to our
 321 own implementation.
 322
 323
 324 @node Libtool and Windows
 325 @section Libtool and Windows
 326
 327 If you want it to be possible to cross-compile your program to MinGW
 328 and you use Libtool, you need to put:
 329
 330 @example
 331 AC_LIBTOOL_WIN32_DLL
 332 @end example
 333
 334 in your @file{configure.ac}.  This sets the correct names for the
 335 @code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
 336
 337 If you are building a library, you will also need to pass
 338 @code{-no-undefined} to make sure Libtool produces a DLL for your
 339 library.  From a @file{Makefile.am}:
 340
 341 @example
 342 libgsasl_la_LDFLAGS += -no-undefined
 343 @end example
 344
 345
 346 @node License Texinfo sources
 347 @section License Texinfo sources
 348
 349 Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
 350 in Texinfo form.  (The master location is
 351 @url{http://www.gnu.org/licenses/}).  These Texinfo documents have
 352 various node names and structures built into them; for your manual,
 353 you might like to change these.  It's ok to do this, and a convenient
 354 way to do so is to use a context diff and the @option{--local-dir}
 355 option to @command{gnulib-tool}.
 356
 357 Of course the license texts themselves should not be changed at all.
 358
 359 @node Build robot for gnulib
 360 @section Build robot for gnulib
 361
 362 To simplify testing on a wide set of platforms, gnulib is built on
 363 many platforms every day and the results are uploaded to:
 364
 365 @url{http://autobuild.josefsson.org/gnulib/}
 366
 367 If you wish to help the gnulib development effort with build logs for
 368 your favorite platform, you may perform these steps:
 369
 370 @enumerate
 371
 372 @item Create gnulib directory
 373
 374 On a machine with recent automake, autoconf, m4 installed and with a
 375 gnulib git or cvs checkout (typically a Linux machine), use
 376
 377 @example
 378 gnulib-tool --create-megatestdir --with-tests --dir=..."
 379 @end example
 380
 381 Note: The created directory uses ca. 512 MB on disk.
 382
 383 @item Transfer gnulib directory
 384
 385 Transfer this directory to a build machine (HP-UX, Cygwin, or
 386 whatever).  Often it is easier to transfer one file, and this can be
 387 achieved by running, inside the directory the following commands:
 388
 389 @example
 390 ./configure
 391 make dist
 392 @end example
 393
 394 And then transferring the @file{dummy-0.tar.gz} file.
 395
 396 @item Build modules
 397
 398 On the build machine, run ./do-autobuild (or "nohup ./do-autobuild").
 399 It creates a directory 'logs/' with a log file for each module.
 400
 401 @item Submit build logs
 402
 403 Submit each log file to Simon's site, either through a
 404
 405 @example
 406 mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/`
 407 @end example
 408
 409 or through netcat
 410
 411 @example
 412 autobuild-submit logs/*
 413 @end example
 414
 415 @end enumerate
 416
 417 @node Header File Substitutes
 418 @chapter ISO C and POSIX Header File Substitutes
 419
 420 This chapter describes which header files specified by ISO C or POSIX are
 421 substituted by Gnulib, which portability pitfalls are fixed by Gnulib, and
 422 which (known) portability problems are not worked around by Gnulib.
 423
 424 @menu
 425 * aio.h::
 426 * arpa/inet.h::
 427 * assert.h::
 428 * complex.h::
 429 * cpio.h::
 430 * ctype.h::
 431 * dirent.h::
 432 * dlfcn.h::
 433 * errno.h::
 434 * fcntl.h::
 435 * fenv.h::
 436 * float.h::
 437 * fmtmsg.h::
 438 * fnmatch.h::
 439 * ftw.h::
 440 * glob.h::
 441 * grp.h::
 442 * iconv.h::
 443 * inttypes.h::
 444 * iso646.h::
 445 * langinfo.h::
 446 * libgen.h::
 447 * limits.h::
 448 * locale.h::
 449 * math.h::
 450 * monetary.h::
 451 * mqueue.h::
 452 * ndbm.h::
 453 * net/if.h::
 454 * netdb.h::
 455 * netinet/in.h::
 456 * netinet/tcp.h::
 457 * nl_types.h::
 458 * poll.h::
 459 * pthread.h::
 460 * pwd.h::
 461 * regex.h::
 462 * sched.h::
 463 * search.h::
 464 * semaphore.h::
 465 * setjmp.h::
 466 * signal.h::
 467 * spawn.h::
 468 * stdarg.h::
 469 * stdbool.h::
 470 * stddef.h::
 471 * stdint.h::
 472 * stdio.h::
 473 * stdlib.h::
 474 * string.h::
 475 * strings.h::
 476 * stropts.h::
 477 * sys/ipc.h::
 478 * sys/mman.h::
 479 * sys/msg.h::
 480 * sys/resource.h::
 481 * sys/select.h::
 482 * sys/sem.h::
 483 * sys/shm.h::
 484 * sys/socket.h::
 485 * sys/stat.h::
 486 * sys/statvfs.h::
 487 * sys/time.h::
 488 * sys/timeb.h::
 489 * sys/times.h::
 490 * sys/types.h::
 491 * sys/uio.h::
 492 * sys/un.h::
 493 * sys/utsname.h::
 494 * sys/wait.h::
 495 * syslog.h::
 496 * tar.h::
 497 * termios.h::
 498 * tgmath.h::
 499 * time.h::
 500 * trace.h::
 501 * ucontext.h::
 502 * ulimit.h::
 503 * unistd.h::
 504 * utime.h::
 505 * utmpx.h::
 506 * wchar.h::
 507 * wctype.h::
 508 * wordexp.h::
 509 @end menu
 510
 511 @include headers/aio.texi
 512 @include headers/arpa_inet.texi
 513 @include headers/assert.texi
 514 @include headers/complex.texi
 515 @include headers/cpio.texi
 516 @include headers/ctype.texi
 517 @include headers/dirent.texi
 518 @include headers/dlfcn.texi
 519 @include headers/errno.texi
 520 @include headers/fcntl.texi
 521 @include headers/fenv.texi
 522 @include headers/float.texi
 523 @include headers/fmtmsg.texi
 524 @include headers/fnmatch.texi
 525 @include headers/ftw.texi
 526 @include headers/glob.texi
 527 @include headers/grp.texi
 528 @include headers/iconv.texi
 529 @include headers/inttypes.texi
 530 @include headers/iso646.texi
 531 @include headers/langinfo.texi
 532 @include headers/libgen.texi
 533 @include headers/limits.texi
 534 @include headers/locale.texi
 535 @include headers/math.texi
 536 @include headers/monetary.texi
 537 @include headers/mqueue.texi
 538 @include headers/ndbm.texi
 539 @include headers/net_if.texi
 540 @include headers/netdb.texi
 541 @include headers/netinet_in.texi
 542 @include headers/netinet_tcp.texi
 543 @include headers/nl_types.texi
 544 @include headers/poll.texi
 545 @include headers/pthread.texi
 546 @include headers/pwd.texi
 547 @include headers/regex.texi
 548 @include headers/sched.texi
 549 @include headers/search.texi
 550 @include headers/semaphore.texi
 551 @include headers/setjmp.texi
 552 @include headers/signal.texi
 553 @include headers/spawn.texi
 554 @include headers/stdarg.texi
 555 @include headers/stdbool.texi
 556 @include headers/stddef.texi
 557 @include headers/stdint.texi
 558 @include headers/stdio.texi
 559 @include headers/stdlib.texi
 560 @include headers/string.texi
 561 @include headers/strings.texi
 562 @include headers/stropts.texi
 563 @include headers/sys_ipc.texi
 564 @include headers/sys_mman.texi
 565 @include headers/sys_msg.texi
 566 @include headers/sys_resource.texi
 567 @include headers/sys_select.texi
 568 @include headers/sys_sem.texi
 569 @include headers/sys_shm.texi
 570 @include headers/sys_socket.texi
 571 @include headers/sys_stat.texi
 572 @include headers/sys_statvfs.texi
 573 @include headers/sys_time.texi
 574 @include headers/sys_timeb.texi
 575 @include headers/sys_times.texi
 576 @include headers/sys_types.texi
 577 @include headers/sys_uio.texi
 578 @include headers/sys_un.texi
 579 @include headers/sys_utsname.texi
 580 @include headers/sys_wait.texi
 581 @include headers/syslog.texi
 582 @include headers/tar.texi
 583 @include headers/termios.texi
 584 @include headers/tgmath.texi
 585 @include headers/time.texi
 586 @include headers/trace.texi
 587 @include headers/ucontext.texi
 588 @include headers/ulimit.texi
 589 @include headers/unistd.texi
 590 @include headers/utime.texi
 591 @include headers/utmpx.texi
 592 @include headers/wchar.texi
 593 @include headers/wctype.texi
 594 @include headers/wordexp.texi
 595
 596 @node Particular Modules
 597 @chapter Particular Modules
 598
 599 @menu
 600 * Quoting::
 601 * ctime::
 602 * error and progname::
 603 * gcd::
 604 * inet_ntoa::
 605 * Regular expressions::
 606 * Supporting Relocation::
 607 @end menu
 608
 609 @include quote.texi
 610 @include error.texi
 611 @include ctime.texi
 612 @include gcd.texi
 613 @include inet_ntoa.texi
 614 @include relocatable-maint.texi
 615
 616 @node Regular expressions
 617 @section Regular expressions
 618
 619 Gnulib supports many different types of regular expressions; although
 620 the underlying features are the same or identical, the syntax used
 621 varies.  The descriptions given here for the different types are
 622 generated automatically.
 623
 624 @include regexprops-generic.texi
 625
 626
 627 @node Copying This Manual
 628 @appendix Copying This Manual
 629
 630 @menu
 631 * GNU Free Documentation License::  License for copying this manual.
 632 @end menu
 633
 634 @include fdl.texi
 635
 636
 637 @node Index
 638 @unnumbered Index
 639
 640 @printindex cp
 641
 642 @bye