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