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