regexprops, generated by findutils helper
[gnulib.git] / doc / gnulib.texi
1 \input texinfo   @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.14 2005-07-27 00:16:01 karl 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: 2005-07-27 00:16:01 $
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 Free Software Foundation, Inc.
18
19 @quotation
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.1 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
24 and with the Back-Cover Texts as in (a) below.  A copy of the
25 license is included in the section entitled ``GNU Free Documentation
26 License.''
27
28 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
29 this GNU Manual, like GNU software.  Copies published by the Free
30 Software Foundation raise funds for GNU development.''
31 @end quotation
32 @end copying
33
34 @dircategory Software development
35 @direntry
36 * Gnulib: (gnulib).             Source files to share among distributions.
37 @end direntry
38
39 @titlepage
40 @title GNU Gnulib
41 @subtitle updated @value{UPDATED}
42 @author @email{bug-gnulib@@gnu.org}
43 @page
44 @vskip 0pt plus 1filll
45 @insertcopying
46 @end titlepage
47
48 @contents
49
50 @ifnottex
51 @node Top
52 @top GNU Gnulib
53
54 @insertcopying
55 @end ifnottex
56
57 @menu
58 * Gnulib::
59 * Invoking gnulib-tool::
60 * Copying This Manual::
61 * Index::
62 @end menu
63
64
65 @node Gnulib
66 @chapter Gnulib
67
68 This manual contains some bare-bones documentation, but not much more.
69 It's mostly been a place to store notes until someone (you?)@ gets
70 around to writing a coherent manual.
71
72 Getting started:
73
74 @itemize
75 @item Gnulib is hosted at Savannah:
76       @url{http://savannah.gnu.org/projects/gnulib}.  Get the sources
77       through CVS from there.
78 @item The Gnulib home page:
79       @url{http://www.gnu.org/software/gnulib/}.
80 @end itemize
81
82 @menu
83 * Comments::
84 * Header files::
85 * Quoting::
86 * ctime::
87 * inet_ntoa::
88 * Out of memory handling::
89 * Library version handling::
90 * Regular expressions::
91 @end menu
92
93
94 @node Comments
95 @section Comments
96
97 @cindex comments describing functions
98 @cindex describing functions, locating
99 Where to put comments describing functions: Because of risk of
100 divergence, we prefer to keep most function describing comments in
101 only one place: just above the actual function definition.  Some
102 people prefer to put that documentation in the .h file.  In any case,
103 it should appear in just one place unless you can ensure that the
104 multiple copies will always remain identical.
105
106
107 @node Header files
108 @section Header files
109
110 @cindex double inclusion of header files
111 @cindex header file include protection
112 It is a tradition to use CPP tricks to avoid parsing the same header
113 file more than once, which might cause warnings.  The trick is to wrap
114 the content of the header file (say, @file{foo.h}) in a block, as in:
115
116 @example
117 #ifndef FOO_H
118 # define FOO_H
119 ...
120 body of header file goes here
121 ...
122 #endif /* FOO_H */
123 @end example
124
125 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
126 style.  The C89 and C99 standards reserve all identifiers that begin with an
127 underscore and either an uppercase letter or another underscore, for
128 any use.  Thus, in theory, an application might not safely assume that
129 @code{_FOO_H} has not already been defined by a library.  On the other
130 hand, using @code{FOO_H} will likely lead the higher risk of
131 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
132 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
133 macro function).  Your preference may depend on whether you consider
134 the header file under discussion as part of the application (which has
135 its own namespace for CPP symbols) or a supporting library (that
136 shouldn't interfere with the application's CPP symbol namespace).
137
138 @cindex C++ header files
139 @cindex Header files and C++
140 Adapting C header files for use in C++ applications can use another
141 CPP trick, as in:
142
143 @example
144 # ifdef __cplusplus
145 extern "C"
146 @{
147 # endif
148 ...
149 body of header file goes here
150 ...
151 # ifdef __cplusplus
152 @}
153 # endif
154 @end example
155
156 The idea here is that @code{__cplusplus} is defined only by C++
157 implementations, which will wrap the header file in an @samp{extern "C"}
158 block.  Again, whether to use this trick is a matter of taste and
159 style.  While the above can be seen as harmless, it could be argued
160 that the header file is written in C, and any C++ application using it
161 should explicitly use the @samp{extern "C"} block itself.  Your
162 preference might depend on whether you consider the API exported by
163 your header file as something available for C programs only, or for C
164 and C++ programs alike.
165
166 @subheading Include ordering
167
168 When writing a gnulib module, or even in general, a good way to order
169 the @samp{#include} directives is the following.
170
171 @itemize
172 @item First comes the #include "..." specifying the module being implemented.
173 @item Then come all the #include <...> of system or system-replacement headers,
174 in arbitrary order.
175 @item Then come all the #include "..." of gnulib and private headers, in
176 arbitrary order.
177 @end itemize
178
179
180 @node Quoting
181 @section Quoting
182
183 @cindex Quoting
184 @findex quote
185 @findex quotearg
186
187 Gnulib provides @samp{quote} and @samp{quotearg} modules to help with
188 quoting text, such as file names, in messages to the user.  Here's an
189 example of using @samp{quote}:
190
191 @example
192 #include <quote.h>
193  ...
194   error (0, errno, _("cannot change owner of %s"), quote (fname));
195 @end example
196
197 This differs from
198
199 @example
200   error (0, errno, _("cannot change owner of `%s'"), fname);
201 @end example
202
203 @noindent in that @code{quote} escapes unusual characters in
204 @code{fname}, e.g., @samp{'} and control characters like @samp{\n}.
205
206 @findex quote_n
207 However, a caveat: @code{quote} reuses the storage that it returns.
208 Hence if you need more than one thing quoted at the same time, you
209 need to use @code{quote_n}.
210
211 @findex quotearg_alloc
212 Also, the quote module is not suited for multithreaded applications.
213 In that case, you have to use @code{quotearg_alloc}, defined in the
214 @samp{quotearg} module, which is decidedly less convenient.
215
216
217 @node ctime
218 @section ctime
219 @findex ctime
220
221 The @code{ctime} function need not be reentrant, and consequently is
222 not required to be thread safe.  Implementations of @code{ctime}
223 typically write the time stamp into static buffer.  If two threads
224 call @code{ctime} at roughly the same time, you might end up with the
225 wrong date in one of the threads, or some undefined string.  There is
226 a re-entrant interface @code{ctime_r}, that take a pre-allocated
227 buffer and length of the buffer, and return @code{NULL} on errors.
228 The input buffer should be at least 26 bytes in size.  The output
229 string is locale-independent.  However, years can have more than 4
230 digits if @code{time_t} is sufficiently wide, so the length of the
231 required output buffer is not easy to determine.  Increasing the
232 buffer size when @code{ctime_r} return @code{NULL} is not necessarily
233 sufficient. The @code{NULL} return value could mean some other error
234 condition, which will not go away by increasing the buffer size.
235
236 A more flexible function is @code{strftime}.  However, note that it is
237 locale dependent.
238
239
240 @node inet_ntoa
241 @section inet_ntoa
242 @findex inet_ntoa
243
244 The @code{inet_ntoa} function need not be reentrant, and consequently
245 is not required to be thread safe.  Implementations of
246 @code{inet_ntoa} typically write the time stamp into static buffer.
247 If two threads call @code{inet_ntoa} at roughly the same time, you
248 might end up with the wrong date in one of the threads, or some
249 undefined string.  Further, @code{inet_ntoa} is specific for
250 @acronym{IPv4} addresses.
251
252 A protocol independent function is @code{inet_ntop}.
253
254
255 @node Out of memory handling
256 @section Out of memory handling
257
258 @cindex Out of Memory handling
259 @cindex Memory allocation failure
260 The GSS API does not have a standard error code for the out of memory
261 error condition.  Instead of adding a non-standard error code, this
262 library has chosen to adopt a different strategy.  Out of memory
263 handling happens in rare situations, but performing the out of memory
264 error handling after almost all API function invocations pollute your
265 source code and might make it harder to spot more serious problems.
266 The strategy chosen improve code readability and robustness.
267
268 @cindex Aborting execution
269 For most applications, aborting the application with an error message
270 when the out of memory situation occur is the best that can be wished
271 for.  This is how the library behaves by default.
272
273 @vindex xalloc_fail_func
274 However, we realize that some applications may not want to have the
275 GSS library abort execution in any situation.  The GSS library support
276 a hook to let the application regain control and perform its own
277 cleanups when an out of memory situation has occured.  The application
278 can define a function (having a @code{void} prototype, i.e., no return
279 value and no parameters) and set the library variable
280 @code{xalloc_fail_func} to that function.  The variable should be
281 declared as follows.
282
283 @example
284 extern void (*xalloc_fail_func) (void);
285 @end example
286
287 The GSS library will invoke this function if an out of memory error
288 occurs.  Note that after this the GSS library is in an undefined
289 state, so you must unload or restart the application to continue call
290 GSS library functions.  The hook is only intended to allow the
291 application to log the situation in a special way.  Of course, care
292 must be taken to not allocate more memory, as that will likely also
293 fail.
294
295
296 @node Library version handling
297 @section Library version handling
298
299 The module @samp{check-version} can be useful when your gnulib
300 application is a system library.  You will typically wrap the call to
301 the @code{check_version} function through a library API, your library
302 header file may contain:
303
304 @example
305 #define STRINGPREP_VERSION "0.5.18"
306 ...
307   extern const char *stringprep_check_version (const char *req_version);
308 @end example
309
310 To avoid ELF symbol collisions with other libraries that use the
311 @samp{check-version} module, add to @file{config.h} through a
312 AC_DEFINE something like:
313
314 @example
315 AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])
316 @end example
317
318 The @code{stringprep_check_version} function will thus be implemented
319 by the @code{check_version} module.
320
321 There are two uses of the interface.  The first is a way to provide
322 for applications to find out the version number of the library it
323 uses.  The application may contain diagnostic code such as:
324
325 @example
326   printf ("Stringprep version: header %s library %s",
327           STRINGPREP_VERSION,
328           stringprep_check_version (NULL));
329 @end example
330
331 Separating the library and header file version can be useful when
332 searching for version mismatch related problems.
333
334 The second uses is as a rudimentary test of proper library version, by
335 making sure the application get a library version that is the same, or
336 newer, than the header file used when building the application.  This
337 doesn't catch all problems, libraries may change backwards incompatibly
338 in later versions, but enable applications to require a certain
339 minimum version before it may proceed.
340
341 Typical uses look like:
342
343 @example
344        /* Check version of libgcrypt. */
345        if (!gcry_check_version (GCRYPT_VERSION))
346          die ("version mismatch\n");
347 @end example
348
349
350 @node Regular expressions
351 @section Regular expressions
352
353 Gnulib supports many different types of regular expressions; although
354 the underlying features are the same or identical, the syntax used
355 varies.  The descriptions given here for the different types are
356 generated automatically.
357
358 @include regexprops-generic.texi
359
360
361 @node Invoking gnulib-tool
362 @chapter Invoking gnulib-tool
363
364 @pindex gnulib-tool
365 @cindex invoking @command{gnulib-tool}
366
367 Run @samp{gnulib-tool --help}, and use the source.
368 @command{gnulib-tool} is the way to import Gnulib modules.
369
370 @menu
371 * Initial import::              First import of Gnulib modules.
372 * Importing updated files::     Subsequent imports.
373 * Finishing touches::           Simplifying imports.
374 @end menu
375
376
377 @node Initial import
378 @section Initial import
379 @cindex initial import
380
381 Gnulib assumes your project uses Autoconf and Automake.  Invoking
382 @samp{gnulib-tool --import} will copy source files, create a
383 @file{Makefile.am} to build them, and generate a @file{gnulib.m4} with
384 Autoconf M4 macro declarations used by @file{configure.ac}.
385
386 Our example will be a library that uses Autoconf, Automake and
387 Libtool.  It calls @code{strdup}, and you wish to use gnulib to make
388 the package portable to C89 (which doesn't have @code{strdup}).
389
390 @example
391 ~/src/libfoo$ gnulib-tool --import strdup
392 Module list with included dependencies:
393   strdup
394 File list:
395   lib/strdup.c
396   lib/strdup.h
397   m4/onceonly_2_57.m4
398   m4/strdup.m4
399 Creating ./lib/Makefile.am...
400 Creating ./m4/gnulib.m4...
401 Finished.
402
403 You may need to add #include directives for the following .h files.
404   #include "strdup.h"
405
406 Don't forget to add "lib/Makefile"
407 to AC_CONFIG_FILES in "./configure.ac" and to mention
408 "lib" in SUBDIRS in some Makefile.am.
409 ~/src/libfoo$
410 @end example
411
412 By default, the source code is copied into @file{lib/} and the M4
413 macros in @file{m4/}.  You can override these paths by using
414 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
415 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
416 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
417 Some modules also provide other files necessary
418 for building. These files are copied into the directory specified
419 by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the
420 @code{--aux-dir=DIRECTORY} option. If neither is specified, the
421 current directory is assumed.
422
423 @code{gnulib-tool} can make symbolic links instead
424 of copying the source files. Use the @code{--symbolic}
425 (or @code{-s} for short) option to do this.
426
427 @code{gnulib-tool} will overwrite any pre-existing files, in
428 particular @file{Makefile.am}.  Unfortunately, separating the
429 generated @file{Makefile.am} content (for building the gnulib library)
430 into a separate file, say @file{gnulib.mk}, that could be included
431 by your handwritten @file{Makefile.am} is not possible, due to how
432 variable assignments are handled by Automake.
433
434 Consequently, it can be a good idea to chose directories that are not
435 already used by your projects, to separate gnulib imported files from
436 your own files.  This approach can also be useful if you want to avoid
437 conflicts between other tools (e.g., @code{getextize} that also copy
438 M4 files into your package.  Simon Josefsson successfully uses a source
439 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
440 packages.
441
442 A few manual steps are required to finish the initial import.
443
444 First, you need to make sure Autoconf can find the macro definitions
445 in @file{gnulib.m4}.  Use the @code{ACLOCAL_AMFLAGS} specifier in your
446 top-level @file{Makefile.am} file, as in:
447
448 @example
449 ACLOCAL_AMFLAGS = -I m4
450 @end example
451
452 Naturally, replace @file{m4} with the value from @code{--m4-base} or
453 @code{gl_M4_BASE}.  If the M4 base is @file{gl/m4} you would use:
454
455 @example
456 ACLOCAL_AMFLAGS = -I gl/m4
457 @end example
458
459 You are now ready to call the M4 macros in @code{gnulib.m4} from
460 @file{configure.ac}.  The macro @code{gl_EARLY} must be called as soon
461 as possible after verifying that the C compiler is working.
462 Typically, this is immediately after @code{AC_PROG_CC}, as in:
463
464 @example
465 ...
466 AC_PROG_CC
467 gl_EARLY
468 ...
469 @end example
470
471 The core part of the gnulib checks are done by the macro
472 @code{gl_INIT}.  Place it further down in the file, typically where
473 you normally check for header files or functions.  Or in a separate
474 section with other gnulib statements, such as @code{gl_SOURCE_BASE}.
475 For example:
476
477 @example
478 ...
479 # For gnulib.
480 gl_INIT
481 ...
482 @end example
483
484 @code{gl_INIT} will in turn call the macros related with the 
485 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
486 or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or 
487 @code{AM_FUNC_GETLINE} so there is no need to call those macros yourself
488 when you use the corresponding gnulib modules.
489
490 You must also make sure that the gnulib library is built.  Add the
491 @code{Makefile} in the gnulib source base directory to
492 @code{AC_CONFIG_FILES}, as in:
493
494 @example
495 AC_CONFIG_FILES(... lib/Makefile ...)
496 @end example
497
498 If your gnulib source base is @file{gl}, you would use:
499
500 @example
501 AC_CONFIG_FILES(... gl/Makefile ...)
502 @end example
503
504 You must also make sure that @code{make} work in the gnulib directory.
505 Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am
506 statement, as in:
507
508 @example
509 SUBDIRS = lib
510 @end example
511
512 or if you, more likely, already have a few entries in @code{SUBDIRS},
513 you can add something like:
514
515 @example
516 SUBDIRS += lib
517 @end example
518
519 If you are using a gnulib source base of @code{gl}, you would use:
520
521 @example
522 SUBDIRS += gl
523 @end example
524
525 Finally, you have to add compiler and linker flags in the appropriate
526 source directories, so that you can make use
527 of the gnulib library.  For example:
528
529 @example
530 ...
531 AM_CPPFLAGS = -I$(top_srcdir)/lib
532 ...
533 LIBADD = lib/libgnu.a
534 ...
535 @end example
536
537 Don't forget to @code{#include} the various header files.  In this
538 example, you would need to make sure that @samp{#include "strdup.h"}
539 is evaluated when compiling all source code files, that want to make
540 use of @code{strdup}. 
541
542 When an include file is provided by the gnulib
543 you shouldn't try to include the corresponding system header files 
544 yourself but let the gnulib header file do it as the ordering
545 of the definition for some symbols may be significant.
546
547 For example, to use the @code{time_r} gnulib module you should
548 use include header file provided by the gnulib, and so
549 @samp{#include "time_r.h"}, but you shouldn't explicitely
550 @samp{#include <time.h>} as it is already done in @file{time_r.h}
551 before the redefinition of some symbols.
552
553 @node Importing updated files
554 @section Importing updated files
555
556 From time to time, you may want to invoke @samp{gnulib-tool --import}
557 to update the files in your package.  Once you have set up your
558 package for gnulib, this step is quite simple.  For example:
559
560 @example
561 ~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup
562 Module list with included dependencies:
563   strdup
564 File list:
565   lib/strdup.c
566   lib/strdup.h
567   m4/onceonly_2_57.m4
568   m4/strdup.m4
569 Creating ./lib/Makefile.am...
570 Creating ./m4/gnulib.m4...
571 Finished.
572
573 Don't forget to add "lib/Makefile"
574 to AC_CONFIG_FILES in "./configure.ac" and to mention
575 "lib" in SUBDIRS in some Makefile.am.
576 ~/src/libfoo$
577 @end example
578
579 If you don't recall how you invoked the tool last time, the commands
580 used (and the operations it resulted in) are placed in comments within
581 the generated @file{Makefile.am} and @file{gnulib.m4}, as in:
582
583 @example
584 ...
585 # Invoked as: gnulib-tool --import strdup
586 # Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup
587 ...
588 @end example
589
590
591 @node Finishing touches
592 @section Finishing touches
593
594 Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
595 @samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup
596 snprintf getline minmax}) can be tedious.  To simplify this procedure,
597 you may put the command line parameters in your @file{configure.ac}.
598 For example:
599
600 @example
601 ...
602 AC_PROG_CC
603 gl_EARLY
604 ...
605 # For gnulib.
606 gl_SOURCE_BASE(gl)
607 gl_M4_BASE(gl/m4)
608 gl_LIB(libgl)
609 gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
610 gl_INIT
611 ...
612 @end example
613
614 This illustrate all macros defined in @file{gnulib.m4}.  With the
615 above, importing new files are as simple as running @samp{gnulib-tool
616 --import} with no additional parameters.
617
618 The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and
619 @code{gl_M4_BASE} have been discussed earlier.  The @code{gl_LIB}
620 macro can be used if you wish to change the library name (by default
621 @file{libgnu.a} or @file{libgnu.la} if you use libtool).  The
622 @code{gl_MODULES} macro is used to specify which modules to import.
623
624
625 @node Copying This Manual
626 @appendix Copying This Manual
627
628 @menu
629 * GNU Free Documentation License::  License for copying this manual.
630 @end menu
631
632 @include fdl.texi
633
634
635 @node Index
636 @unnumbered Index
637
638 @printindex cp
639
640 @bye