1 |
14 |
jlechner |
\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 |
|
|
|