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* 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 99To date, @libib{} is generally not installed on its own. It has evolved 100over years but does not have its own version number nor release schedule. 101 102Possibly 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 104with your own sources; the library would then be linked in at the end. This 105prevents any possible version mismatches with other copies of libiberty 106elsewhere on the system. 107 108Passing @option{--enable-install-libiberty} to the @command{configure} 109script when building @libib{} causes the header files and archive library 110to be installed when @kbd{make install} is run. This option also takes 111an (optional) argument to specify the installation location, in the same 112manner as @option{--prefix}. 113 114For your own projects, an approach which offers stability and flexibility 115is to include @libib{} with your code, but allow the end user to optionally 116choose to use a previously-installed version instead. In this way the 117user may choose (for example) to install @libib{} as part of GCC, and use 118that version for all software built with that compiler. (This approach 119has proven useful with software using the GNU @code{readline} library.) 120 121Making use of @libib{} code usually requires that you include one or more 122header files from the @libib{} distribution. (They will be named as 123necessary in the function descriptions.) At link time, you will need to 124add @option{-liberty} to your link command invocation. 125 126 127@node Overview 128@chapter Overview 129 130Functions 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 150Certain operating systems do not provide functions which have since 151become standardized, or at least common. For example, the Single 152Unix Specification Version 2 requires that the @code{basename} 153function be provided, but an OS which predates that specification 154might not have this function. This should not prevent well-written 155code from running on such a system. 156 157Similarly, some functions exist only among a particular ``flavor'' 158or ``family'' of operating systems. As an example, the @code{bzero} 159function is often not present on systems outside the BSD-derived 160family of systems. 161 162Many such functions are provided in @libib{}. They are quickly 163listed here with little description, as systems which lack them 164become less and less common. Each function @var{foo} is implemented 165in @file{@var{foo}.c} but not declared in any @libib{} header file; more 166comments and caveats for each function's implementation are often 167available in the source file. Generally, the function can simply 168be declared as @code{extern}. 169 170 171 172@node Replacement Functions 173@section Replacement Functions 174@cindex replacement functions 175@cindex functions, replacement 176 177Some functions have extremely limited implementations on different 178platforms. Other functions are tedious to use correctly; for example, 179proper use of @code{malloc} calls for the return value to be checked and 180appropriate action taken if memory has been exhausted. A group of 181``replacement functions'' is available in @libib{} to address these issues 182for some of the most commonly used subroutines. 183 184All of these functions are declared in the @file{libiberty.h} header 185file. Many of the implementations will use preprocessor macros set by 186GNU Autoconf, if you decide to make use of that program. Some of these 187functions 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 202The functions beginning with the letter @samp{x} are wrappers around 203standard functions; the functions provided by the system environment 204are called and their results checked before the results are passed back 205to client code. If the standard functions fail, these wrappers will 206terminate 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 213The existence and implementation of the @code{atexit} routine varies 214amongst the flavors of Unix. @libib{} provides an unvarying dependable 215implementation via @code{xatexit} and @code{xexit}. 216 217 218@node Error Reporting 219@subsection Error Reporting 220@cindex error reporting 221 222These are a set of routines to facilitate programming with the system 223@code{errno} interface. The @libib{} source file @file{strerror.c} 224contains 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 235functions, which has proven generically useful in GNU programs, such as 236obstacks and regex. These functions are often copied from other 237projects as they gain popularity, and are included here to provide a 238central 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 269Copyright @copyright{} 1990 Regents of the University of California. 270All rights reserved. 271 272Redistribution and use in source and binary forms, with or without 273modification, are permitted provided that the following conditions 274are met: 275 276@enumerate 277 278@item 279Redistributions of source code must retain the above copyright 280notice, this list of conditions and the following disclaimer. 281 282@item 283Redistributions in binary form must reproduce the above copyright 284notice, this list of conditions and the following disclaimer in the 285documentation and/or other materials provided with the distribution. 286 287@item 288[rescinded 22 July 1999] 289 290@item 291Neither the name of the University nor the names of its contributors 292may be used to endorse or promote products derived from this software 293without specific prior written permission. 294 295@end enumerate 296 297THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 298ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 299IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 300ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 301FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 302DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 303OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 304HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 305LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 306OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 307SUCH DAMAGE. 308 309@node Index 310@unnumbered Index 311 312@printindex cp 313 314@bye 315 316