OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [binutils-2.18.50/] [libiberty/] [libiberty.texi] - Blame information for rev 156

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 38 julius
\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
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.