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