merge from gcc

1 files changed, 316 insertions, 0 deletions

diff --git a/libiberty/libiberty.texi b/libiberty/libiberty.texi
new file mode 100644
index 0000000..9181b0f
--- /dev/null
+++ b/libiberty/libiberty.texi
@@ -0,0 +1,316 @@
+\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
+
+@macro libib
+@code{libiberty}
+@end macro
+
+@c The edition date is written in three locations.  Search for 'thedate'.
+@ifinfo
+This manual describes the GNU @libib library of utility subroutines.
+This edition accompanies GCC 3, September 2001.
+
+Copyright @copyright{} 2001 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.1
+      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
+
+
+@c The edition date is written in three locations.  Search for 'thedate'.
+@titlepage
+@title @sc{gnu} libiberty
+@subtitle September 2001
+@subtitle for GCC 3
+@author Phil Edwards et al.
+@page
+
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2001 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.1
+      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
+
+
+@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}.
+
+@c The edition date is written in three locations.  Search for 'thedate'.
+This edition accompanies GCC 3, September 2001.
+
+@end ifnottex
+
+@menu
+* Using::              How to use libiberty in your code.
+
+* Overview::           Overview of available function groups.
+
+* Functions::          Available functions, macros, and global variables.
+
+* Obstacks::           Object Stacks.
+
+* Licenses::           The various licenses under which libiberty sources are
+                       distributed.
+
+* Index::              Index of functions and categories.
+@end menu
+
+@node Using,Overview,Top,Top
+@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 @samp{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,Functions,Using,Top
+@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,Replacement Functions,,Overview
+@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{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,Extensions,Supplemental Functions,Overview
+@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 `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,,Replacement Functions,Overview
+@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
+
+
+@node Functions,Obstacks,Overview,Top
+@chapter Function, Variable, and Macro Listing.
+@include functions.texi
+
+@c This is generated from the glibc manual using a make-obstacks-texi.sh
+@c script of Phil's.  Hope it's accurate.
+@include obstacks.texi
+
+
+@node Licenses,Index,Obstacks,Top
+@appendix Licenses
+
+@menu
+
+* Library Copying::   The GNU Libary 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 website, with its @node line altered to make makeinfo shut up.
+@include copying-lib.texi
+
+@page
+@node BSD,,,Licenses
+@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,,Licenses,Top
+@unnumbered Index
+
+@printindex cp
+
+@contents
+@bye
+