This manual describes the GNU libiberty library of utility subroutines. This edition accompanies GCC 3, September 2001.

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.2 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''.

Introduction
************

The libiberty library is a collection of subroutines used by various GNU programs.  It is available under the Library General Public License; for more information, see Library Copying.

This edition accompanies GCC 3, September 2001.

Using
*****

To date, libiberty 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 libiberty in your projects is to drop the libiberty 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 --enable-install-libiberty to the configure script when building libiberty causes the header files and archive library to be installed when make install is run.  This option also takes an (optional) argument to specify the installation location, in the same manner as --prefix.

For your own projects, an approach which offers stability and flexibility is to include libiberty 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 libiberty 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 readline library.)

Making use of libiberty code usually requires that you include one or more header files from the libiberty distribution.  (They will be named as necessary in the function descriptions.)  At link time, you will need to add -liberty to your link command invocation.

Overview
********

Functions contained in libiberty can be divided into three general categories.

Supplemental Functions
======================

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 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 bzero function is often not present on systems outside the BSD-derived family of systems.

Many such functions are provided in libiberty.  They are quickly listed here with little description, as systems which lack them become less and less common.  Each function FOO is implemented in FOO.c but not declared in any libiberty 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 extern.

Replacement Functions
=====================

Some functions have extremely limited implementations on different platforms.  Other functions are tedious to use correctly; for example, proper use of 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 libiberty to address these issues for some of the most commonly used subroutines.

All of these functions are declared in the 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.

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.

Exit Handlers
-------------

The existence and implementation of the atexit routine varies amongst the flavors of Unix.  libiberty provides an unvarying dependable implementation via xatexit and xexit.

Error Reporting
---------------

These are a set of routines to facilitate programming with the system errno interface.  The libiberty source file strerror.c contains a good deal of documentation for these functions.

Extensions
==========

libiberty 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.

     [file obstacks.texi not included]

Function, Variable, and Macro Listing.
**************************************

     [file functions.texi not included]

Licenses
********

     [file copying-lib.texi not included]

BSD
===

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:

 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

 2. 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.

 3. [rescinded 22 July 1999]

 4. 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.

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.