| 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 | |