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