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