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