libiberty/libiberty.texi

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