1169695Skan\input texinfo @c -*-texinfo-*- 2169695Skan@c %**start of header 3169695Skan@setfilename libiberty.info 4169695Skan@settitle @sc{gnu} libiberty 5169695Skan@c %**end of header 6169695Skan 7169695Skan@syncodeindex fn cp 8169695Skan@syncodeindex vr cp 9169695Skan@syncodeindex pg cp 10169695Skan 11169695Skan@finalout 12169695Skan@c %**end of header 13169695Skan 14169695Skan@dircategory GNU libraries 15169695Skan@direntry 16169695Skan* Libiberty: (libiberty). Library of utility functions which 17169695Skan are missing or broken on some systems. 18169695Skan@end direntry 19169695Skan 20169695Skan@macro libib 21169695Skan@code{libiberty} 22169695Skan@end macro 23169695Skan 24169695Skan@c The edition date is written in three locations. Search for 'thedate'. 25169695Skan@ifinfo 26169695SkanThis manual describes the GNU @libib library of utility subroutines. 27169695SkanThis edition accompanies GCC 3, September 2001. 28169695Skan 29169695SkanCopyright @copyright{} 2001 Free Software Foundation, Inc. 30169695Skan 31169695Skan Permission is granted to copy, distribute and/or modify this document 32169695Skan under the terms of the GNU Free Documentation License, Version 1.2 33169695Skan or any later version published by the Free Software Foundation; 34169695Skan with no Invariant Sections, with no Front-Cover Texts, and with no 35169695Skan Back-Cover Texts. A copy of the license is included in the 36169695Skan section entitled ``GNU Free Documentation License''. 37169695Skan 38169695Skan@ignore 39169695SkanPermission is granted to process this file through TeX and print the 40169695Skanresults, provided the printed document carries a copying permission 41169695Skannotice identical to this one except for the removal of this paragraph 42169695Skan(this paragraph not being relevant to the printed manual). 43169695Skan 44169695Skan@end ignore 45169695Skan@end ifinfo 46169695Skan 47169695Skan 48169695Skan@c The edition date is written in three locations. Search for 'thedate'. 49169695Skan@titlepage 50169695Skan@title @sc{gnu} libiberty 51169695Skan@subtitle September 2001 52169695Skan@subtitle for GCC 3 53169695Skan@author Phil Edwards et al. 54169695Skan@page 55169695Skan 56169695Skan 57169695Skan@vskip 0pt plus 1filll 58169695SkanCopyright @copyright{} 2001 Free Software Foundation, Inc. 59169695Skan 60169695Skan Permission is granted to copy, distribute and/or modify this document 61169695Skan under the terms of the GNU Free Documentation License, Version 1.2 62169695Skan or any later version published by the Free Software Foundation; 63169695Skan with no Invariant Sections, with no Front-Cover Texts, and with no 64169695Skan Back-Cover Texts. A copy of the license is included in the 65169695Skan section entitled ``GNU Free Documentation License''. 66169695Skan 67169695Skan@end titlepage 68169695Skan@contents 69169695Skan@page 70169695Skan 71169695Skan@ifnottex 72169695Skan@node Top,Using,, 73169695Skan@top Introduction 74169695Skan 75169695SkanThe @libib{} library is a collection of subroutines used by various 76169695SkanGNU programs. It is available under the Library General Public 77169695SkanLicense; for more information, see @ref{Library Copying}. 78169695Skan 79169695Skan@c The edition date is written in three locations. Search for 'thedate'. 80169695SkanThis edition accompanies GCC 3, September 2001. 81169695Skan 82169695Skan@end ifnottex 83169695Skan 84169695Skan@menu 85169695Skan* Using:: How to use libiberty in your code. 86169695Skan 87169695Skan* Overview:: Overview of available function groups. 88169695Skan 89169695Skan* Functions:: Available functions, macros, and global variables. 90169695Skan 91169695Skan* Obstacks:: Object Stacks. 92169695Skan 93169695Skan* Licenses:: The various licenses under which libiberty sources are 94169695Skan distributed. 95169695Skan 96169695Skan* Index:: Index of functions and categories. 97169695Skan@end menu 98169695Skan 99169695Skan@node Using 100169695Skan@chapter Using 101169695Skan@cindex using libiberty 102169695Skan@cindex libiberty usage 103169695Skan@cindex how to use 104169695Skan 105169695Skan@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY. 106169695Skan 107169695SkanTo date, @libib{} is generally not installed on its own. It has evolved 108169695Skanover years but does not have its own version number nor release schedule. 109169695Skan 110169695SkanPossibly the easiest way to use @libib{} in your projects is to drop the 111169695Skan@libib{} code into your project's sources, and to build the library along 112169695Skanwith your own sources; the library would then be linked in at the end. This 113169695Skanprevents any possible version mismatches with other copies of libiberty 114169695Skanelsewhere on the system. 115169695Skan 116169695SkanPassing @option{--enable-install-libiberty} to the @command{configure} 117169695Skanscript when building @libib{} causes the header files and archive library 118169695Skanto be installed when @kbd{make install} is run. This option also takes 119169695Skanan (optional) argument to specify the installation location, in the same 120169695Skanmanner as @option{--prefix}. 121169695Skan 122169695SkanFor your own projects, an approach which offers stability and flexibility 123169695Skanis to include @libib{} with your code, but allow the end user to optionally 124169695Skanchoose to use a previously-installed version instead. In this way the 125169695Skanuser may choose (for example) to install @libib{} as part of GCC, and use 126169695Skanthat version for all software built with that compiler. (This approach 127169695Skanhas proven useful with software using the GNU @code{readline} library.) 128169695Skan 129169695SkanMaking use of @libib{} code usually requires that you include one or more 130169695Skanheader files from the @libib{} distribution. (They will be named as 131169695Skannecessary in the function descriptions.) At link time, you will need to 132169695Skanadd @option{-liberty} to your link command invocation. 133169695Skan 134169695Skan 135169695Skan@node Overview 136169695Skan@chapter Overview 137169695Skan 138169695SkanFunctions contained in @libib{} can be divided into three general categories. 139169695Skan 140169695Skan 141169695Skan@menu 142169695Skan* Supplemental Functions:: Providing functions which don't exist 143169695Skan on older operating systems. 144169695Skan 145169695Skan* Replacement Functions:: These functions are sometimes buggy or 146169695Skan unpredictable on some operating systems. 147169695Skan 148169695Skan* Extensions:: Functions which provide useful extensions 149169695Skan or safety wrappers around existing code. 150169695Skan@end menu 151169695Skan 152169695Skan@node Supplemental Functions 153169695Skan@section Supplemental Functions 154169695Skan@cindex supplemental functions 155169695Skan@cindex functions, supplemental 156169695Skan@cindex functions, missing 157169695Skan 158169695SkanCertain operating systems do not provide functions which have since 159169695Skanbecome standardized, or at least common. For example, the Single 160169695SkanUnix Specification Version 2 requires that the @code{basename} 161169695Skanfunction be provided, but an OS which predates that specification 162169695Skanmight not have this function. This should not prevent well-written 163169695Skancode from running on such a system. 164169695Skan 165169695SkanSimilarly, some functions exist only among a particular ``flavor'' 166169695Skanor ``family'' of operating systems. As an example, the @code{bzero} 167169695Skanfunction is often not present on systems outside the BSD-derived 168169695Skanfamily of systems. 169169695Skan 170169695SkanMany such functions are provided in @libib{}. They are quickly 171169695Skanlisted here with little description, as systems which lack them 172169695Skanbecome less and less common. Each function @var{foo} is implemented 173169695Skanin @file{@var{foo}.c} but not declared in any @libib{} header file; more 174169695Skancomments and caveats for each function's implementation are often 175169695Skanavailable in the source file. Generally, the function can simply 176169695Skanbe declared as @code{extern}. 177169695Skan 178169695Skan 179169695Skan 180169695Skan@node Replacement Functions 181169695Skan@section Replacement Functions 182169695Skan@cindex replacement functions 183169695Skan@cindex functions, replacement 184169695Skan 185169695SkanSome functions have extremely limited implementations on different 186169695Skanplatforms. Other functions are tedious to use correctly; for example, 187169695Skanproper use of @code{malloc} calls for the return value to be checked and 188169695Skanappropriate action taken if memory has been exhausted. A group of 189169695Skan``replacement functions'' is available in @libib{} to address these issues 190169695Skanfor some of the most commonly used subroutines. 191169695Skan 192169695SkanAll of these functions are declared in the @file{libiberty.h} header 193169695Skanfile. Many of the implementations will use preprocessor macros set by 194169695SkanGNU Autoconf, if you decide to make use of that program. Some of these 195169695Skanfunctions may call one another. 196169695Skan 197169695Skan 198169695Skan@menu 199169695Skan* Memory Allocation:: Testing and handling failed memory 200169695Skan requests automatically. 201169695Skan* Exit Handlers:: Calling routines on program exit. 202169695Skan* Error Reporting:: Mapping errno and signal numbers to 203169695Skan more useful string formats. 204169695Skan@end menu 205169695Skan 206169695Skan@node Memory Allocation 207169695Skan@subsection Memory Allocation 208169695Skan@cindex memory allocation 209169695Skan 210169695SkanThe functions beginning with the letter @samp{x} are wrappers around 211169695Skanstandard functions; the functions provided by the system environment 212169695Skanare called and their results checked before the results are passed back 213169695Skanto client code. If the standard functions fail, these wrappers will 214169695Skanterminate the program. Thus, these versions can be used with impunity. 215169695Skan 216169695Skan 217169695Skan@node Exit Handlers 218169695Skan@subsection Exit Handlers 219169695Skan@cindex exit handlers 220169695Skan 221169695SkanThe existence and implementation of the @code{atexit} routine varies 222169695Skanamongst the flavors of Unix. @libib{} provides an unvarying dependable 223169695Skanimplementation via @code{xatexit} and @code{xexit}. 224169695Skan 225169695Skan 226169695Skan@node Error Reporting 227169695Skan@subsection Error Reporting 228169695Skan@cindex error reporting 229169695Skan 230169695SkanThese are a set of routines to facilitate programming with the system 231169695Skan@code{errno} interface. The @libib{} source file @file{strerror.c} 232169695Skancontains a good deal of documentation for these functions. 233169695Skan 234169695Skan@c signal stuff 235169695Skan 236169695Skan 237169695Skan@node Extensions 238169695Skan@section Extensions 239169695Skan@cindex extensions 240169695Skan@cindex functions, extension 241169695Skan 242169695Skan@libib{} includes additional functionality above and beyond standard 243169695Skanfunctions, which has proven generically useful in GNU programs, such as 244169695Skanobstacks and regex. These functions are often copied from other 245169695Skanprojects as they gain popularity, and are included here to provide a 246169695Skancentral location from which to use, maintain, and distribute them. 247169695Skan 248169695Skan@menu 249169695Skan* Obstacks:: Stacks of arbitrary objects. 250169695Skan@end menu 251169695Skan 252169695Skan@c This is generated from the glibc manual using a make-obstacks-texi.sh 253169695Skan@c script of Phil's. Hope it's accurate. 254169695Skan@include obstacks.texi 255169695Skan 256169695Skan@node Functions 257169695Skan@chapter Function, Variable, and Macro Listing. 258169695Skan@include functions.texi 259169695Skan 260169695Skan@node Licenses 261169695Skan@appendix Licenses 262169695Skan 263169695Skan@menu 264169695Skan 265169695Skan* Library Copying:: The GNU Library General Public License 266169695Skan* BSD:: Regents of the University of California 267169695Skan 268169695Skan@end menu 269169695Skan 270169695Skan@c This takes care of Library Copying. It is the copying-lib.texi from the 271169695Skan@c GNU web site, with its @node line altered to make makeinfo shut up. 272169695Skan@include copying-lib.texi 273169695Skan 274169695Skan@page 275169695Skan@node BSD 276169695Skan@appendixsec BSD 277169695Skan 278169695SkanCopyright @copyright{} 1990 Regents of the University of California. 279169695SkanAll rights reserved. 280169695Skan 281169695SkanRedistribution and use in source and binary forms, with or without 282169695Skanmodification, are permitted provided that the following conditions 283169695Skanare met: 284169695Skan 285169695Skan@enumerate 286169695Skan 287169695Skan@item 288169695SkanRedistributions of source code must retain the above copyright 289169695Skannotice, this list of conditions and the following disclaimer. 290169695Skan 291169695Skan@item 292169695SkanRedistributions in binary form must reproduce the above copyright 293169695Skannotice, this list of conditions and the following disclaimer in the 294169695Skandocumentation and/or other materials provided with the distribution. 295169695Skan 296169695Skan@item 297169695Skan[rescinded 22 July 1999] 298169695Skan 299169695Skan@item 300169695SkanNeither the name of the University nor the names of its contributors 301169695Skanmay be used to endorse or promote products derived from this software 302169695Skanwithout specific prior written permission. 303169695Skan 304169695Skan@end enumerate 305169695Skan 306169695SkanTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 307169695SkanANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 308169695SkanIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 309169695SkanARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 310169695SkanFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 311169695SkanDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 312169695SkanOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 313169695SkanHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 314169695SkanLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 315169695SkanOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 316169695SkanSUCH DAMAGE. 317169695Skan 318169695Skan@node Index 319169695Skan@unnumbered Index 320169695Skan 321169695Skan@printindex cp 322169695Skan 323169695Skan@bye 324169695Skan 325