1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.29 2006-10-23 11:27:37 haible Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2006-10-23 11:27:37 $
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 Free Software Foundation, Inc.
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
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.''
34 @dircategory Software development
36 * Gnulib: (gnulib). Source files to share among distributions.
41 @subtitle updated @value{UPDATED}
42 @author @email{bug-gnulib@@gnu.org}
44 @vskip 0pt plus 1filll
59 * Invoking gnulib-tool::
60 * Miscellanous Notes::
61 * Particular Modules:: Documentation of Individual Modules
62 * Copying This Manual::
70 Gnulib is a source code library. It provides basic functionalities to
71 programs and libraries. Currently (as of October 2006) more than 30
72 packages make use of Gnulib.
77 @item Gnulib is hosted at Savannah:
78 @url{http://savannah.gnu.org/projects/gnulib}. Get the sources
79 through CVS from there.
80 @item The Gnulib home page:
81 @url{http://www.gnu.org/software/gnulib/}.
85 * Library vs. Reusable Code::
86 * Portability and Application Code::
88 * Various Kinds of Modules::
89 * Collaborative Development::
91 * Steady Development::
95 @include gnulib-intro.texi
98 @include gnulib-tool.texi
101 @node Miscellanous Notes
102 @chapter Miscellanous Notes
107 * Out of memory handling::
108 * Library version handling::
110 * Libtool and Windows::
111 * License Texinfo sources::
118 @cindex comments describing functions
119 @cindex describing functions, locating
120 Where to put comments describing functions: Because of risk of
121 divergence, we prefer to keep most function describing comments in
122 only one place: just above the actual function definition. Some
123 people prefer to put that documentation in the .h file. In any case,
124 it should appear in just one place unless you can ensure that the
125 multiple copies will always remain identical.
129 @section Header files
131 @cindex double inclusion of header files
132 @cindex header file include protection
133 It is a tradition to use CPP tricks to avoid parsing the same header
134 file more than once, which might cause warnings. The trick is to wrap
135 the content of the header file (say, @file{foo.h}) in a block, as in:
141 body of header file goes here
146 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
147 style. The C89 and C99 standards reserve all identifiers that begin with an
148 underscore and either an uppercase letter or another underscore, for
149 any use. Thus, in theory, an application might not safely assume that
150 @code{_FOO_H} has not already been defined by a library. On the other
151 hand, using @code{FOO_H} will likely lead the higher risk of
152 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
153 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
154 macro function). Your preference may depend on whether you consider
155 the header file under discussion as part of the application (which has
156 its own namespace for CPP symbols) or a supporting library (that
157 shouldn't interfere with the application's CPP symbol namespace).
159 @cindex C++ header files
160 @cindex Header files and C++
161 Adapting C header files for use in C++ applications can use another
170 body of header file goes here
177 The idea here is that @code{__cplusplus} is defined only by C++
178 implementations, which will wrap the header file in an @samp{extern "C"}
179 block. Again, whether to use this trick is a matter of taste and
180 style. While the above can be seen as harmless, it could be argued
181 that the header file is written in C, and any C++ application using it
182 should explicitly use the @samp{extern "C"} block itself. Your
183 preference might depend on whether you consider the API exported by
184 your header file as something available for C programs only, or for C
185 and C++ programs alike.
187 @subheading Include ordering
189 When writing a gnulib module, or even in general, a good way to order
190 the @samp{#include} directives is the following.
193 @item First comes the #include "..." specifying the module being implemented.
194 @item Then come all the #include <...> of system or system-replacement headers,
196 @item Then come all the #include "..." of gnulib and private headers, in
201 @node Out of memory handling
202 @section Out of memory handling
204 @cindex Out of Memory handling
205 @cindex Memory allocation failure
206 The GSS API does not have a standard error code for the out of memory
207 error condition. Instead of adding a non-standard error code, this
208 library has chosen to adopt a different strategy. Out of memory
209 handling happens in rare situations, but performing the out of memory
210 error handling after almost all API function invocations pollute your
211 source code and might make it harder to spot more serious problems.
212 The strategy chosen improve code readability and robustness.
214 @cindex Aborting execution
215 For most applications, aborting the application with an error message
216 when the out of memory situation occur is the best that can be wished
217 for. This is how the library behaves by default.
219 @vindex xalloc_fail_func
220 However, we realize that some applications may not want to have the
221 GSS library abort execution in any situation. The GSS library support
222 a hook to let the application regain control and perform its own
223 cleanups when an out of memory situation has occurred. The application
224 can define a function (having a @code{void} prototype, i.e., no return
225 value and no parameters) and set the library variable
226 @code{xalloc_fail_func} to that function. The variable should be
230 extern void (*xalloc_fail_func) (void);
233 The GSS library will invoke this function if an out of memory error
234 occurs. Note that after this the GSS library is in an undefined
235 state, so you must unload or restart the application to continue call
236 GSS library functions. The hook is only intended to allow the
237 application to log the situation in a special way. Of course, care
238 must be taken to not allocate more memory, as that will likely also
242 @node Library version handling
243 @section Library version handling
245 The module @samp{check-version} can be useful when your gnulib
246 application is a system library. You will typically wrap the call to
247 the @code{check_version} function through a library API, your library
248 header file may contain:
251 #define STRINGPREP_VERSION "0.5.18"
253 extern const char *stringprep_check_version (const char *req_version);
256 To avoid ELF symbol collisions with other libraries that use the
257 @samp{check-version} module, add to @file{config.h} through a
258 AC_DEFINE something like:
261 AC_DEFINE(check_version, stringprep_check_version,
262 [Rename check_version.])
265 The @code{stringprep_check_version} function will thus be implemented
266 by the @code{check_version} module.
268 There are two uses of the interface. The first is a way to provide
269 for applications to find out the version number of the library it
270 uses. The application may contain diagnostic code such as:
273 printf ("Stringprep version: header %s library %s",
275 stringprep_check_version (NULL));
278 Separating the library and header file version can be useful when
279 searching for version mismatch related problems.
281 The second uses is as a rudimentary test of proper library version, by
282 making sure the application get a library version that is the same, or
283 newer, than the header file used when building the application. This
284 doesn't catch all problems, libraries may change backwards incompatibly
285 in later versions, but enable applications to require a certain
286 minimum version before it may proceed.
288 Typical uses look like:
291 /* Check version of libgcrypt. */
292 if (!gcry_check_version (GCRYPT_VERSION))
293 die ("version mismatch\n");
297 @node Windows sockets
298 @section Windows sockets
300 There are several issues when building applications that should work
301 under Windows. The most problematic part is for applications that use
304 Hopefully, we can add helpful notes to this section that will help you
305 port your application to Windows using gnulib.
307 @subsection Getaddrinfo and WINVER
309 This was written for the getaddrinfo module, but may be applicable to
312 The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
313 XP. The function declaration is present if @code{WINVER >= 0x0501}.
314 Windows 2000 does not have getaddrinfo in its @file{WS2_32.dll}.
316 Thus, if you want to assume Windows XP or later, you can add
317 AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo
320 If you want to support Windows 2000, don't do anything, but be aware
321 that gnulib will use its own (partial) getaddrinfo implementation even
322 on Windows XP. Currently the code does not attempt to determine if
323 the getaddrinfo function is available during runtime.
325 Todo: Make getaddrinfo.c open the WS2_32.DLL and check for the
326 getaddrinfo symbol and use it if present, otherwise fall back to our
330 @node Libtool and Windows
331 @section Libtool and Windows
333 If you want it to be possible to cross-compile your program to MinGW
334 and you use Libtool, you need to put:
340 in your @file{configure.ac}. This sets the correct names for the
341 @code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
343 If you are building a library, you will also need to pass
344 @code{-no-undefined} to make sure Libtool produces a DLL for your
345 library. From a @file{Makefile.am}:
348 libgsasl_la_LDFLAGS += -no-undefined
352 @node License Texinfo sources
353 @section License Texinfo sources
355 Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
356 in Texinfo form. (The master location is
357 @url{http://www.gnu.org/licenses/}). These Texinfo documents have
358 various node names and structures built into them; for your manual,
359 you might like to change these. It's ok to do this, and a convenient
360 way to do so is to use a context diff and the @option{--local-dir}
361 option to @command{gnulib-tool}.
363 Of course the license texts themselves should not be changed at all.
366 @node Particular Modules
367 @chapter Particular Modules
374 * Regular expressions::
383 @include inet_ntoa.texi
385 @node Regular expressions
386 @section Regular expressions
388 Gnulib supports many different types of regular expressions; although
389 the underlying features are the same or identical, the syntax used
390 varies. The descriptions given here for the different types are
391 generated automatically.
393 @include regexprops-generic.texi
396 @node Copying This Manual
397 @appendix Copying This Manual
400 * GNU Free Documentation License:: License for copying this manual.