1 \input texinfo @c -*-texinfo-*-
2 @comment $Id: gnulib.texi,v 1.21 2006-04-30 13:38:54 karl Exp $
3 @comment %**start of header
4 @setfilename gnulib.info
8 @comment %**end of header
10 @set UPDATED $Date: 2006-04-30 13:38:54 $
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 * Copying This Manual::
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.
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/}.
89 * Out of memory handling::
90 * Library version handling::
91 * Regular expressions::
98 @cindex comments describing functions
99 @cindex describing functions, locating
100 Where to put comments describing functions: Because of risk of
101 divergence, we prefer to keep most function describing comments in
102 only one place: just above the actual function definition. Some
103 people prefer to put that documentation in the .h file. In any case,
104 it should appear in just one place unless you can ensure that the
105 multiple copies will always remain identical.
109 @section Header files
111 @cindex double inclusion of header files
112 @cindex header file include protection
113 It is a tradition to use CPP tricks to avoid parsing the same header
114 file more than once, which might cause warnings. The trick is to wrap
115 the content of the header file (say, @file{foo.h}) in a block, as in:
121 body of header file goes here
126 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
127 style. The C89 and C99 standards reserve all identifiers that begin with an
128 underscore and either an uppercase letter or another underscore, for
129 any use. Thus, in theory, an application might not safely assume that
130 @code{_FOO_H} has not already been defined by a library. On the other
131 hand, using @code{FOO_H} will likely lead the higher risk of
132 collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
133 which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
134 macro function). Your preference may depend on whether you consider
135 the header file under discussion as part of the application (which has
136 its own namespace for CPP symbols) or a supporting library (that
137 shouldn't interfere with the application's CPP symbol namespace).
139 @cindex C++ header files
140 @cindex Header files and C++
141 Adapting C header files for use in C++ applications can use another
150 body of header file goes here
157 The idea here is that @code{__cplusplus} is defined only by C++
158 implementations, which will wrap the header file in an @samp{extern "C"}
159 block. Again, whether to use this trick is a matter of taste and
160 style. While the above can be seen as harmless, it could be argued
161 that the header file is written in C, and any C++ application using it
162 should explicitly use the @samp{extern "C"} block itself. Your
163 preference might depend on whether you consider the API exported by
164 your header file as something available for C programs only, or for C
165 and C++ programs alike.
167 @subheading Include ordering
169 When writing a gnulib module, or even in general, a good way to order
170 the @samp{#include} directives is the following.
173 @item First comes the #include "..." specifying the module being implemented.
174 @item Then come all the #include <...> of system or system-replacement headers,
176 @item Then come all the #include "..." of gnulib and private headers, in
187 @include inet_ntoa.texi
190 @node Out of memory handling
191 @section Out of memory handling
193 @cindex Out of Memory handling
194 @cindex Memory allocation failure
195 The GSS API does not have a standard error code for the out of memory
196 error condition. Instead of adding a non-standard error code, this
197 library has chosen to adopt a different strategy. Out of memory
198 handling happens in rare situations, but performing the out of memory
199 error handling after almost all API function invocations pollute your
200 source code and might make it harder to spot more serious problems.
201 The strategy chosen improve code readability and robustness.
203 @cindex Aborting execution
204 For most applications, aborting the application with an error message
205 when the out of memory situation occur is the best that can be wished
206 for. This is how the library behaves by default.
208 @vindex xalloc_fail_func
209 However, we realize that some applications may not want to have the
210 GSS library abort execution in any situation. The GSS library support
211 a hook to let the application regain control and perform its own
212 cleanups when an out of memory situation has occured. The application
213 can define a function (having a @code{void} prototype, i.e., no return
214 value and no parameters) and set the library variable
215 @code{xalloc_fail_func} to that function. The variable should be
219 extern void (*xalloc_fail_func) (void);
222 The GSS library will invoke this function if an out of memory error
223 occurs. Note that after this the GSS library is in an undefined
224 state, so you must unload or restart the application to continue call
225 GSS library functions. The hook is only intended to allow the
226 application to log the situation in a special way. Of course, care
227 must be taken to not allocate more memory, as that will likely also
231 @node Library version handling
232 @section Library version handling
234 The module @samp{check-version} can be useful when your gnulib
235 application is a system library. You will typically wrap the call to
236 the @code{check_version} function through a library API, your library
237 header file may contain:
240 #define STRINGPREP_VERSION "0.5.18"
242 extern const char *stringprep_check_version (const char *req_version);
245 To avoid ELF symbol collisions with other libraries that use the
246 @samp{check-version} module, add to @file{config.h} through a
247 AC_DEFINE something like:
250 AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.])
253 The @code{stringprep_check_version} function will thus be implemented
254 by the @code{check_version} module.
256 There are two uses of the interface. The first is a way to provide
257 for applications to find out the version number of the library it
258 uses. The application may contain diagnostic code such as:
261 printf ("Stringprep version: header %s library %s",
263 stringprep_check_version (NULL));
266 Separating the library and header file version can be useful when
267 searching for version mismatch related problems.
269 The second uses is as a rudimentary test of proper library version, by
270 making sure the application get a library version that is the same, or
271 newer, than the header file used when building the application. This
272 doesn't catch all problems, libraries may change backwards incompatibly
273 in later versions, but enable applications to require a certain
274 minimum version before it may proceed.
276 Typical uses look like:
279 /* Check version of libgcrypt. */
280 if (!gcry_check_version (GCRYPT_VERSION))
281 die ("version mismatch\n");
285 @node Regular expressions
286 @section Regular expressions
288 Gnulib supports many different types of regular expressions; although
289 the underlying features are the same or identical, the syntax used
290 varies. The descriptions given here for the different types are
291 generated automatically.
293 @include regexprops-generic.texi
296 @include gnulib-tool.texi
299 @node Copying This Manual
300 @appendix Copying This Manual
303 * GNU Free Documentation License:: License for copying this manual.