189857Sobrien\input texinfo @c -*-texinfo-*- 289857Sobrien@c %**start of header 389857Sobrien@setfilename libiberty.info 489857Sobrien@settitle @sc{gnu} libiberty 589857Sobrien@c %**end of header 689857Sobrien 789857Sobrien@syncodeindex fn cp 889857Sobrien@syncodeindex vr cp 989857Sobrien@syncodeindex pg cp 1089857Sobrien 1189857Sobrien@finalout 1289857Sobrien@c %**end of header 1389857Sobrien 1489857Sobrien@dircategory GNU libraries 1589857Sobrien@direntry 1689857Sobrien* Libiberty: (libiberty). Library of utility functions which 1789857Sobrien are missing or broken on some systems. 1889857Sobrien@end direntry 1989857Sobrien 2089857Sobrien@macro libib 2189857Sobrien@code{libiberty} 2289857Sobrien@end macro 2389857Sobrien 2489857Sobrien@c The edition date is written in three locations. Search for 'thedate'. 2589857Sobrien@ifinfo 2689857SobrienThis manual describes the GNU @libib library of utility subroutines. 2789857SobrienThis edition accompanies GCC 3, September 2001. 2889857Sobrien 2989857SobrienCopyright @copyright{} 2001 Free Software Foundation, Inc. 3089857Sobrien 3189857Sobrien Permission is granted to copy, distribute and/or modify this document 32130561Sobrien under the terms of the GNU Free Documentation License, Version 1.2 3389857Sobrien or any later version published by the Free Software Foundation; 3489857Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 3589857Sobrien Back-Cover Texts. A copy of the license is included in the 3689857Sobrien section entitled ``GNU Free Documentation License''. 3789857Sobrien 3889857Sobrien@ignore 3989857SobrienPermission is granted to process this file through TeX and print the 4089857Sobrienresults, provided the printed document carries a copying permission 4189857Sobriennotice identical to this one except for the removal of this paragraph 4289857Sobrien(this paragraph not being relevant to the printed manual). 4389857Sobrien 4489857Sobrien@end ignore 4589857Sobrien@end ifinfo 4689857Sobrien 4789857Sobrien 4889857Sobrien@c The edition date is written in three locations. Search for 'thedate'. 4989857Sobrien@titlepage 5089857Sobrien@title @sc{gnu} libiberty 5189857Sobrien@subtitle September 2001 5289857Sobrien@subtitle for GCC 3 5389857Sobrien@author Phil Edwards et al. 5489857Sobrien@page 5589857Sobrien 5689857Sobrien 5789857Sobrien@vskip 0pt plus 1filll 5889857SobrienCopyright @copyright{} 2001 Free Software Foundation, Inc. 5989857Sobrien 6089857Sobrien Permission is granted to copy, distribute and/or modify this document 61130561Sobrien under the terms of the GNU Free Documentation License, Version 1.2 6289857Sobrien or any later version published by the Free Software Foundation; 6389857Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 6489857Sobrien Back-Cover Texts. A copy of the license is included in the 6589857Sobrien section entitled ``GNU Free Documentation License''. 6689857Sobrien 6789857Sobrien@end titlepage 6889857Sobrien@contents 6989857Sobrien@page 7089857Sobrien 7189857Sobrien@ifnottex 7289857Sobrien@node Top,Using,, 7389857Sobrien@top Introduction 7489857Sobrien 7589857SobrienThe @libib{} library is a collection of subroutines used by various 7689857SobrienGNU programs. It is available under the Library General Public 7789857SobrienLicense; for more information, see @ref{Library Copying}. 7889857Sobrien 7989857Sobrien@c The edition date is written in three locations. Search for 'thedate'. 8089857SobrienThis edition accompanies GCC 3, September 2001. 8189857Sobrien 8289857Sobrien@end ifnottex 8389857Sobrien 8489857Sobrien@menu 8589857Sobrien* Using:: How to use libiberty in your code. 8689857Sobrien 8789857Sobrien* Overview:: Overview of available function groups. 8889857Sobrien 8989857Sobrien* Functions:: Available functions, macros, and global variables. 9089857Sobrien 9189857Sobrien* Obstacks:: Object Stacks. 9289857Sobrien 9389857Sobrien* Licenses:: The various licenses under which libiberty sources are 9489857Sobrien distributed. 9589857Sobrien 9689857Sobrien* Index:: Index of functions and categories. 9789857Sobrien@end menu 9889857Sobrien 9989857Sobrien@node Using 10089857Sobrien@chapter Using 10189857Sobrien@cindex using libiberty 10289857Sobrien@cindex libiberty usage 10389857Sobrien@cindex how to use 10489857Sobrien 10589857Sobrien@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY. 10689857Sobrien 10789857SobrienTo date, @libib{} is generally not installed on its own. It has evolved 10889857Sobrienover years but does not have its own version number nor release schedule. 10989857Sobrien 11089857SobrienPossibly the easiest way to use @libib{} in your projects is to drop the 11189857Sobrien@libib{} code into your project's sources, and to build the library along 11289857Sobrienwith your own sources; the library would then be linked in at the end. This 11389857Sobrienprevents any possible version mismatches with other copies of libiberty 11489857Sobrienelsewhere on the system. 11589857Sobrien 11689857SobrienPassing @option{--enable-install-libiberty} to the @command{configure} 11789857Sobrienscript when building @libib{} causes the header files and archive library 11889857Sobriento be installed when @kbd{make install} is run. This option also takes 11989857Sobrienan (optional) argument to specify the installation location, in the same 12089857Sobrienmanner as @option{--prefix}. 12189857Sobrien 12289857SobrienFor your own projects, an approach which offers stability and flexibility 12389857Sobrienis to include @libib{} with your code, but allow the end user to optionally 12489857Sobrienchoose to use a previously-installed version instead. In this way the 12589857Sobrienuser may choose (for example) to install @libib{} as part of GCC, and use 12689857Sobrienthat version for all software built with that compiler. (This approach 12789857Sobrienhas proven useful with software using the GNU @code{readline} library.) 12889857Sobrien 12989857SobrienMaking use of @libib{} code usually requires that you include one or more 13089857Sobrienheader files from the @libib{} distribution. (They will be named as 13189857Sobriennecessary in the function descriptions.) At link time, you will need to 13289857Sobrienadd @option{-liberty} to your link command invocation. 13389857Sobrien 13489857Sobrien 13589857Sobrien@node Overview 13689857Sobrien@chapter Overview 13789857Sobrien 13889857SobrienFunctions contained in @libib{} can be divided into three general categories. 13989857Sobrien 14089857Sobrien 14189857Sobrien@menu 14289857Sobrien* Supplemental Functions:: Providing functions which don't exist 14389857Sobrien on older operating systems. 14489857Sobrien 14589857Sobrien* Replacement Functions:: These functions are sometimes buggy or 14689857Sobrien unpredictable on some operating systems. 14789857Sobrien 14889857Sobrien* Extensions:: Functions which provide useful extensions 14989857Sobrien or safety wrappers around existing code. 15089857Sobrien@end menu 15189857Sobrien 15289857Sobrien@node Supplemental Functions 15389857Sobrien@section Supplemental Functions 15489857Sobrien@cindex supplemental functions 15589857Sobrien@cindex functions, supplemental 15689857Sobrien@cindex functions, missing 15789857Sobrien 15889857SobrienCertain operating systems do not provide functions which have since 15989857Sobrienbecome standardized, or at least common. For example, the Single 16089857SobrienUnix Specification Version 2 requires that the @code{basename} 16189857Sobrienfunction be provided, but an OS which predates that specification 16289857Sobrienmight not have this function. This should not prevent well-written 16389857Sobriencode from running on such a system. 16489857Sobrien 16589857SobrienSimilarly, some functions exist only among a particular ``flavor'' 16689857Sobrienor ``family'' of operating systems. As an example, the @code{bzero} 16789857Sobrienfunction is often not present on systems outside the BSD-derived 16889857Sobrienfamily of systems. 16989857Sobrien 17089857SobrienMany such functions are provided in @libib{}. They are quickly 17189857Sobrienlisted here with little description, as systems which lack them 17289857Sobrienbecome less and less common. Each function @var{foo} is implemented 17389857Sobrienin @file{@var{foo}.c} but not declared in any @libib{} header file; more 17489857Sobriencomments and caveats for each function's implementation are often 17589857Sobrienavailable in the source file. Generally, the function can simply 17689857Sobrienbe declared as @code{extern}. 17789857Sobrien 17889857Sobrien 17989857Sobrien 18089857Sobrien@node Replacement Functions 18189857Sobrien@section Replacement Functions 18289857Sobrien@cindex replacement functions 18389857Sobrien@cindex functions, replacement 18489857Sobrien 18589857SobrienSome functions have extremely limited implementations on different 18689857Sobrienplatforms. Other functions are tedious to use correctly; for example, 18789857Sobrienproper use of @code{malloc} calls for the return value to be checked and 18889857Sobrienappropriate action taken if memory has been exhausted. A group of 18989857Sobrien``replacement functions'' is available in @libib{} to address these issues 19089857Sobrienfor some of the most commonly used subroutines. 19189857Sobrien 19289857SobrienAll of these functions are declared in the @file{libiberty.h} header 19389857Sobrienfile. Many of the implementations will use preprocessor macros set by 19489857SobrienGNU Autoconf, if you decide to make use of that program. Some of these 19589857Sobrienfunctions may call one another. 19689857Sobrien 19789857Sobrien 19889857Sobrien@menu 19989857Sobrien* Memory Allocation:: Testing and handling failed memory 20089857Sobrien requests automatically. 20189857Sobrien* Exit Handlers:: Calling routines on program exit. 20289857Sobrien* Error Reporting:: Mapping errno and signal numbers to 20389857Sobrien more useful string formats. 20489857Sobrien@end menu 20589857Sobrien 20689857Sobrien@node Memory Allocation 20789857Sobrien@subsection Memory Allocation 20889857Sobrien@cindex memory allocation 20989857Sobrien 21089857SobrienThe functions beginning with the letter @samp{x} are wrappers around 21189857Sobrienstandard functions; the functions provided by the system environment 21289857Sobrienare called and their results checked before the results are passed back 21389857Sobriento client code. If the standard functions fail, these wrappers will 21489857Sobrienterminate the program. Thus, these versions can be used with impunity. 21589857Sobrien 21689857Sobrien 21789857Sobrien@node Exit Handlers 21889857Sobrien@subsection Exit Handlers 21989857Sobrien@cindex exit handlers 22089857Sobrien 22189857SobrienThe existence and implementation of the @code{atexit} routine varies 22289857Sobrienamongst the flavors of Unix. @libib{} provides an unvarying dependable 22389857Sobrienimplementation via @code{xatexit} and @code{xexit}. 22489857Sobrien 22589857Sobrien 22689857Sobrien@node Error Reporting 22789857Sobrien@subsection Error Reporting 22889857Sobrien@cindex error reporting 22989857Sobrien 23089857SobrienThese are a set of routines to facilitate programming with the system 23189857Sobrien@code{errno} interface. The @libib{} source file @file{strerror.c} 23289857Sobriencontains a good deal of documentation for these functions. 23389857Sobrien 23489857Sobrien@c signal stuff 23589857Sobrien 23689857Sobrien 23789857Sobrien@node Extensions 23889857Sobrien@section Extensions 23989857Sobrien@cindex extensions 24089857Sobrien@cindex functions, extension 24189857Sobrien 24289857Sobrien@libib{} includes additional functionality above and beyond standard 24389857Sobrienfunctions, which has proven generically useful in GNU programs, such as 24489857Sobrienobstacks and regex. These functions are often copied from other 24589857Sobrienprojects as they gain popularity, and are included here to provide a 24689857Sobriencentral location from which to use, maintain, and distribute them. 24789857Sobrien 24889857Sobrien@menu 24989857Sobrien* Obstacks:: Stacks of arbitrary objects. 25089857Sobrien@end menu 25189857Sobrien 25289857Sobrien@c This is generated from the glibc manual using a make-obstacks-texi.sh 25389857Sobrien@c script of Phil's. Hope it's accurate. 25489857Sobrien@include obstacks.texi 25589857Sobrien 25689857Sobrien@node Functions 25789857Sobrien@chapter Function, Variable, and Macro Listing. 25889857Sobrien@include functions.texi 25989857Sobrien 26089857Sobrien@node Licenses 26189857Sobrien@appendix Licenses 26289857Sobrien 26389857Sobrien@menu 26489857Sobrien 26589857Sobrien* Library Copying:: The GNU Library General Public License 26689857Sobrien* BSD:: Regents of the University of California 26789857Sobrien 26889857Sobrien@end menu 26989857Sobrien 27089857Sobrien@c This takes care of Library Copying. It is the copying-lib.texi from the 27189857Sobrien@c GNU web site, with its @node line altered to make makeinfo shut up. 27289857Sobrien@include copying-lib.texi 27389857Sobrien 27489857Sobrien@page 27589857Sobrien@node BSD 27689857Sobrien@appendixsec BSD 27789857Sobrien 27889857SobrienCopyright @copyright{} 1990 Regents of the University of California. 27989857SobrienAll rights reserved. 28089857Sobrien 28189857SobrienRedistribution and use in source and binary forms, with or without 28289857Sobrienmodification, are permitted provided that the following conditions 28389857Sobrienare met: 28489857Sobrien 28589857Sobrien@enumerate 28689857Sobrien 28789857Sobrien@item 28889857SobrienRedistributions of source code must retain the above copyright 28989857Sobriennotice, this list of conditions and the following disclaimer. 29089857Sobrien 29189857Sobrien@item 29289857SobrienRedistributions in binary form must reproduce the above copyright 29389857Sobriennotice, this list of conditions and the following disclaimer in the 29489857Sobriendocumentation and/or other materials provided with the distribution. 29589857Sobrien 29689857Sobrien@item 29789857Sobrien[rescinded 22 July 1999] 29889857Sobrien 29989857Sobrien@item 30089857SobrienNeither the name of the University nor the names of its contributors 30189857Sobrienmay be used to endorse or promote products derived from this software 30289857Sobrienwithout specific prior written permission. 30389857Sobrien 30489857Sobrien@end enumerate 30589857Sobrien 30689857SobrienTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 30789857SobrienANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 30889857SobrienIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 30989857SobrienARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 31089857SobrienFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31189857SobrienDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31289857SobrienOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31389857SobrienHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31489857SobrienLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31589857SobrienOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31689857SobrienSUCH DAMAGE. 31789857Sobrien 318218822Sdim@node Index 31989857Sobrien@unnumbered Index 32089857Sobrien 32189857Sobrien@printindex cp 32289857Sobrien 32389857Sobrien@bye 32489857Sobrien 325