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