Mercurial > hg > CbC > CbC_gcc
comparison libiberty/libiberty.texi @ 0:a06113de4d67
first commit
author | kent <kent@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Fri, 17 Jul 2009 14:47:48 +0900 |
parents | |
children | f6334be47118 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:a06113de4d67 |
---|---|
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 @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 |