mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-12-15 04:31:49 +08:00
a2c5833233
The result of running etc/update-copyright.py --this-year, fixing all the files whose mode is changed by the script, plus a build with --enable-maintainer-mode --enable-cgen-maint=yes, then checking out */po/*.pot which we don't update frequently. The copy of cgen was with commit d1dd5fcc38ead reverted as that commit breaks building of bfp opcodes files.
314 lines
10 KiB
Plaintext
314 lines
10 KiB
Plaintext
\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
|
|
|