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