Mercurial > hg > CbC > CbC_gcc
annotate libiberty/libiberty.texi @ 111:04ced10e8804
gcc 7
author | kono |
---|---|
date | Fri, 27 Oct 2017 22:46:09 +0900 |
parents | f6334be47118 |
children | 84e7813d76e9 |
rev | line source |
---|---|
0 | 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 | |
111 | 27 Copyright @copyright{} 2001-2017 Free Software Foundation, Inc. |
0 | 28 |
29 Permission is granted to copy, distribute and/or modify this document | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
30 under the terms of the GNU Free Documentation License, Version 1.3 |
0 | 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 | |
111 | 53 Copyright @copyright{} 2001-2017 Free Software Foundation, Inc. |
0 | 54 |
55 Permission is granted to copy, distribute and/or modify this document | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
56 under the terms of the GNU Free Documentation License, Version 1.3 |
0 | 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 | |
111 | 242 @c This is generated from the glibc manual using contrib/make-obstacks-texi.pl |
0 | 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 |