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