Mercurial > hg > CbC > CbC_gcc
annotate libiberty/libiberty.texi @ 108:7ad14f446135
add CbC-example/rectypeTest/
| author | Nobuyasu Oshiro <dimolto@cr.ie.u-ryukyu.ac.jp> |
|---|---|
| date | Thu, 14 Jun 2012 20:30:24 +0900 |
| parents | f6334be47118 |
| children | 04ced10e8804 |
| 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 | |
|
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
|
27 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, |
|
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
|
28 2009, 2010 Free Software Foundation, Inc. |
| 0 | 29 |
| 30 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
|
31 under the terms of the GNU Free Documentation License, Version 1.3 |
| 0 | 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 | |
|
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
|
54 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, |
|
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
|
55 2009, 2010 Free Software Foundation, Inc. |
| 0 | 56 |
| 57 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
|
58 under the terms of the GNU Free Documentation License, Version 1.3 |
| 0 | 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 |