313 lines
10 KiB
Text
313 lines
10 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename libiberty.info
|
|
@settitle @sc{gnu} libiberty
|
|
@c %**end of header
|
|
|
|
@syncodeindex fn cp
|
|
@syncodeindex vr cp
|
|
@syncodeindex pg cp
|
|
|
|
@finalout
|
|
@c %**end of header
|
|
|
|
@dircategory GNU libraries
|
|
@direntry
|
|
* Libiberty: (libiberty). Library of utility functions which
|
|
are missing or broken on some systems.
|
|
@end direntry
|
|
|
|
@macro libib
|
|
@code{libiberty}
|
|
@end macro
|
|
|
|
@ifinfo
|
|
This manual describes the GNU @libib library of utility subroutines.
|
|
|
|
Copyright @copyright{} 2001-2022 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries a copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
@end ifinfo
|
|
|
|
|
|
@titlepage
|
|
@title @sc{gnu} libiberty
|
|
@author Phil Edwards et al.
|
|
@page
|
|
|
|
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 2001-2022 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
|
|
@end titlepage
|
|
@contents
|
|
@page
|
|
|
|
@ifnottex
|
|
@node Top,Using,,
|
|
@top Introduction
|
|
|
|
The @libib{} library is a collection of subroutines used by various
|
|
GNU programs. It is available under the Library General Public
|
|
License; for more information, see @ref{Library Copying}.
|
|
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Using:: How to use libiberty in your code.
|
|
|
|
* Overview:: Overview of available function groups.
|
|
|
|
* Functions:: Available functions, macros, and global variables.
|
|
|
|
* Licenses:: The various licenses under which libiberty sources are
|
|
distributed.
|
|
|
|
* Index:: Index of functions and categories.
|
|
@end menu
|
|
|
|
@node Using
|
|
@chapter Using
|
|
@cindex using libiberty
|
|
@cindex libiberty usage
|
|
@cindex how to use
|
|
|
|
@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY.
|
|
|
|
To date, @libib{} is generally not installed on its own. It has evolved
|
|
over years but does not have its own version number nor release schedule.
|
|
|
|
Possibly the easiest way to use @libib{} in your projects is to drop the
|
|
@libib{} code into your project's sources, and to build the library along
|
|
with your own sources; the library would then be linked in at the end. This
|
|
prevents any possible version mismatches with other copies of libiberty
|
|
elsewhere on the system.
|
|
|
|
Passing @option{--enable-install-libiberty} to the @command{configure}
|
|
script when building @libib{} causes the header files and archive library
|
|
to be installed when @kbd{make install} is run. This option also takes
|
|
an (optional) argument to specify the installation location, in the same
|
|
manner as @option{--prefix}.
|
|
|
|
For your own projects, an approach which offers stability and flexibility
|
|
is to include @libib{} with your code, but allow the end user to optionally
|
|
choose to use a previously-installed version instead. In this way the
|
|
user may choose (for example) to install @libib{} as part of GCC, and use
|
|
that version for all software built with that compiler. (This approach
|
|
has proven useful with software using the GNU @code{readline} library.)
|
|
|
|
Making use of @libib{} code usually requires that you include one or more
|
|
header files from the @libib{} distribution. (They will be named as
|
|
necessary in the function descriptions.) At link time, you will need to
|
|
add @option{-liberty} to your link command invocation.
|
|
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
Functions contained in @libib{} can be divided into three general categories.
|
|
|
|
|
|
@menu
|
|
* Supplemental Functions:: Providing functions which don't exist
|
|
on older operating systems.
|
|
|
|
* Replacement Functions:: These functions are sometimes buggy or
|
|
unpredictable on some operating systems.
|
|
|
|
* Extensions:: Functions which provide useful extensions
|
|
or safety wrappers around existing code.
|
|
@end menu
|
|
|
|
@node Supplemental Functions
|
|
@section Supplemental Functions
|
|
@cindex supplemental functions
|
|
@cindex functions, supplemental
|
|
@cindex functions, missing
|
|
|
|
Certain operating systems do not provide functions which have since
|
|
become standardized, or at least common. For example, the Single
|
|
Unix Specification Version 2 requires that the @code{basename}
|
|
function be provided, but an OS which predates that specification
|
|
might not have this function. This should not prevent well-written
|
|
code from running on such a system.
|
|
|
|
Similarly, some functions exist only among a particular ``flavor''
|
|
or ``family'' of operating systems. As an example, the @code{bzero}
|
|
function is often not present on systems outside the BSD-derived
|
|
family of systems.
|
|
|
|
Many such functions are provided in @libib{}. They are quickly
|
|
listed here with little description, as systems which lack them
|
|
become less and less common. Each function @var{foo} is implemented
|
|
in @file{@var{foo}.c} but not declared in any @libib{} header file; more
|
|
comments and caveats for each function's implementation are often
|
|
available in the source file. Generally, the function can simply
|
|
be declared as @code{extern}.
|
|
|
|
|
|
|
|
@node Replacement Functions
|
|
@section Replacement Functions
|
|
@cindex replacement functions
|
|
@cindex functions, replacement
|
|
|
|
Some functions have extremely limited implementations on different
|
|
platforms. Other functions are tedious to use correctly; for example,
|
|
proper use of @code{malloc} calls for the return value to be checked and
|
|
appropriate action taken if memory has been exhausted. A group of
|
|
``replacement functions'' is available in @libib{} to address these issues
|
|
for some of the most commonly used subroutines.
|
|
|
|
All of these functions are declared in the @file{libiberty.h} header
|
|
file. Many of the implementations will use preprocessor macros set by
|
|
GNU Autoconf, if you decide to make use of that program. Some of these
|
|
functions may call one another.
|
|
|
|
|
|
@menu
|
|
* Memory Allocation:: Testing and handling failed memory
|
|
requests automatically.
|
|
* Exit Handlers:: Calling routines on program exit.
|
|
* Error Reporting:: Mapping errno and signal numbers to
|
|
more useful string formats.
|
|
@end menu
|
|
|
|
@node Memory Allocation
|
|
@subsection Memory Allocation
|
|
@cindex memory allocation
|
|
|
|
The functions beginning with the letter @samp{x} are wrappers around
|
|
standard functions; the functions provided by the system environment
|
|
are called and their results checked before the results are passed back
|
|
to client code. If the standard functions fail, these wrappers will
|
|
terminate the program. Thus, these versions can be used with impunity.
|
|
|
|
|
|
@node Exit Handlers
|
|
@subsection Exit Handlers
|
|
@cindex exit handlers
|
|
|
|
The existence and implementation of the @code{atexit} routine varies
|
|
amongst the flavors of Unix. @libib{} provides an unvarying dependable
|
|
implementation via @code{xatexit} and @code{xexit}.
|
|
|
|
|
|
@node Error Reporting
|
|
@subsection Error Reporting
|
|
@cindex error reporting
|
|
|
|
These are a set of routines to facilitate programming with the system
|
|
@code{errno} interface. The @libib{} source file @file{strerror.c}
|
|
contains a good deal of documentation for these functions.
|
|
|
|
@c signal stuff
|
|
|
|
|
|
@node Extensions
|
|
@section Extensions
|
|
@cindex extensions
|
|
@cindex functions, extension
|
|
|
|
@libib{} includes additional functionality above and beyond standard
|
|
functions, which has proven generically useful in GNU programs, such as
|
|
obstacks and regex. These functions are often copied from other
|
|
projects as they gain popularity, and are included here to provide a
|
|
central location from which to use, maintain, and distribute them.
|
|
|
|
@menu
|
|
* Obstacks:: Stacks of arbitrary objects.
|
|
@end menu
|
|
|
|
@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl
|
|
@include obstacks.texi
|
|
|
|
@node Functions
|
|
@chapter Function, Variable, and Macro Listing.
|
|
@include functions.texi
|
|
|
|
@node Licenses
|
|
@appendix Licenses
|
|
|
|
@menu
|
|
|
|
* Library Copying:: The GNU Library General Public License
|
|
* BSD:: Regents of the University of California
|
|
|
|
@end menu
|
|
|
|
@c This takes care of Library Copying. It is the copying-lib.texi from the
|
|
@c GNU web site, with its @node line altered to make makeinfo shut up.
|
|
@include copying-lib.texi
|
|
|
|
@page
|
|
@node BSD
|
|
@appendixsec BSD
|
|
|
|
Copyright @copyright{} 1990 Regents of the University of California.
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
@item
|
|
Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
|
|
@item
|
|
[rescinded 22 July 1999]
|
|
|
|
@item
|
|
Neither the name of the University nor the names of its contributors
|
|
may be used to endorse or promote products derived from this software
|
|
without specific prior written permission.
|
|
|
|
@end enumerate
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
SUCH DAMAGE.
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@bye
|
|
|