1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.34 2007-03-19 20:30:25 blp Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2007-03-19 20:30:25 $
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 * Particular Modules:: Documentation of Individual Modules
55 * Copying This Manual::
62 Gnulib is a source code library. It provides basic functionalities to
63 programs and libraries. Currently (as of October 2006) more than 30
64 packages make use of Gnulib.
69 @item Gnulib is hosted at Savannah:
70 @url{http://savannah.gnu.org/projects/gnulib}. Get the sources
71 through CVS from there.
72 @item The Gnulib home page:
73 @url{http://www.gnu.org/software/gnulib/}.
77 * Library vs. Reusable Code::
78 * Portability and Application Code::
80 * Various Kinds of Modules::
81 * Collaborative Development::
83 * Steady Development::
87 @include gnulib-intro.texi
90 @include gnulib-tool.texi
93 @node Miscellaneous Notes
94 @chapter Miscellaneous Notes
99 * Out of memory handling::
100 * Library version handling::
102 * Libtool and Windows::
103 * License Texinfo sources::
104 * Build robot for gnulib::
111 @cindex comments describing functions
112 @cindex describing functions, locating
113 Where to put comments describing functions: Because of risk of
114 divergence, we prefer to keep most function describing comments in
115 only one place: just above the actual function definition. Some
116 people prefer to put that documentation in the .h file. In any case,
117 it should appear in just one place unless you can ensure that the
118 multiple copies will always remain identical.
122 @section Header files
124 @cindex double inclusion of header files
125 @cindex header file include protection
126 It is a tradition to use CPP tricks to avoid parsing the same header
127 file more than once, which might cause warnings. The trick is to wrap
128 the content of the header file (say, @file{foo.h}) in a block, as in:
134 body of header file goes here
139 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
140 style. The C89 and C99 standards reserve all identifiers that begin with an
141 underscore and either an uppercase letter or another underscore, for
142 any use. Thus, in theory, an application might not safely assume that
143 @code{_FOO_H} has not already been defined by a library. On the other
144 hand, using @code{FOO_H} will likely lead the higher risk of
145 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
146 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
147 macro function). Your preference may depend on whether you consider
148 the header file under discussion as part of the application (which has
149 its own namespace for CPP symbols) or a supporting library (that
150 shouldn't interfere with the application's CPP symbol namespace).
152 @cindex C++ header files
153 @cindex Header files and C++
154 Adapting C header files for use in C++ applications can use another
163 body of header file goes here
170 The idea here is that @code{__cplusplus} is defined only by C++
171 implementations, which will wrap the header file in an @samp{extern "C"}
172 block. Again, whether to use this trick is a matter of taste and
173 style. While the above can be seen as harmless, it could be argued
174 that the header file is written in C, and any C++ application using it
175 should explicitly use the @samp{extern "C"} block itself. Your
176 preference might depend on whether you consider the API exported by
177 your header file as something available for C programs only, or for C
178 and C++ programs alike.
180 @subheading Include ordering
182 When writing a gnulib module, or even in general, a good way to order
183 the @samp{#include} directives is the following.
186 @item First comes the #include "..." specifying the module being implemented.
187 @item Then come all the #include <...> of system or system-replacement headers,
189 @item Then come all the #include "..." of gnulib and private headers, in
194 @node Out of memory handling
195 @section Out of memory handling
197 @cindex Out of Memory handling
198 @cindex Memory allocation failure
199 The GSS API does not have a standard error code for the out of memory
200 error condition. Instead of adding a non-standard error code, this
201 library has chosen to adopt a different strategy. Out of memory
202 handling happens in rare situations, but performing the out of memory
203 error handling after almost all API function invocations pollute your
204 source code and might make it harder to spot more serious problems.
205 The strategy chosen improves code readability and robustness.
207 @cindex Aborting execution
208 For most applications, aborting the application with an error message
209 when the out of memory situation occurs is the best that can be wished
210 for. This is how the library behaves by default.
212 @vindex xalloc_fail_func
213 However, we realize that some applications may not want to have the
214 GSS library abort execution in any situation. The GSS library supports
215 a hook to let the application regain control and perform its own
216 cleanups when an out of memory situation has occurred. The application
217 can define a function (having a @code{void} prototype, i.e., no return
218 value and no parameters) and set the library variable
219 @code{xalloc_fail_func} to that function. The variable should be
223 extern void (*xalloc_fail_func) (void);
226 The GSS library will invoke this function if an out of memory error
227 occurs. Note that after this the GSS library is in an undefined
228 state, so you must unload or restart the application to continue call
229 GSS library functions. The hook is only intended to allow the
230 application to log the situation in a special way. Of course, care
231 must be taken to not allocate more memory, as that will likely also
235 @node Library version handling
236 @section Library version handling
238 The module @samp{check-version} can be useful when your gnulib
239 application is a system library. You will typically wrap the call to
240 the @code{check_version} function through a library API, your library
241 header file may contain:
244 #define STRINGPREP_VERSION "0.5.18"
246 extern const char *stringprep_check_version (const char *req_version);
249 To avoid ELF symbol collisions with other libraries that use the
250 @samp{check-version} module, add to @file{config.h} through a
251 AC_DEFINE something like:
254 AC_DEFINE(check_version, stringprep_check_version,
255 [Rename check_version.])
258 The @code{stringprep_check_version} function will thus be implemented
259 by the @code{check_version} module.
261 There are two uses of the interface. The first is a way to provide
262 for applications to find out the version number of the library it
263 uses. The application may contain diagnostic code such as:
266 printf ("Stringprep version: header %s library %s",
268 stringprep_check_version (NULL));
271 Separating the library and header file version can be useful when
272 searching for version mismatch related problems.
274 The second uses is as a rudimentary test of proper library version, by
275 making sure the application get a library version that is the same, or
276 newer, than the header file used when building the application. This
277 doesn't catch all problems, libraries may change backwards incompatibly
278 in later versions, but enable applications to require a certain
279 minimum version before it may proceed.
281 Typical uses look like:
284 /* Check version of libgcrypt. */
285 if (!gcry_check_version (GCRYPT_VERSION))
286 die ("version mismatch\n");
290 @node Windows sockets
291 @section Windows sockets
293 There are several issues when building applications that should work
294 under Windows. The most problematic part is for applications that use
297 Hopefully, we can add helpful notes to this section that will help you
298 port your application to Windows using gnulib.
300 @subsection Getaddrinfo and WINVER
302 This was written for the getaddrinfo module, but may be applicable to
305 The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
306 XP. The function declaration is present if @code{WINVER >= 0x0501}.
307 Windows 2000 does not have getaddrinfo in its @file{WS2_32.dll}.
309 Thus, if you want to assume Windows XP or later, you can add
310 AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo
313 If you want to support Windows 2000, don't do anything, but be aware
314 that gnulib will use its own (partial) getaddrinfo implementation even
315 on Windows XP. Currently the code does not attempt to determine if
316 the getaddrinfo function is available during runtime.
318 Todo: Make getaddrinfo.c open the WS2_32.DLL and check for the
319 getaddrinfo symbol and use it if present, otherwise fall back to our
323 @node Libtool and Windows
324 @section Libtool and Windows
326 If you want it to be possible to cross-compile your program to MinGW
327 and you use Libtool, you need to put:
333 in your @file{configure.ac}. This sets the correct names for the
334 @code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
336 If you are building a library, you will also need to pass
337 @code{-no-undefined} to make sure Libtool produces a DLL for your
338 library. From a @file{Makefile.am}:
341 libgsasl_la_LDFLAGS += -no-undefined
345 @node License Texinfo sources
346 @section License Texinfo sources
348 Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
349 in Texinfo form. (The master location is
350 @url{http://www.gnu.org/licenses/}). These Texinfo documents have
351 various node names and structures built into them; for your manual,
352 you might like to change these. It's ok to do this, and a convenient
353 way to do so is to use a context diff and the @option{--local-dir}
354 option to @command{gnulib-tool}.
356 Of course the license texts themselves should not be changed at all.
358 @node Build robot for gnulib
359 @section Build robot for gnulib
361 To simplify testing on a wide set of platforms, gnulib is built on
362 many platforms every day and the results are uploaded to:
364 @url{http://autobuild.josefsson.org/gnulib/}
366 If you wish to help the gnulib development effort with build logs for
367 your favorite platform, you may perform these steps:
371 @item Create gnulib directory
373 On a machine with recent automake, autoconf, m4 installed and with a
374 gnulib cvs checkout (typically a Linux machine), use
377 gnulib-tool --create-megatestdir --with-tests --dir=..."
380 Note: The created directory uses ca. 512 MB on disk.
382 @item Transfer gnulib directory
384 Transfer this directory to a build machine (HP-UX, Cygwin, or
385 whatever). Often it is easier to transfer one file, and this can be
386 achieved by running, inside the directory the following commands:
393 And then transferring the @file{dummy-0.tar.gz} file.
397 On the build machine, run ./autobuild (or "nohup ./autobuild"). It
398 creates a directory 'logs/' with a log file for each module.
400 @item Submit build logs
402 Submit each log file to Simon's site, either through a
405 mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@/`
411 autobuild-submit logs/*
416 @node Particular Modules
417 @chapter Particular Modules
422 * error and progname::
425 * Regular expressions::
426 * Supporting Relocation::
433 @include inet_ntoa.texi
434 @include relocatable-maint.texi
436 @node Regular expressions
437 @section Regular expressions
439 Gnulib supports many different types of regular expressions; although
440 the underlying features are the same or identical, the syntax used
441 varies. The descriptions given here for the different types are
442 generated automatically.
444 @include regexprops-generic.texi
447 @node Copying This Manual
448 @appendix Copying This Manual
451 * GNU Free Documentation License:: License for copying this manual.