Mercurial > hg > octave-nkf > gnulib-hg
annotate doc/gnulib.texi @ 6764:a156a04768bf
gcd in menu
| author | Karl Berry <karl@freefriends.org> |
|---|---|
| date | Sun, 30 Apr 2006 13:38:54 +0000 |
| parents | 3f978fa80453 |
| children | 1b6de7675435 |
| rev | line source |
|---|---|
| 5239 | 1 \input texinfo @c -*-texinfo-*- |
| 6764 | 2 @comment $Id: gnulib.texi,v 1.21 2006-04-30 13:38:54 karl Exp $ |
| 5239 | 3 @comment %**start of header |
| 4 @setfilename gnulib.info | |
| 5 @settitle GNU Gnulib | |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
6 @syncodeindex fn cp |
| 5239 | 7 @syncodeindex pg cp |
| 8 @comment %**end of header | |
| 9 | |
| 6764 | 10 @set UPDATED $Date: 2006-04-30 13:38:54 $ |
| 5239 | 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 | |
| 6764 | 17 Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. |
| 5239 | 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 | |
| 5257 | 36 * Gnulib: (gnulib). Source files to share among distributions. |
| 5239 | 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 | |
| 5870 | 68 This manual contains some bare-bones documentation, but not much more. |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
69 It's mostly been a place to store notes until someone (you?)@ gets |
| 5870 | 70 around to writing a coherent manual. |
| 5239 | 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:: | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
84 * Header files:: |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
85 * Quoting:: |
| 5239 | 86 * ctime:: |
| 87 * inet_ntoa:: | |
| 6764 | 88 * gcd:: |
| 5239 | 89 * Out of memory handling:: |
|
5938
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
90 * Library version handling:: |
|
6008
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
91 * Regular expressions:: |
| 5239 | 92 @end menu |
| 93 | |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
94 |
| 5239 | 95 @node Comments |
| 96 @section Comments | |
| 97 | |
| 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. | |
| 106 | |
| 107 | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
108 @node Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
109 @section Header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
110 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
111 @cindex double inclusion of header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
112 @cindex header file include protection |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
113 It is a tradition to use CPP tricks to avoid parsing the same header |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
114 file more than once, which might cause warnings. The trick is to wrap |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
115 the content of the header file (say, @file{foo.h}) in a block, as in: |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
116 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
117 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
118 #ifndef FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
119 # define FOO_H |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
120 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
121 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
122 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
123 #endif /* FOO_H */ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
124 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
125 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
126 Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
127 style. The C89 and C99 standards reserve all identifiers that begin with an |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
128 underscore and either an uppercase letter or another underscore, for |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
129 any use. Thus, in theory, an application might not safely assume that |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
130 @code{_FOO_H} has not already been defined by a library. On the other |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
131 hand, using @code{FOO_H} will likely lead the higher risk of |
| 5269 | 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 | |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
135 the header file under discussion as part of the application (which has |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
136 its own namespace for CPP symbols) or a supporting library (that |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
137 shouldn't interfere with the application's CPP symbol namespace). |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
138 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
139 @cindex C++ header files |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
140 @cindex Header files and C++ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
141 Adapting C header files for use in C++ applications can use another |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
142 CPP trick, as in: |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
143 |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
144 @example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
145 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
146 extern "C" |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
147 @{ |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
148 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
149 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
150 body of header file goes here |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
151 ... |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
152 # ifdef __cplusplus |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
153 @} |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
154 # endif |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
155 @end example |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
156 |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
157 The idea here is that @code{__cplusplus} is defined only by C++ |
|
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
158 implementations, which will wrap the header file in an @samp{extern "C"} |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
159 block. Again, whether to use this trick is a matter of taste and |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
160 style. While the above can be seen as harmless, it could be argued |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
161 that the header file is written in C, and any C++ application using it |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
162 should explicitly use the @samp{extern "C"} block itself. Your |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
163 preference might depend on whether you consider the API exported by |
|
5261
95f7304acdac
Minor fixups to previous patch.
Paul Eggert <eggert@cs.ucla.edu>
parents:
5260
diff
changeset
|
164 your header file as something available for C programs only, or for C |
|
5260
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
165 and C++ programs alike. |
|
5a0174704b16
header files, from simon
Karl Berry <karl@freefriends.org>
parents:
5257
diff
changeset
|
166 |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
167 @subheading Include ordering |
|
5883
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
168 |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
169 When writing a gnulib module, or even in general, a good way to order |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
170 the @samp{#include} directives is the following. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
171 |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
172 @itemize |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
173 @item First comes the #include "..." specifying the module being implemented. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
174 @item Then come all the #include <...> of system or system-replacement headers, |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
175 in arbitrary order. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
176 @item Then come all the #include "..." of gnulib and private headers, in |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
177 arbitrary order. |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
178 @end itemize |
|
19bb5e876a29
Add "Include ordering", based on e-mail from Bruno.
Simon Josefsson <simon@josefsson.org>
parents:
5870
diff
changeset
|
179 |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
180 |
|
6256
22062645e739
Move many things into separate files.
Bruno Haible <bruno@clisp.org>
parents:
6251
diff
changeset
|
181 @include quote.texi |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
182 |
|
6256
22062645e739
Move many things into separate files.
Bruno Haible <bruno@clisp.org>
parents:
6251
diff
changeset
|
183 @include ctime.texi |
| 5239 | 184 |
| 6764 | 185 @include gcd.texi |
| 5239 | 186 |
|
6256
22062645e739
Move many things into separate files.
Bruno Haible <bruno@clisp.org>
parents:
6251
diff
changeset
|
187 @include inet_ntoa.texi |
| 5239 | 188 |
| 189 | |
| 190 @node Out of memory handling | |
| 191 @section Out of memory handling | |
| 192 | |
| 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. | |
| 202 | |
| 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. | |
| 207 | |
| 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 | |
| 216 declared as follows. | |
| 217 | |
| 218 @example | |
| 219 extern void (*xalloc_fail_func) (void); | |
| 220 @end example | |
| 221 | |
| 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 | |
| 228 fail. | |
| 229 | |
| 230 | |
|
5938
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
231 @node Library version handling |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
232 @section Library version handling |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
233 |
|
5992
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
234 The module @samp{check-version} can be useful when your gnulib |
|
5938
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
235 application is a system library. You will typically wrap the call to |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
236 the @code{check_version} function through a library API, your library |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
237 header file may contain: |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
238 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
239 @example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
240 #define STRINGPREP_VERSION "0.5.18" |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
241 ... |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
242 extern const char *stringprep_check_version (const char *req_version); |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
243 @end example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
244 |
|
5992
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
245 To avoid ELF symbol collisions with other libraries that use the |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
246 @samp{check-version} module, add to @file{config.h} through a |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
247 AC_DEFINE something like: |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
248 |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
249 @example |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
250 AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.]) |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
251 @end example |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
252 |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
253 The @code{stringprep_check_version} function will thus be implemented |
|
6cf595732ddb
gnulib.texi (Library version handling): Add ELF symbol collision
Simon Josefsson <simon@josefsson.org>
parents:
5983
diff
changeset
|
254 by the @code{check_version} module. |
|
5938
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
255 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
256 There are two uses of the interface. The first is a way to provide |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
257 for applications to find out the version number of the library it |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
258 uses. The application may contain diagnostic code such as: |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
259 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
260 @example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
261 printf ("Stringprep version: header %s library %s", |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
262 STRINGPREP_VERSION, |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
263 stringprep_check_version (NULL)); |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
264 @end example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
265 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
266 Separating the library and header file version can be useful when |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
267 searching for version mismatch related problems. |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
268 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
269 The second uses is as a rudimentary test of proper library version, by |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
270 making sure the application get a library version that is the same, or |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
271 newer, than the header file used when building the application. This |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
272 doesn't catch all problems, libraries may change backwards incompatibly |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
273 in later versions, but enable applications to require a certain |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
274 minimum version before it may proceed. |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
275 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
276 Typical uses look like: |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
277 |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
278 @example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
279 /* Check version of libgcrypt. */ |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
280 if (!gcry_check_version (GCRYPT_VERSION)) |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
281 die ("version mismatch\n"); |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
282 @end example |
|
14697da96543
2005-06-28 Simon Josefsson <jas@extundo.com>
Simon Josefsson <simon@josefsson.org>
parents:
5883
diff
changeset
|
283 |
|
5982
8f55c4ac38d6
updates from Patrice, start at quoting
Karl Berry <karl@freefriends.org>
parents:
5938
diff
changeset
|
284 |
|
6008
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
285 @node Regular expressions |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
286 @section Regular expressions |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
287 |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
288 Gnulib supports many different types of regular expressions; although |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
289 the underlying features are the same or identical, the syntax used |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
290 varies. The descriptions given here for the different types are |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
291 generated automatically. |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
292 |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
293 @include regexprops-generic.texi |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
294 |
|
47323bc9321f
regexprops, generated by findutils helper
Karl Berry <karl@freefriends.org>
parents:
5992
diff
changeset
|
295 |
|
6256
22062645e739
Move many things into separate files.
Bruno Haible <bruno@clisp.org>
parents:
6251
diff
changeset
|
296 @include gnulib-tool.texi |
|
5256
e23bd8e9d368
import sections from Simon
Karl Berry <karl@freefriends.org>
parents:
5239
diff
changeset
|
297 |
| 5239 | 298 |
| 299 @node Copying This Manual | |
| 300 @appendix Copying This Manual | |
| 301 | |
| 302 @menu | |
| 303 * GNU Free Documentation License:: License for copying this manual. | |
| 304 @end menu | |
| 305 | |
| 306 @include fdl.texi | |
| 307 | |
| 308 | |
| 309 @node Index | |
| 310 @unnumbered Index | |
| 311 | |
| 312 @printindex cp | |
| 313 | |
| 314 @bye |