Mercurial > hg > CbC > CbC_gcc
annotate libiberty/libiberty.texi @ 158:494b0b89df80 default tip
...
| author | Shinji KONO <kono@ie.u-ryukyu.ac.jp> |
|---|---|
| date | Mon, 25 May 2020 18:13:55 +0900 |
| parents | 1830386684a0 |
| children |
| 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 | |
| 145 | 27 Copyright @copyright{} 2001-2020 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 | |
| 145 | 53 Copyright @copyright{} 2001-2020 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 |