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 contrib/make-obstacks-texi.pl 245 @include obstacks.texi 246 247 @node Functions 248 @chapter Function, Variable, and Macro Listing. 249 @include functions.texi 250 251 @node Licenses 252 @appendix Licenses 253 254 @menu 255 256 * Library Copying:: The GNU Library 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 web site, with its @node line altered to make makeinfo shut up. 263 @include copying-lib.texi 264 265 @page 266 @node BSD 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 310 @unnumbered Index 311 312 @printindex cp 313 314 @bye 315 316
