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