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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gdb-7.2/] [libiberty/] [libiberty.texi] - Blame information for rev 841

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 330 jeremybenn
\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
 

powered by: WebSVN 2.1.0

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