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
8 @comment %**end of header
10 @set UPDATED $Date: 2007-04-27 19:58:15 $
13 This manual is for GNU Gnulib (updated @value{UPDATED}),
14 which is a library of common routines intended to be shared at the
17 Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
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.''
27 @dircategory Software development
29 * Gnulib: (gnulib). Source files to share among distributions.
34 @subtitle updated @value{UPDATED}
35 @author @email{bug-gnulib@@gnu.org}
37 @vskip 0pt plus 1filll
52 * Invoking gnulib-tool::
53 * Miscellaneous Notes::
54 * Header File Substitutes::
55 * Particular Modules:: Documentation of Individual Modules
56 * Copying This Manual::
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.
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/}.
78 * Library vs. Reusable Code::
79 * Portability and Application Code::
81 * Various Kinds of Modules::
82 * Collaborative Development::
84 * Steady Development::
88 @include gnulib-intro.texi
91 @include gnulib-tool.texi
94 @node Miscellaneous Notes
95 @chapter Miscellaneous Notes
100 * Out of memory handling::
101 * Library version handling::
103 * Libtool and Windows::
104 * License Texinfo sources::
105 * Build robot for gnulib::
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.
123 @section Header files
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:
135 body of header file goes here
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).
153 @cindex C++ header files
154 @cindex Header files and C++
155 Adapting C header files for use in C++ applications can use another
164 body of header file goes here
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.
181 @subheading Include ordering
183 When writing a gnulib module, or even in general, a good way to order
184 the @samp{#include} directives is the following.
187 @item First comes the #include "..." specifying the module being implemented.
188 @item Then come all the #include <...> of system or system-replacement headers,
190 @item Then come all the #include "..." of gnulib and private headers, in
195 @node Out of memory handling
196 @section Out of memory handling
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.
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.
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
224 extern void (*xalloc_fail_func) (void);
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
236 @node Library version handling
237 @section Library version handling
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:
245 #define STRINGPREP_VERSION "0.5.18"
247 extern const char *stringprep_check_version (const char *req_version);
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:
255 AC_DEFINE(check_version, stringprep_check_version,
256 [Rename check_version.])
259 The @code{stringprep_check_version} function will thus be implemented
260 by the @code{check_version} module.
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:
267 printf ("Stringprep version: header %s library %s",
269 stringprep_check_version (NULL));
272 Separating the library and header file version can be useful when
273 searching for version mismatch related problems.
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.
282 Typical uses look like:
285 /* Check version of libgcrypt. */
286 if (!gcry_check_version (GCRYPT_VERSION))
287 die ("version mismatch\n");
291 @node Windows sockets
292 @section Windows sockets
294 There are several issues when building applications that should work
295 under Windows. The most problematic part is for applications that use
298 Hopefully, we can add helpful notes to this section that will help you
299 port your application to Windows using gnulib.
301 @subsection Getaddrinfo and WINVER
303 This was written for the getaddrinfo module, but may be applicable to
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}.
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
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.
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
324 @node Libtool and Windows
325 @section Libtool and Windows
327 If you want it to be possible to cross-compile your program to MinGW
328 and you use Libtool, you need to put:
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.
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}:
342 libgsasl_la_LDFLAGS += -no-undefined
346 @node License Texinfo sources
347 @section License Texinfo sources
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}.
357 Of course the license texts themselves should not be changed at all.
359 @node Build robot for gnulib
360 @section Build robot for gnulib
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:
365 @url{http://autobuild.josefsson.org/gnulib/}
367 If you wish to help the gnulib development effort with build logs for
368 your favorite platform, you may perform these steps:
372 @item Create gnulib directory
374 On a machine with recent automake, autoconf, m4 installed and with a
375 gnulib git or cvs checkout (typically a Linux machine), use
378 gnulib-tool --create-megatestdir --with-tests --dir=..."
381 Note: The created directory uses ca. 512 MB on disk.
383 @item Transfer gnulib directory
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:
394 And then transferring the @file{dummy-0.tar.gz} file.
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.
401 @item Submit build logs
403 Submit each log file to Simon's site, either through a
406 mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/`
412 autobuild-submit logs/*
417 @node Header File Substitutes
418 @chapter ISO C and POSIX Header File Substitutes
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.
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
596 @node Particular Modules
597 @chapter Particular Modules
602 * error and progname::
605 * Regular expressions::
606 * Supporting Relocation::
613 @include inet_ntoa.texi
614 @include relocatable-maint.texi
616 @node Regular expressions
617 @section Regular expressions
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.
624 @include regexprops-generic.texi
627 @node Copying This Manual
628 @appendix Copying This Manual
631 * GNU Free Documentation License:: License for copying this manual.