OSDN Git Service

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