|
0
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @c %**start of header
|
|
|
3 @setfilename libiberty.info
|
|
|
4 @settitle @sc{gnu} libiberty
|
|
|
5 @c %**end of header
|
|
|
6
|
|
|
7 @syncodeindex fn cp
|
|
|
8 @syncodeindex vr cp
|
|
|
9 @syncodeindex pg cp
|
|
|
10
|
|
|
11 @finalout
|
|
|
12 @c %**end of header
|
|
|
13
|
|
|
14 @dircategory GNU libraries
|
|
|
15 @direntry
|
|
|
16 * Libiberty: (libiberty). Library of utility functions which
|
|
|
17 are missing or broken on some systems.
|
|
|
18 @end direntry
|
|
|
19
|
|
|
20 @macro libib
|
|
|
21 @code{libiberty}
|
|
|
22 @end macro
|
|
|
23
|
|
|
24 @c The edition date is written in three locations. Search for 'thedate'.
|
|
|
25 @ifinfo
|
|
|
26 This manual describes the GNU @libib library of utility subroutines.
|
|
|
27 This edition accompanies GCC 3, September 2001.
|
|
|
28
|
|
|
29 Copyright @copyright{} 2001 Free Software Foundation, Inc.
|
|
|
30
|
|
|
31 Permission is granted to copy, distribute and/or modify this document
|
|
|
32 under the terms of the GNU Free Documentation License, Version 1.2
|
|
|
33 or any later version published by the Free Software Foundation;
|
|
|
34 with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
|
35 Back-Cover Texts. A copy of the license is included in the
|
|
|
36 section entitled ``GNU Free Documentation License''.
|
|
|
37
|
|
|
38 @ignore
|
|
|
39 Permission is granted to process this file through TeX and print the
|
|
|
40 results, provided the printed document carries a copying permission
|
|
|
41 notice identical to this one except for the removal of this paragraph
|
|
|
42 (this paragraph not being relevant to the printed manual).
|
|
|
43
|
|
|
44 @end ignore
|
|
|
45 @end ifinfo
|
|
|
46
|
|
|
47
|
|
|
48 @c The edition date is written in three locations. Search for 'thedate'.
|
|
|
49 @titlepage
|
|
|
50 @title @sc{gnu} libiberty
|
|
|
51 @subtitle September 2001
|
|
|
52 @subtitle for GCC 3
|
|
|
53 @author Phil Edwards et al.
|
|
|
54 @page
|
|
|
55
|
|
|
56
|
|
|
57 @vskip 0pt plus 1filll
|
|
|
58 Copyright @copyright{} 2001 Free Software Foundation, Inc.
|
|
|
59
|
|
|
60 Permission is granted to copy, distribute and/or modify this document
|
|
|
61 under the terms of the GNU Free Documentation License, Version 1.2
|
|
|
62 or any later version published by the Free Software Foundation;
|
|
|
63 with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
|
64 Back-Cover Texts. A copy of the license is included in the
|
|
|
65 section entitled ``GNU Free Documentation License''.
|
|
|
66
|
|
|
67 @end titlepage
|
|
|
68 @contents
|
|
|
69 @page
|
|
|
70
|
|
|
71 @ifnottex
|
|
|
72 @node Top,Using,,
|
|
|
73 @top Introduction
|
|
|
74
|
|
|
75 The @libib{} library is a collection of subroutines used by various
|
|
|
76 GNU programs. It is available under the Library General Public
|
|
|
77 License; for more information, see @ref{Library Copying}.
|
|
|
78
|
|
|
79 @c The edition date is written in three locations. Search for 'thedate'.
|
|
|
80 This edition accompanies GCC 3, September 2001.
|
|
|
81
|
|
|
82 @end ifnottex
|
|
|
83
|
|
|
84 @menu
|
|
|
85 * Using:: How to use libiberty in your code.
|
|
|
86
|
|
|
87 * Overview:: Overview of available function groups.
|
|
|
88
|
|
|
89 * Functions:: Available functions, macros, and global variables.
|
|
|
90
|
|
|
91 * Obstacks:: Object Stacks.
|
|
|
92
|
|
|
93 * Licenses:: The various licenses under which libiberty sources are
|
|
|
94 distributed.
|
|
|
95
|
|
|
96 * Index:: Index of functions and categories.
|
|
|
97 @end menu
|
|
|
98
|
|
|
99 @node Using
|
|
|
100 @chapter Using
|
|
|
101 @cindex using libiberty
|
|
|
102 @cindex libiberty usage
|
|
|
103 @cindex how to use
|
|
|
104
|
|
|
105 @c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY.
|
|
|
106
|
|
|
107 To date, @libib{} is generally not installed on its own. It has evolved
|
|
|
108 over years but does not have its own version number nor release schedule.
|
|
|
109
|
|
|
110 Possibly the easiest way to use @libib{} in your projects is to drop the
|
|
|
111 @libib{} code into your project's sources, and to build the library along
|
|
|
112 with your own sources; the library would then be linked in at the end. This
|
|
|
113 prevents any possible version mismatches with other copies of libiberty
|
|
|
114 elsewhere on the system.
|
|
|
115
|
|
|
116 Passing @option{--enable-install-libiberty} to the @command{configure}
|
|
|
117 script when building @libib{} causes the header files and archive library
|
|
|
118 to be installed when @kbd{make install} is run. This option also takes
|
|
|
119 an (optional) argument to specify the installation location, in the same
|
|
|
120 manner as @option{--prefix}.
|
|
|
121
|
|
|
122 For your own projects, an approach which offers stability and flexibility
|
|
|
123 is to include @libib{} with your code, but allow the end user to optionally
|
|
|
124 choose to use a previously-installed version instead. In this way the
|
|
|
125 user may choose (for example) to install @libib{} as part of GCC, and use
|
|
|
126 that version for all software built with that compiler. (This approach
|
|
|
127 has proven useful with software using the GNU @code{readline} library.)
|
|
|
128
|
|
|
129 Making use of @libib{} code usually requires that you include one or more
|
|
|
130 header files from the @libib{} distribution. (They will be named as
|
|
|
131 necessary in the function descriptions.) At link time, you will need to
|
|
|
132 add @option{-liberty} to your link command invocation.
|
|
|
133
|
|
|
134
|
|
|
135 @node Overview
|
|
|
136 @chapter Overview
|
|
|
137
|
|
|
138 Functions contained in @libib{} can be divided into three general categories.
|
|
|
139
|
|
|
140
|
|
|
141 @menu
|
|
|
142 * Supplemental Functions:: Providing functions which don't exist
|
|
|
143 on older operating systems.
|
|
|
144
|
|
|
145 * Replacement Functions:: These functions are sometimes buggy or
|
|
|
146 unpredictable on some operating systems.
|
|
|
147
|
|
|
148 * Extensions:: Functions which provide useful extensions
|
|
|
149 or safety wrappers around existing code.
|
|
|
150 @end menu
|
|
|
151
|
|
|
152 @node Supplemental Functions
|
|
|
153 @section Supplemental Functions
|
|
|
154 @cindex supplemental functions
|
|
|
155 @cindex functions, supplemental
|
|
|
156 @cindex functions, missing
|
|
|
157
|
|
|
158 Certain operating systems do not provide functions which have since
|
|
|
159 become standardized, or at least common. For example, the Single
|
|
|
160 Unix Specification Version 2 requires that the @code{basename}
|
|
|
161 function be provided, but an OS which predates that specification
|
|
|
162 might not have this function. This should not prevent well-written
|
|
|
163 code from running on such a system.
|
|
|
164
|
|
|
165 Similarly, some functions exist only among a particular ``flavor''
|
|
|
166 or ``family'' of operating systems. As an example, the @code{bzero}
|
|
|
167 function is often not present on systems outside the BSD-derived
|
|
|
168 family of systems.
|
|
|
169
|
|
|
170 Many such functions are provided in @libib{}. They are quickly
|
|
|
171 listed here with little description, as systems which lack them
|
|
|
172 become less and less common. Each function @var{foo} is implemented
|
|
|
173 in @file{@var{foo}.c} but not declared in any @libib{} header file; more
|
|
|
174 comments and caveats for each function's implementation are often
|
|
|
175 available in the source file. Generally, the function can simply
|
|
|
176 be declared as @code{extern}.
|
|
|
177
|
|
|
178
|
|
|
179
|
|
|
180 @node Replacement Functions
|
|
|
181 @section Replacement Functions
|
|
|
182 @cindex replacement functions
|
|
|
183 @cindex functions, replacement
|
|
|
184
|
|
|
185 Some functions have extremely limited implementations on different
|
|
|
186 platforms. Other functions are tedious to use correctly; for example,
|
|
|
187 proper use of @code{malloc} calls for the return value to be checked and
|
|
|
188 appropriate action taken if memory has been exhausted. A group of
|
|
|
189 ``replacement functions'' is available in @libib{} to address these issues
|
|
|
190 for some of the most commonly used subroutines.
|
|
|
191
|
|
|
192 All of these functions are declared in the @file{libiberty.h} header
|
|
|
193 file. Many of the implementations will use preprocessor macros set by
|
|
|
194 GNU Autoconf, if you decide to make use of that program. Some of these
|
|
|
195 functions may call one another.
|
|
|
196
|
|
|
197
|
|
|
198 @menu
|
|
|
199 * Memory Allocation:: Testing and handling failed memory
|
|
|
200 requests automatically.
|
|
|
201 * Exit Handlers:: Calling routines on program exit.
|
|
|
202 * Error Reporting:: Mapping errno and signal numbers to
|
|
|
203 more useful string formats.
|
|
|
204 @end menu
|
|
|
205
|
|
|
206 @node Memory Allocation
|
|
|
207 @subsection Memory Allocation
|
|
|
208 @cindex memory allocation
|
|
|
209
|
|
|
210 The functions beginning with the letter @samp{x} are wrappers around
|
|
|
211 standard functions; the functions provided by the system environment
|
|
|
212 are called and their results checked before the results are passed back
|
|
|
213 to client code. If the standard functions fail, these wrappers will
|
|
|
214 terminate the program. Thus, these versions can be used with impunity.
|
|
|
215
|
|
|
216
|
|
|
217 @node Exit Handlers
|
|
|
218 @subsection Exit Handlers
|
|
|
219 @cindex exit handlers
|
|
|
220
|
|
|
221 The existence and implementation of the @code{atexit} routine varies
|
|
|
222 amongst the flavors of Unix. @libib{} provides an unvarying dependable
|
|
|
223 implementation via @code{xatexit} and @code{xexit}.
|
|
|
224
|
|
|
225
|
|
|
226 @node Error Reporting
|
|
|
227 @subsection Error Reporting
|
|
|
228 @cindex error reporting
|
|
|
229
|
|
|
230 These are a set of routines to facilitate programming with the system
|
|
|
231 @code{errno} interface. The @libib{} source file @file{strerror.c}
|
|
|
232 contains a good deal of documentation for these functions.
|
|
|
233
|
|
|
234 @c signal stuff
|
|
|
235
|
|
|
236
|
|
|
237 @node Extensions
|
|
|
238 @section Extensions
|
|
|
239 @cindex extensions
|
|
|
240 @cindex functions, extension
|
|
|
241
|
|
|
242 @libib{} includes additional functionality above and beyond standard
|
|
|
243 functions, which has proven generically useful in GNU programs, such as
|
|
|
244 obstacks and regex. These functions are often copied from other
|
|
|
245 projects as they gain popularity, and are included here to provide a
|
|
|
246 central location from which to use, maintain, and distribute them.
|
|
|
247
|
|
|
248 @menu
|
|
|
249 * Obstacks:: Stacks of arbitrary objects.
|
|
|
250 @end menu
|
|
|
251
|
|
|
252 @c This is generated from the glibc manual using a make-obstacks-texi.sh
|
|
|
253 @c script of Phil's. Hope it's accurate.
|
|
|
254 @include obstacks.texi
|
|
|
255
|
|
|
256 @node Functions
|
|
|
257 @chapter Function, Variable, and Macro Listing.
|
|
|
258 @include functions.texi
|
|
|
259
|
|
|
260 @node Licenses
|
|
|
261 @appendix Licenses
|
|
|
262
|
|
|
263 @menu
|
|
|
264
|
|
|
265 * Library Copying:: The GNU Library General Public License
|
|
|
266 * BSD:: Regents of the University of California
|
|
|
267
|
|
|
268 @end menu
|
|
|
269
|
|
|
270 @c This takes care of Library Copying. It is the copying-lib.texi from the
|
|
|
271 @c GNU web site, with its @node line altered to make makeinfo shut up.
|
|
|
272 @include copying-lib.texi
|
|
|
273
|
|
|
274 @page
|
|
|
275 @node BSD
|
|
|
276 @appendixsec BSD
|
|
|
277
|
|
|
278 Copyright @copyright{} 1990 Regents of the University of California.
|
|
|
279 All rights reserved.
|
|
|
280
|
|
|
281 Redistribution and use in source and binary forms, with or without
|
|
|
282 modification, are permitted provided that the following conditions
|
|
|
283 are met:
|
|
|
284
|
|
|
285 @enumerate
|
|
|
286
|
|
|
287 @item
|
|
|
288 Redistributions of source code must retain the above copyright
|
|
|
289 notice, this list of conditions and the following disclaimer.
|
|
|
290
|
|
|
291 @item
|
|
|
292 Redistributions in binary form must reproduce the above copyright
|
|
|
293 notice, this list of conditions and the following disclaimer in the
|
|
|
294 documentation and/or other materials provided with the distribution.
|
|
|
295
|
|
|
296 @item
|
|
|
297 [rescinded 22 July 1999]
|
|
|
298
|
|
|
299 @item
|
|
|
300 Neither the name of the University nor the names of its contributors
|
|
|
301 may be used to endorse or promote products derived from this software
|
|
|
302 without specific prior written permission.
|
|
|
303
|
|
|
304 @end enumerate
|
|
|
305
|
|
|
306 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
|
307 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
|
308 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
|
309 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
|
310 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
|
311 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
|
312 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
|
313 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
|
314 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
|
315 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
|
316 SUCH DAMAGE.
|
|
|
317
|
|
|
318 @node Index
|
|
|
319 @unnumbered Index
|
|
|
320
|
|
|
321 @printindex cp
|
|
|
322
|
|
|
323 @bye
|
|
|
324
|
