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
  10 @macro libib
  11 @code{libiberty}
  12 @end macro
  13
  14 @c The edition date is written in three locations.  Search for 'thedate'.
  15 @ifinfo
  16 This manual describes the GNU @libib library of utility subroutines.
  17 This edition accompanies GCC 3, September 2001.
  18
  19 Copyright @copyright{} 2001 Free Software Foundation, Inc.
  20
  21       Permission is granted to copy, distribute and/or modify this document
  22       under the terms of the GNU Free Documentation License, Version 1.1
  23       or any later version published by the Free Software Foundation;
  24       with no Invariant Sections, with no Front-Cover Texts, and with no
  25       Back-Cover Texts.  A copy of the license is included in the
  26       section entitled ``GNU Free Documentation License''.
  27
  28 @ignore
  29 Permission is granted to process this file through TeX and print the
  30 results, provided the printed document carries a copying permission
  31 notice identical to this one except for the removal of this paragraph
  32 (this paragraph not being relevant to the printed manual).
  33
  34 @end ignore
  35 @end ifinfo
  36
  37
  38 @c The edition date is written in three locations.  Search for 'thedate'.
  39 @titlepage
  40 @title @sc{gnu} libiberty
  41 @subtitle September 2001
  42 @subtitle for GCC 3
  43 @author Phil Edwards et al.
  44 @page
  45
  46
  47 @vskip 0pt plus 1filll
  48 Copyright @copyright{} 2001 Free Software Foundation, Inc.
  49
  50       Permission is granted to copy, distribute and/or modify this document
  51       under the terms of the GNU Free Documentation License, Version 1.1
  52       or any later version published by the Free Software Foundation;
  53       with no Invariant Sections, with no Front-Cover Texts, and with no
  54       Back-Cover Texts.  A copy of the license is included in the
  55       section entitled ``GNU Free Documentation License''.
  56
  57 @end titlepage
  58
  59
  60 @ifnottex
  61 @node    Top,Using,,
  62 @top     Introduction
  63
  64 The @libib{} library is a collection of subroutines used by various
  65 GNU programs.  It is available under the Library General Public
  66 License; for more information, see @ref{Library Copying}.
  67
  68 @c The edition date is written in three locations.  Search for 'thedate'.
  69 This edition accompanies GCC 3, September 2001.
  70
  71 @end ifnottex
  72
  73 @menu
  74 * Using::              How to use libiberty in your code.
  75
  76 * Overview::           Overview of available function groups.
  77
  78 * Functions::          Available functions, macros, and global variables.
  79
  80 * Obstacks::           Object Stacks.
  81
  82 * Licenses::           The various licenses under which libiberty sources are
  83                        distributed.
  84
  85 * Index::              Index of functions and categories.
  86 @end menu
  87
  88 @node Using,Overview,Top,Top
  89 @chapter Using
  90 @cindex using libiberty
  91 @cindex libiberty usage
  92 @cindex how to use
  93
  94 @c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY.
  95
  96 To date, @libib{} is generally not installed on its own.  It has evolved
  97 over years but does not have its own version number nor release schedule.
  98
  99 Possibly the easiest way to use @libib{} in your projects is to drop the
 100 @libib{} code into your project's sources, and to build the library along
 101 with your own sources; the library would then be linked in at the end.  This
 102 prevents any possible version mismatches with other copies of libiberty
 103 elsewhere on the system.
 104
 105 Passing @option{--enable-install-libiberty} to the @command{configure}
 106 script when building @libib{} causes the header files and archive library
 107 to be installed when @samp{make install} is run.  This option also takes
 108 an (optional) argument to specify the installation location, in the same
 109 manner as @option{--prefix}.
 110
 111 For your own projects, an approach which offers stability and flexibility
 112 is to include @libib{} with your code, but allow the end user to optionally
 113 choose to use a previously-installed version instead.  In this way the
 114 user may choose (for example) to install @libib{} as part of GCC, and use
 115 that version for all software built with that compiler.  (This approach
 116 has proven useful with software using the GNU @code{readline} library.)
 117
 118 Making use of @libib{} code usually requires that you include one or more
 119 header files from the @libib{} distribution.  (They will be named as
 120 necessary in the function descriptions.)  At link time, you will need to
 121 add @option{-liberty} to your link command invocation.
 122
 123
 124 @node Overview,Functions,Using,Top
 125 @chapter Overview
 126
 127 Functions contained in @libib{} can be divided into three general categories.
 128
 129
 130 @menu
 131 * Supplemental Functions::       Providing functions which don't exist
 132                                  on older operating systems.
 133
 134 * Replacement Functions::        These functions are sometimes buggy or
 135                                  unpredictable on some operating systems.
 136
 137 * Extensions::                   Functions which provide useful extensions
 138                                  or safety wrappers around existing code.
 139 @end menu
 140
 141 @node Supplemental Functions,Replacement Functions,,Overview
 142 @section Supplemental Functions
 143 @cindex supplemental functions
 144 @cindex functions, supplemental
 145 @cindex functions, missing
 146
 147 Certain operating systems do not provide functions which have since
 148 become standardized, or at least common.  For example, the Single
 149 Unix Specification Version 2 requires that the @code{basename}
 150 function be provided, but an OS which predates that specification
 151 might not have this function.  This should not prevent well-written
 152 code from running on such a system.
 153
 154 Similarly, some functions exist only among a particular ``flavor''
 155 or ``family'' of operating systems.  As an example, the @code{bzero}
 156 function is often not present on systems outside the BSD-derived
 157 family of systems.
 158
 159 Many such functions are provided in @libib{}.  They are quickly
 160 listed here with little description, as systems which lack them
 161 become less and less common.  Each function @var{foo} is implemented
 162 in @file{foo.c} but not declared in any @libib{} header file; more
 163 comments and caveats for each function's implementation are often
 164 available in the source file.  Generally, the function can simply
 165 be declared as @code{extern}.
 166
 167
 168
 169 @node Replacement Functions,Extensions,Supplemental Functions,Overview
 170 @section Replacement Functions
 171 @cindex replacement functions
 172 @cindex functions, replacement
 173
 174 Some functions have extremely limited implementations on different
 175 platforms.  Other functions are tedious to use correctly; for example,
 176 proper use of @code{malloc} calls for the return value to be checked and
 177 appropriate action taken if memory has been exhausted.  A group of
 178 ``replacement functions'' is available in @libib{} to address these issues
 179 for some of the most commonly used subroutines.
 180
 181 All of these functions are declared in the @file{libiberty.h} header
 182 file.  Many of the implementations will use preprocessor macros set by
 183 GNU Autoconf, if you decide to make use of that program.  Some of these
 184 functions may call one another.
 185
 186
 187 @menu
 188 * Memory Allocation::            Testing and handling failed memory
 189                                    requests automatically.
 190 * Exit Handlers::                Calling routines on program exit.
 191 * Error Reporting::              Mapping errno and signal numbers to
 192                                    more useful string formats.
 193 @end menu
 194
 195 @node Memory Allocation
 196 @subsection Memory Allocation
 197 @cindex memory allocation
 198
 199 The functions beginning with the letter `x' are wrappers around
 200 standard functions; the functions provided by the system environment
 201 are called and their results checked before the results are passed back
 202 to client code.  If the standard functions fail, these wrappers will
 203 terminate the program.  Thus, these versions can be used with impunity.
 204
 205
 206 @node Exit Handlers
 207 @subsection Exit Handlers
 208 @cindex exit handlers
 209
 210 The existence and implementation of the @code{atexit} routine varies
 211 amongst the flavors of Unix.  @libib{} provides an unvarying dependable
 212 implementation via @code{xatexit} and @code{xexit}.
 213
 214
 215 @node Error Reporting
 216 @subsection Error Reporting
 217 @cindex error reporting
 218
 219 These are a set of routines to facilitate programming with the system
 220 @code{errno} interface.  The @libib{} source file @file{strerror.c}
 221 contains a good deal of documentation for these functions.
 222
 223 @c signal stuff
 224
 225
 226 @node Extensions,,Replacement Functions,Overview
 227 @section Extensions
 228 @cindex extensions
 229 @cindex functions, extension
 230
 231 @libib{} includes additional functionality above and beyond standard
 232 functions, which has proven generically useful in GNU programs, such as
 233 obstacks and regex.  These functions are often copied from other
 234 projects as they gain popularity, and are included here to provide a
 235 central location from which to use, maintain, and distribute them.
 236
 237 @menu
 238 * Obstacks::                     Stacks of arbitrary objects.
 239 @end menu
 240
 241
 242 @node Functions,Obstacks,Overview,Top
 243 @chapter Function, Variable, and Macro Listing.
 244 @include functions.texi
 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
 251 @node Licenses,Index,Obstacks,Top
 252 @appendix Licenses
 253
 254 @menu
 255
 256 * Library Copying::   The GNU Libary General Public License
 257 * BSD::               Regents of the University of California
 258
 259 @end menu
 260
 261 @c This takes care of Library Copying.  It is the copying-lib.texi from the
 262 @c GNU website, with its @node line altered to make makeinfo shut up.
 263 @include copying-lib.texi
 264
 265 @page
 266 @node BSD,,,Licenses
 267 @appendixsec BSD
 268
 269 Copyright @copyright{} 1990 Regents of the University of California.
 270 All rights reserved.
 271
 272 Redistribution and use in source and binary forms, with or without
 273 modification, are permitted provided that the following conditions
 274 are met:
 275
 276 @enumerate
 277
 278 @item
 279 Redistributions of source code must retain the above copyright
 280 notice, this list of conditions and the following disclaimer.
 281
 282 @item
 283 Redistributions in binary form must reproduce the above copyright
 284 notice, this list of conditions and the following disclaimer in the
 285 documentation and/or other materials provided with the distribution.
 286
 287 @item
 288 [rescinded 22 July 1999]
 289
 290 @item
 291 Neither the name of the University nor the names of its contributors
 292 may be used to endorse or promote products derived from this software
 293 without specific prior written permission.
 294
 295 @end enumerate
 296
 297 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 298 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 299 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 300 ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 301 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 302 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 303 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 304 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 305 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 306 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 307 SUCH DAMAGE.
 308
 309 @node    Index,,Licenses,Top
 310 @unnumbered Index
 311
 312 @printindex cp
 313
 314 @contents
 315 @bye
 316