You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3536 lines
184 KiB
HTML
3536 lines
184 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>GNU libiberty</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="GNU libiberty">
|
|
<meta name="generator" content="makeinfo 4.7">
|
|
<link title="Top" rel="top" href="#Top">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family: serif; font-weight: normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<h1 class="settitle">GNU libiberty</h1>
|
|
<div class="contents">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a name="toc_Top" href="#Top">Introduction</a>
|
|
<li><a name="toc_Using" href="#Using">1 Using</a>
|
|
<li><a name="toc_Overview" href="#Overview">2 Overview</a>
|
|
<ul>
|
|
<li><a href="#Supplemental-Functions">2.1 Supplemental Functions</a>
|
|
<li><a href="#Replacement-Functions">2.2 Replacement Functions</a>
|
|
<ul>
|
|
<li><a href="#Memory-Allocation">2.2.1 Memory Allocation</a>
|
|
<li><a href="#Exit-Handlers">2.2.2 Exit Handlers</a>
|
|
<li><a href="#Error-Reporting">2.2.3 Error Reporting</a>
|
|
</li></ul>
|
|
<li><a href="#Extensions">2.3 Extensions</a>
|
|
</li></ul>
|
|
<li><a name="toc_Obstacks" href="#Obstacks">3 Obstacks</a>
|
|
<ul>
|
|
<li><a href="#Creating-Obstacks">3.1 Creating Obstacks</a>
|
|
<li><a href="#Preparing-for-Obstacks">3.2 Preparing for Using Obstacks</a>
|
|
<li><a href="#Allocation-in-an-Obstack">3.3 Allocation in an Obstack</a>
|
|
<li><a href="#Freeing-Obstack-Objects">3.4 Freeing Objects in an Obstack</a>
|
|
<li><a href="#Obstack-Functions">3.5 Obstack Functions and Macros</a>
|
|
<li><a href="#Growing-Objects">3.6 Growing Objects</a>
|
|
<li><a href="#Extra-Fast-Growing">3.7 Extra Fast Growing Objects</a>
|
|
<li><a href="#Status-of-an-Obstack">3.8 Status of an Obstack</a>
|
|
<li><a href="#Obstacks-Data-Alignment">3.9 Alignment of Data in Obstacks</a>
|
|
<li><a href="#Obstack-Chunks">3.10 Obstack Chunks</a>
|
|
<li><a href="#Summary-of-Obstacks">3.11 Summary of Obstack Functions</a>
|
|
</li></ul>
|
|
<li><a name="toc_Functions" href="#Functions">4 Function, Variable, and Macro Listing.</a>
|
|
<li><a name="toc_Licenses" href="#Licenses">Appendix A Licenses</a>
|
|
<ul>
|
|
<li><a href="#Library-Copying">A.1 GNU LESSER GENERAL PUBLIC LICENSE</a>
|
|
<ul>
|
|
<li><a href="#Library-Copying">A.1.1 Preamble</a>
|
|
<li><a href="#Library-Copying">A.1.2 How to Apply These Terms to Your New Libraries</a>
|
|
</li></ul>
|
|
<li><a href="#BSD">A.2 BSD</a>
|
|
</li></ul>
|
|
<li><a name="toc_Index" href="#Index">Index</a>
|
|
</li></ul>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#Using">Using</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="unnumbered">Introduction</h2>
|
|
|
|
<p>The <code>libiberty</code> library is a collection of subroutines used by various
|
|
GNU programs. It is available under the Library General Public
|
|
License; for more information, see <a href="#Library-Copying">Library Copying</a>.
|
|
|
|
<!-- The edition date is written in three locations. Search for 'thedate'. -->
|
|
<p>This edition accompanies GCC 3, September 2001.
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Using">Using</a>: How to use libiberty in your code.
|
|
|
|
<li><a accesskey="2" href="#Overview">Overview</a>: Overview of available function groups.
|
|
|
|
<li><a accesskey="3" href="#Functions">Functions</a>: Available functions, macros, and global variables.
|
|
|
|
<li><a accesskey="4" href="#Obstacks">Obstacks</a>: Object Stacks.
|
|
|
|
<li><a accesskey="5" href="#Licenses">Licenses</a>: The various licenses under which libiberty sources are
|
|
distributed.
|
|
|
|
<li><a accesskey="6" href="#Index">Index</a>: Index of functions and categories.
|
|
</ul>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Using"></a>Next: <a rel="next" accesskey="n" href="#Overview">Overview</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="chapter">1 Using</h2>
|
|
|
|
<p><a name="index-using-libiberty-1"></a><a name="index-libiberty-usage-2"></a><a name="index-how-to-use-3"></a>
|
|
<!-- THIS SECTION IS CRAP AND NEEDS REWRITING BADLY. -->
|
|
|
|
<p>To date, <code>libiberty</code> is generally not installed on its own. It has evolved
|
|
over years but does not have its own version number nor release schedule.
|
|
|
|
<p>Possibly the easiest way to use <code>libiberty</code> in your projects is to drop the
|
|
<code>libiberty</code> 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.
|
|
|
|
<p>Passing <span class="option">--enable-install-libiberty</span> to the <span class="command">configure</span>
|
|
script when building <code>libiberty</code> causes the header files and archive library
|
|
to be installed when <kbd>make install</kbd> is run. This option also takes
|
|
an (optional) argument to specify the installation location, in the same
|
|
manner as <span class="option">--prefix</span>.
|
|
|
|
<p>For your own projects, an approach which offers stability and flexibility
|
|
is to include <code>libiberty</code> 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 <code>libiberty</code> 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</code> library.)
|
|
|
|
<p>Making use of <code>libiberty</code> code usually requires that you include one or more
|
|
header files from the <code>libiberty</code> distribution. (They will be named as
|
|
necessary in the function descriptions.) At link time, you will need to
|
|
add <span class="option">-liberty</span> to your link command invocation.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Overview"></a>Next: <a rel="next" accesskey="n" href="#Functions">Functions</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Using">Using</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="chapter">2 Overview</h2>
|
|
|
|
<p>Functions contained in <code>libiberty</code> can be divided into three general categories.
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Supplemental-Functions">Supplemental Functions</a>: Providing functions which don't exist
|
|
on older operating systems.
|
|
|
|
<li><a accesskey="2" href="#Replacement-Functions">Replacement Functions</a>: These functions are sometimes buggy or
|
|
unpredictable on some operating systems.
|
|
|
|
<li><a accesskey="3" href="#Extensions">Extensions</a>: Functions which provide useful extensions
|
|
or safety wrappers around existing code.
|
|
</ul>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Supplemental-Functions"></a>Next: <a rel="next" accesskey="n" href="#Replacement-Functions">Replacement Functions</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Overview">Overview</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">2.1 Supplemental Functions</h3>
|
|
|
|
<p><a name="index-supplemental-functions-4"></a><a name="index-functions_002c-supplemental-5"></a><a name="index-functions_002c-missing-6"></a>
|
|
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</code>
|
|
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.
|
|
|
|
<p>Similarly, some functions exist only among a particular “flavor”
|
|
or “family” of operating systems. As an example, the <code>bzero</code>
|
|
function is often not present on systems outside the BSD-derived
|
|
family of systems.
|
|
|
|
<p>Many such functions are provided in <code>libiberty</code>. They are quickly
|
|
listed here with little description, as systems which lack them
|
|
become less and less common. Each function <var>foo</var> is implemented
|
|
in <var>foo</var><span class="file">.c</span> but not declared in any <code>libiberty</code> 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</code>.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Replacement-Functions"></a>Next: <a rel="next" accesskey="n" href="#Extensions">Extensions</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Supplemental-Functions">Supplemental Functions</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Overview">Overview</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">2.2 Replacement Functions</h3>
|
|
|
|
<p><a name="index-replacement-functions-7"></a><a name="index-functions_002c-replacement-8"></a>
|
|
Some functions have extremely limited implementations on different
|
|
platforms. Other functions are tedious to use correctly; for example,
|
|
proper use of <code>malloc</code> 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 <code>libiberty</code> to address these issues
|
|
for some of the most commonly used subroutines.
|
|
|
|
<p>All of these functions are declared in the <span class="file">libiberty.h</span> 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.
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Memory-Allocation">Memory Allocation</a>: Testing and handling failed memory
|
|
requests automatically.
|
|
<li><a accesskey="2" href="#Exit-Handlers">Exit Handlers</a>: Calling routines on program exit.
|
|
<li><a accesskey="3" href="#Error-Reporting">Error Reporting</a>: Mapping errno and signal numbers to
|
|
more useful string formats.
|
|
</ul>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Memory-Allocation"></a>Next: <a rel="next" accesskey="n" href="#Exit-Handlers">Exit Handlers</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Replacement-Functions">Replacement Functions</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h4 class="subsection">2.2.1 Memory Allocation</h4>
|
|
|
|
<p><a name="index-memory-allocation-9"></a>
|
|
The functions beginning with the letter <span class="samp">x</span> 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.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Exit-Handlers"></a>Next: <a rel="next" accesskey="n" href="#Error-Reporting">Error Reporting</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Memory-Allocation">Memory Allocation</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Replacement-Functions">Replacement Functions</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h4 class="subsection">2.2.2 Exit Handlers</h4>
|
|
|
|
<p><a name="index-exit-handlers-10"></a>
|
|
The existence and implementation of the <code>atexit</code> routine varies
|
|
amongst the flavors of Unix. <code>libiberty</code> provides an unvarying dependable
|
|
implementation via <code>xatexit</code> and <code>xexit</code>.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Error-Reporting"></a>Previous: <a rel="previous" accesskey="p" href="#Exit-Handlers">Exit Handlers</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Replacement-Functions">Replacement Functions</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h4 class="subsection">2.2.3 Error Reporting</h4>
|
|
|
|
<p><a name="index-error-reporting-11"></a>
|
|
These are a set of routines to facilitate programming with the system
|
|
<code>errno</code> interface. The <code>libiberty</code> source file <span class="file">strerror.c</span>
|
|
contains a good deal of documentation for these functions.
|
|
|
|
<!-- signal stuff -->
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Extensions"></a>Previous: <a rel="previous" accesskey="p" href="#Replacement-Functions">Replacement Functions</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Overview">Overview</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">2.3 Extensions</h3>
|
|
|
|
<p><a name="index-extensions-12"></a><a name="index-functions_002c-extension-13"></a>
|
|
<code>libiberty</code> 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.
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Obstacks">Obstacks</a>: Stacks of arbitrary objects.
|
|
</ul>
|
|
|
|
<!-- This is generated from the glibc manual using a make-obstacks-texi.sh -->
|
|
<!-- script of Phil's. Hope it's accurate. -->
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Obstacks"></a>Next: <a rel="next" accesskey="n" href="#Licenses">Licenses</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Functions">Functions</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="chapter">3 Obstacks</h2>
|
|
|
|
<p><a name="index-obstacks-14"></a>
|
|
An <dfn>obstack</dfn> is a pool of memory containing a stack of objects. You
|
|
can create any number of separate obstacks, and then allocate objects in
|
|
specified obstacks. Within each obstack, the last object allocated must
|
|
always be the first one freed, but distinct obstacks are independent of
|
|
each other.
|
|
|
|
<p>Aside from this one constraint of order of freeing, obstacks are totally
|
|
general: an obstack can contain any number of objects of any size. They
|
|
are implemented with macros, so allocation is usually very fast as long as
|
|
the objects are usually small. And the only space overhead per object is
|
|
the padding needed to start each object on a suitable boundary.
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Creating-Obstacks">Creating Obstacks</a>: How to declare an obstack in your program.
|
|
<li><a accesskey="2" href="#Preparing-for-Obstacks">Preparing for Obstacks</a>: Preparations needed before you can
|
|
use obstacks.
|
|
<li><a accesskey="3" href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>: Allocating objects in an obstack.
|
|
<li><a accesskey="4" href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a>: Freeing objects in an obstack.
|
|
<li><a accesskey="5" href="#Obstack-Functions">Obstack Functions</a>: The obstack functions are both
|
|
functions and macros.
|
|
<li><a accesskey="6" href="#Growing-Objects">Growing Objects</a>: Making an object bigger by stages.
|
|
<li><a accesskey="7" href="#Extra-Fast-Growing">Extra Fast Growing</a>: Extra-high-efficiency (though more
|
|
complicated) growing objects.
|
|
<li><a accesskey="8" href="#Status-of-an-Obstack">Status of an Obstack</a>: Inquiries about the status of an obstack.
|
|
<li><a accesskey="9" href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a>: Controlling alignment of objects in obstacks.
|
|
<li><a href="#Obstack-Chunks">Obstack Chunks</a>: How obstacks obtain and release chunks;
|
|
efficiency considerations.
|
|
<li><a href="#Summary-of-Obstacks">Summary of Obstacks</a>
|
|
</ul>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Creating-Obstacks"></a>Next: <a rel="next" accesskey="n" href="#Preparing-for-Obstacks">Preparing for Obstacks</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.1 Creating Obstacks</h3>
|
|
|
|
<p>The utilities for manipulating obstacks are declared in the header
|
|
file <span class="file">obstack.h</span>.
|
|
<a name="index-obstack_002eh-15"></a>
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
|
|
<div class="defun">
|
|
— Data Type: <b>struct obstack</b><var><a name="index-struct-obstack-16"></a></var><br>
|
|
<blockquote><p>An obstack is represented by a data structure of type <code>struct
|
|
obstack</code>. This structure has a small fixed size; it records the status
|
|
of the obstack and how to find the space in which objects are allocated.
|
|
It does not contain any of the objects themselves. You should not try
|
|
to access the contents of the structure directly; use only the functions
|
|
described in this chapter.
|
|
</p></blockquote></div>
|
|
|
|
<p>You can declare variables of type <code>struct obstack</code> and use them as
|
|
obstacks, or you can allocate obstacks dynamically like any other kind
|
|
of object. Dynamic allocation of obstacks allows your program to have a
|
|
variable number of different stacks. (You can even allocate an
|
|
obstack structure in another obstack, but this is rarely useful.)
|
|
|
|
<p>All the functions that work with obstacks require you to specify which
|
|
obstack to use. You do this with a pointer of type <code>struct obstack
|
|
*</code>. In the following, we often say “an obstack” when strictly
|
|
speaking the object at hand is such a pointer.
|
|
|
|
<p>The objects in the obstack are packed into large blocks called
|
|
<dfn>chunks</dfn>. The <code>struct obstack</code> structure points to a chain of
|
|
the chunks currently in use.
|
|
|
|
<p>The obstack library obtains a new chunk whenever you allocate an object
|
|
that won't fit in the previous chunk. Since the obstack library manages
|
|
chunks automatically, you don't need to pay much attention to them, but
|
|
you do need to supply a function which the obstack library should use to
|
|
get a chunk. Usually you supply a function which uses <code>malloc</code>
|
|
directly or indirectly. You must also supply a function to free a chunk.
|
|
These matters are described in the following section.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Preparing-for-Obstacks"></a>Next: <a rel="next" accesskey="n" href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Creating-Obstacks">Creating Obstacks</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.2 Preparing for Using Obstacks</h3>
|
|
|
|
<p>Each source file in which you plan to use the obstack functions
|
|
must include the header file <span class="file">obstack.h</span>, like this:
|
|
|
|
<pre class="smallexample"> #include <obstack.h>
|
|
</pre>
|
|
<p><a name="index-obstack_005fchunk_005falloc-17"></a><a name="index-obstack_005fchunk_005ffree-18"></a>Also, if the source file uses the macro <code>obstack_init</code>, it must
|
|
declare or define two functions or macros that will be called by the
|
|
obstack library. One, <code>obstack_chunk_alloc</code>, is used to allocate
|
|
the chunks of memory into which objects are packed. The other,
|
|
<code>obstack_chunk_free</code>, is used to return chunks when the objects in
|
|
them are freed. These macros should appear before any use of obstacks
|
|
in the source file.
|
|
|
|
<p>Usually these are defined to use <code>malloc</code> via the intermediary
|
|
<code>xmalloc</code> (see <a href="libc.html#Unconstrained-Allocation">Unconstrained Allocation (The GNU C Library Reference Manual)</a>). This is done with
|
|
the following pair of macro definitions:
|
|
|
|
<pre class="smallexample"> #define obstack_chunk_alloc xmalloc
|
|
#define obstack_chunk_free free
|
|
</pre>
|
|
<p class="noindent">Though the memory you get using obstacks really comes from <code>malloc</code>,
|
|
using obstacks is faster because <code>malloc</code> is called less often, for
|
|
larger blocks of memory. See <a href="#Obstack-Chunks">Obstack Chunks</a>, for full details.
|
|
|
|
<p>At run time, before the program can use a <code>struct obstack</code> object
|
|
as an obstack, it must initialize the obstack by calling
|
|
<code>obstack_init</code>.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: int <b>obstack_init</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005finit-19"></a></var><br>
|
|
<blockquote><p>Initialize obstack <var>obstack-ptr</var> for allocation of objects. This
|
|
function calls the obstack's <code>obstack_chunk_alloc</code> function. If
|
|
allocation of memory fails, the function pointed to by
|
|
<code>obstack_alloc_failed_handler</code> is called. The <code>obstack_init</code>
|
|
function always returns 1 (Compatibility notice: Former versions of
|
|
obstack returned 0 if allocation failed).
|
|
</p></blockquote></div>
|
|
|
|
<p>Here are two examples of how to allocate the space for an obstack and
|
|
initialize it. First, an obstack that is a static variable:
|
|
|
|
<pre class="smallexample"> static struct obstack myobstack;
|
|
...
|
|
obstack_init (&myobstack);
|
|
</pre>
|
|
<p class="noindent">Second, an obstack that is itself dynamically allocated:
|
|
|
|
<pre class="smallexample"> struct obstack *myobstack_ptr
|
|
= (struct obstack *) xmalloc (sizeof (struct obstack));
|
|
|
|
obstack_init (myobstack_ptr);
|
|
</pre>
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Variable: <b>obstack_alloc_failed_handler</b><var><a name="index-obstack_005falloc_005ffailed_005fhandler-20"></a></var><br>
|
|
<blockquote><p>The value of this variable is a pointer to a function that
|
|
<code>obstack</code> uses when <code>obstack_chunk_alloc</code> fails to allocate
|
|
memory. The default action is to print a message and abort.
|
|
You should supply a function that either calls <code>exit</code>
|
|
(see <a href="libc.html#Program-Termination">Program Termination (The GNU C Library Reference Manual)</a>) or <code>longjmp</code> (see <a href="libc.html#Non_002dLocal-Exits">Non-Local Exits (The GNU C Library Reference Manual)</a>) and doesn't return.
|
|
|
|
<pre class="smallexample"> void my_obstack_alloc_failed (void)
|
|
...
|
|
obstack_alloc_failed_handler = &my_obstack_alloc_failed;
|
|
</pre>
|
|
</blockquote></div>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Allocation-in-an-Obstack"></a>Next: <a rel="next" accesskey="n" href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Preparing-for-Obstacks">Preparing for Obstacks</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.3 Allocation in an Obstack</h3>
|
|
|
|
<p><a name="index-allocation-_0028obstacks_0029-21"></a>
|
|
The most direct way to allocate an object in an obstack is with
|
|
<code>obstack_alloc</code>, which is invoked almost like <code>malloc</code>.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_alloc</b> (<var>struct obstack *obstack-ptr, int size</var>)<var><a name="index-obstack_005falloc-22"></a></var><br>
|
|
<blockquote><p>This allocates an uninitialized block of <var>size</var> bytes in an obstack
|
|
and returns its address. Here <var>obstack-ptr</var> specifies which obstack
|
|
to allocate the block in; it is the address of the <code>struct obstack</code>
|
|
object which represents the obstack. Each obstack function or macro
|
|
requires you to specify an <var>obstack-ptr</var> as the first argument.
|
|
|
|
<p>This function calls the obstack's <code>obstack_chunk_alloc</code> function if
|
|
it needs to allocate a new chunk of memory; it calls
|
|
<code>obstack_alloc_failed_handler</code> if allocation of memory by
|
|
<code>obstack_chunk_alloc</code> failed.
|
|
</p></blockquote></div>
|
|
|
|
<p>For example, here is a function that allocates a copy of a string <var>str</var>
|
|
in a specific obstack, which is in the variable <code>string_obstack</code>:
|
|
|
|
<pre class="smallexample"> struct obstack string_obstack;
|
|
|
|
char *
|
|
copystring (char *string)
|
|
{
|
|
size_t len = strlen (string) + 1;
|
|
char *s = (char *) obstack_alloc (&string_obstack, len);
|
|
memcpy (s, string, len);
|
|
return s;
|
|
}
|
|
</pre>
|
|
<p>To allocate a block with specified contents, use the function
|
|
<code>obstack_copy</code>, declared like this:
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_copy</b> (<var>struct obstack *obstack-ptr, void *address, int size</var>)<var><a name="index-obstack_005fcopy-23"></a></var><br>
|
|
<blockquote><p>This allocates a block and initializes it by copying <var>size</var>
|
|
bytes of data starting at <var>address</var>. It calls
|
|
<code>obstack_alloc_failed_handler</code> if allocation of memory by
|
|
<code>obstack_chunk_alloc</code> failed.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_copy0</b> (<var>struct obstack *obstack-ptr, void *address, int size</var>)<var><a name="index-obstack_005fcopy0-24"></a></var><br>
|
|
<blockquote><p>Like <code>obstack_copy</code>, but appends an extra byte containing a null
|
|
character. This extra byte is not counted in the argument <var>size</var>.
|
|
</p></blockquote></div>
|
|
|
|
<p>The <code>obstack_copy0</code> function is convenient for copying a sequence
|
|
of characters into an obstack as a null-terminated string. Here is an
|
|
example of its use:
|
|
|
|
<pre class="smallexample"> char *
|
|
obstack_savestring (char *addr, int size)
|
|
{
|
|
return obstack_copy0 (&myobstack, addr, size);
|
|
}
|
|
</pre>
|
|
<p class="noindent">Contrast this with the previous example of <code>savestring</code> using
|
|
<code>malloc</code> (see <a href="libc.html#Basic-Allocation">Basic Allocation (The GNU C Library Reference Manual)</a>).
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Freeing-Obstack-Objects"></a>Next: <a rel="next" accesskey="n" href="#Obstack-Functions">Obstack Functions</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.4 Freeing Objects in an Obstack</h3>
|
|
|
|
<p><a name="index-freeing-_0028obstacks_0029-25"></a>
|
|
To free an object allocated in an obstack, use the function
|
|
<code>obstack_free</code>. Since the obstack is a stack of objects, freeing
|
|
one object automatically frees all other objects allocated more recently
|
|
in the same obstack.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_free</b> (<var>struct obstack *obstack-ptr, void *object</var>)<var><a name="index-obstack_005ffree-26"></a></var><br>
|
|
<blockquote><p>If <var>object</var> is a null pointer, everything allocated in the obstack
|
|
is freed. Otherwise, <var>object</var> must be the address of an object
|
|
allocated in the obstack. Then <var>object</var> is freed, along with
|
|
everything allocated in <var>obstack</var> since <var>object</var>.
|
|
</p></blockquote></div>
|
|
|
|
<p>Note that if <var>object</var> is a null pointer, the result is an
|
|
uninitialized obstack. To free all memory in an obstack but leave it
|
|
valid for further allocation, call <code>obstack_free</code> with the address
|
|
of the first object allocated on the obstack:
|
|
|
|
<pre class="smallexample"> obstack_free (obstack_ptr, first_object_allocated_ptr);
|
|
</pre>
|
|
<p>Recall that the objects in an obstack are grouped into chunks. When all
|
|
the objects in a chunk become free, the obstack library automatically
|
|
frees the chunk (see <a href="#Preparing-for-Obstacks">Preparing for Obstacks</a>). Then other
|
|
obstacks, or non-obstack allocation, can reuse the space of the chunk.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Obstack-Functions"></a>Next: <a rel="next" accesskey="n" href="#Growing-Objects">Growing Objects</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.5 Obstack Functions and Macros</h3>
|
|
|
|
<p><a name="index-macros-27"></a>
|
|
The interfaces for using obstacks may be defined either as functions or
|
|
as macros, depending on the compiler. The obstack facility works with
|
|
all C compilers, including both ISO C<!-- /@w --> and traditional C, but there are
|
|
precautions you must take if you plan to use compilers other than GNU C.
|
|
|
|
<p>If you are using an old-fashioned non-ISO C<!-- /@w --> compiler, all the obstack
|
|
“functions” are actually defined only as macros. You can call these
|
|
macros like functions, but you cannot use them in any other way (for
|
|
example, you cannot take their address).
|
|
|
|
<p>Calling the macros requires a special precaution: namely, the first
|
|
operand (the obstack pointer) may not contain any side effects, because
|
|
it may be computed more than once. For example, if you write this:
|
|
|
|
<pre class="smallexample"> obstack_alloc (get_obstack (), 4);
|
|
</pre>
|
|
<p class="noindent">you will find that <code>get_obstack</code> may be called several times.
|
|
If you use <code>*obstack_list_ptr++</code> as the obstack pointer argument,
|
|
you will get very strange results since the incrementation may occur
|
|
several times.
|
|
|
|
<p>In ISO C<!-- /@w -->, each function has both a macro definition and a function
|
|
definition. The function definition is used if you take the address of the
|
|
function without calling it. An ordinary call uses the macro definition by
|
|
default, but you can request the function definition instead by writing the
|
|
function name in parentheses, as shown here:
|
|
|
|
<pre class="smallexample"> char *x;
|
|
void *(*funcp) ();
|
|
/* <span class="roman">Use the macro</span>. */
|
|
x = (char *) obstack_alloc (obptr, size);
|
|
/* <span class="roman">Call the function</span>. */
|
|
x = (char *) (obstack_alloc) (obptr, size);
|
|
/* <span class="roman">Take the address of the function</span>. */
|
|
funcp = obstack_alloc;
|
|
</pre>
|
|
<p class="noindent">This is the same situation that exists in ISO C<!-- /@w --> for the standard library
|
|
functions. See <a href="libc.html#Macro-Definitions">Macro Definitions (The GNU C Library Reference Manual)</a>.
|
|
|
|
<p><strong>Warning:</strong> When you do use the macros, you must observe the
|
|
precaution of avoiding side effects in the first operand, even in ISO C<!-- /@w -->.
|
|
|
|
<p>If you use the GNU C compiler, this precaution is not necessary, because
|
|
various language extensions in GNU C permit defining the macros so as to
|
|
compute each argument only once.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Growing-Objects"></a>Next: <a rel="next" accesskey="n" href="#Extra-Fast-Growing">Extra Fast Growing</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Obstack-Functions">Obstack Functions</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.6 Growing Objects</h3>
|
|
|
|
<p><a name="index-growing-objects-_0028in-obstacks_0029-28"></a><a name="index-changing-the-size-of-a-block-_0028obstacks_0029-29"></a>
|
|
Because memory in obstack chunks is used sequentially, it is possible to
|
|
build up an object step by step, adding one or more bytes at a time to the
|
|
end of the object. With this technique, you do not need to know how much
|
|
data you will put in the object until you come to the end of it. We call
|
|
this the technique of <dfn>growing objects</dfn>. The special functions
|
|
for adding data to the growing object are described in this section.
|
|
|
|
<p>You don't need to do anything special when you start to grow an object.
|
|
Using one of the functions to add data to the object automatically
|
|
starts it. However, it is necessary to say explicitly when the object is
|
|
finished. This is done with the function <code>obstack_finish</code>.
|
|
|
|
<p>The actual address of the object thus built up is not known until the
|
|
object is finished. Until then, it always remains possible that you will
|
|
add so much data that the object must be copied into a new chunk.
|
|
|
|
<p>While the obstack is in use for a growing object, you cannot use it for
|
|
ordinary allocation of another object. If you try to do so, the space
|
|
already added to the growing object will become part of the other object.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_blank</b> (<var>struct obstack *obstack-ptr, int size</var>)<var><a name="index-obstack_005fblank-30"></a></var><br>
|
|
<blockquote><p>The most basic function for adding to a growing object is
|
|
<code>obstack_blank</code>, which adds space without initializing it.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_grow</b> (<var>struct obstack *obstack-ptr, void *data, int size</var>)<var><a name="index-obstack_005fgrow-31"></a></var><br>
|
|
<blockquote><p>To add a block of initialized space, use <code>obstack_grow</code>, which is
|
|
the growing-object analogue of <code>obstack_copy</code>. It adds <var>size</var>
|
|
bytes of data to the growing object, copying the contents from
|
|
<var>data</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_grow0</b> (<var>struct obstack *obstack-ptr, void *data, int size</var>)<var><a name="index-obstack_005fgrow0-32"></a></var><br>
|
|
<blockquote><p>This is the growing-object analogue of <code>obstack_copy0</code>. It adds
|
|
<var>size</var> bytes copied from <var>data</var>, followed by an additional null
|
|
character.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_1grow</b> (<var>struct obstack *obstack-ptr, char c</var>)<var><a name="index-obstack_005f1grow-33"></a></var><br>
|
|
<blockquote><p>To add one character at a time, use the function <code>obstack_1grow</code>.
|
|
It adds a single byte containing <var>c</var> to the growing object.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_ptr_grow</b> (<var>struct obstack *obstack-ptr, void *data</var>)<var><a name="index-obstack_005fptr_005fgrow-34"></a></var><br>
|
|
<blockquote><p>Adding the value of a pointer one can use the function
|
|
<code>obstack_ptr_grow</code>. It adds <code>sizeof (void *)</code> bytes
|
|
containing the value of <var>data</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_int_grow</b> (<var>struct obstack *obstack-ptr, int data</var>)<var><a name="index-obstack_005fint_005fgrow-35"></a></var><br>
|
|
<blockquote><p>A single value of type <code>int</code> can be added by using the
|
|
<code>obstack_int_grow</code> function. It adds <code>sizeof (int)</code> bytes to
|
|
the growing object and initializes them with the value of <var>data</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_finish</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005ffinish-36"></a></var><br>
|
|
<blockquote><p>When you are finished growing the object, use the function
|
|
<code>obstack_finish</code> to close it off and return its final address.
|
|
|
|
<p>Once you have finished the object, the obstack is available for ordinary
|
|
allocation or for growing another object.
|
|
|
|
<p>This function can return a null pointer under the same conditions as
|
|
<code>obstack_alloc</code> (see <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>).
|
|
</p></blockquote></div>
|
|
|
|
<p>When you build an object by growing it, you will probably need to know
|
|
afterward how long it became. You need not keep track of this as you grow
|
|
the object, because you can find out the length from the obstack just
|
|
before finishing the object with the function <code>obstack_object_size</code>,
|
|
declared as follows:
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: int <b>obstack_object_size</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005fobject_005fsize-37"></a></var><br>
|
|
<blockquote><p>This function returns the current size of the growing object, in bytes.
|
|
Remember to call this function <em>before</em> finishing the object.
|
|
After it is finished, <code>obstack_object_size</code> will return zero.
|
|
</p></blockquote></div>
|
|
|
|
<p>If you have started growing an object and wish to cancel it, you should
|
|
finish it and then free it, like this:
|
|
|
|
<pre class="smallexample"> obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
|
|
</pre>
|
|
<p class="noindent">This has no effect if no object was growing.
|
|
|
|
<p><a name="index-shrinking-objects-38"></a>You can use <code>obstack_blank</code> with a negative size argument to make
|
|
the current object smaller. Just don't try to shrink it beyond zero
|
|
length—there's no telling what will happen if you do that.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Extra-Fast-Growing"></a>Next: <a rel="next" accesskey="n" href="#Status-of-an-Obstack">Status of an Obstack</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Growing-Objects">Growing Objects</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.7 Extra Fast Growing Objects</h3>
|
|
|
|
<p><a name="index-efficiency-and-obstacks-39"></a>
|
|
The usual functions for growing objects incur overhead for checking
|
|
whether there is room for the new growth in the current chunk. If you
|
|
are frequently constructing objects in small steps of growth, this
|
|
overhead can be significant.
|
|
|
|
<p>You can reduce the overhead by using special “fast growth”
|
|
functions that grow the object without checking. In order to have a
|
|
robust program, you must do the checking yourself. If you do this checking
|
|
in the simplest way each time you are about to add data to the object, you
|
|
have not saved anything, because that is what the ordinary growth
|
|
functions do. But if you can arrange to check less often, or check
|
|
more efficiently, then you make the program faster.
|
|
|
|
<p>The function <code>obstack_room</code> returns the amount of room available
|
|
in the current chunk. It is declared as follows:
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: int <b>obstack_room</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005froom-40"></a></var><br>
|
|
<blockquote><p>This returns the number of bytes that can be added safely to the current
|
|
growing object (or to an object about to be started) in obstack
|
|
<var>obstack</var> using the fast growth functions.
|
|
</p></blockquote></div>
|
|
|
|
<p>While you know there is room, you can use these fast growth functions
|
|
for adding data to a growing object:
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_1grow_fast</b> (<var>struct obstack *obstack-ptr, char c</var>)<var><a name="index-obstack_005f1grow_005ffast-41"></a></var><br>
|
|
<blockquote><p>The function <code>obstack_1grow_fast</code> adds one byte containing the
|
|
character <var>c</var> to the growing object in obstack <var>obstack-ptr</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_ptr_grow_fast</b> (<var>struct obstack *obstack-ptr, void *data</var>)<var><a name="index-obstack_005fptr_005fgrow_005ffast-42"></a></var><br>
|
|
<blockquote><p>The function <code>obstack_ptr_grow_fast</code> adds <code>sizeof (void *)</code>
|
|
bytes containing the value of <var>data</var> to the growing object in
|
|
obstack <var>obstack-ptr</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_int_grow_fast</b> (<var>struct obstack *obstack-ptr, int data</var>)<var><a name="index-obstack_005fint_005fgrow_005ffast-43"></a></var><br>
|
|
<blockquote><p>The function <code>obstack_int_grow_fast</code> adds <code>sizeof (int)</code> bytes
|
|
containing the value of <var>data</var> to the growing object in obstack
|
|
<var>obstack-ptr</var>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void <b>obstack_blank_fast</b> (<var>struct obstack *obstack-ptr, int size</var>)<var><a name="index-obstack_005fblank_005ffast-44"></a></var><br>
|
|
<blockquote><p>The function <code>obstack_blank_fast</code> adds <var>size</var> bytes to the
|
|
growing object in obstack <var>obstack-ptr</var> without initializing them.
|
|
</p></blockquote></div>
|
|
|
|
<p>When you check for space using <code>obstack_room</code> and there is not
|
|
enough room for what you want to add, the fast growth functions
|
|
are not safe. In this case, simply use the corresponding ordinary
|
|
growth function instead. Very soon this will copy the object to a
|
|
new chunk; then there will be lots of room available again.
|
|
|
|
<p>So, each time you use an ordinary growth function, check afterward for
|
|
sufficient space using <code>obstack_room</code>. Once the object is copied
|
|
to a new chunk, there will be plenty of space again, so the program will
|
|
start using the fast growth functions again.
|
|
|
|
<p>Here is an example:
|
|
|
|
<pre class="smallexample"> void
|
|
add_string (struct obstack *obstack, const char *ptr, int len)
|
|
{
|
|
while (len > 0)
|
|
{
|
|
int room = obstack_room (obstack);
|
|
if (room == 0)
|
|
{
|
|
/* <span class="roman">Not enough room. Add one character slowly,</span>
|
|
<span class="roman">which may copy to a new chunk and make room.</span> */
|
|
obstack_1grow (obstack, *ptr++);
|
|
len--;
|
|
}
|
|
else
|
|
{
|
|
if (room > len)
|
|
room = len;
|
|
/* <span class="roman">Add fast as much as we have room for.</span> */
|
|
len -= room;
|
|
while (room-- > 0)
|
|
obstack_1grow_fast (obstack, *ptr++);
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Status-of-an-Obstack"></a>Next: <a rel="next" accesskey="n" href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Extra-Fast-Growing">Extra Fast Growing</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.8 Status of an Obstack</h3>
|
|
|
|
<p><a name="index-obstack-status-45"></a><a name="index-status-of-obstack-46"></a>
|
|
Here are functions that provide information on the current status of
|
|
allocation in an obstack. You can use them to learn about an object while
|
|
still growing it.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_base</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005fbase-47"></a></var><br>
|
|
<blockquote><p>This function returns the tentative address of the beginning of the
|
|
currently growing object in <var>obstack-ptr</var>. If you finish the object
|
|
immediately, it will have that address. If you make it larger first, it
|
|
may outgrow the current chunk—then its address will change!
|
|
|
|
<p>If no object is growing, this value says where the next object you
|
|
allocate will start (once again assuming it fits in the current
|
|
chunk).
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: void * <b>obstack_next_free</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005fnext_005ffree-48"></a></var><br>
|
|
<blockquote><p>This function returns the address of the first free byte in the current
|
|
chunk of obstack <var>obstack-ptr</var>. This is the end of the currently
|
|
growing object. If no object is growing, <code>obstack_next_free</code>
|
|
returns the same value as <code>obstack_base</code>.
|
|
</p></blockquote></div>
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Function: int <b>obstack_object_size</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005fobject_005fsize-49"></a></var><br>
|
|
<blockquote><p>This function returns the size in bytes of the currently growing object.
|
|
This is equivalent to
|
|
|
|
<pre class="smallexample"> obstack_next_free (<var>obstack-ptr</var>) - obstack_base (<var>obstack-ptr</var>)
|
|
</pre>
|
|
</blockquote></div>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Obstacks-Data-Alignment"></a>Next: <a rel="next" accesskey="n" href="#Obstack-Chunks">Obstack Chunks</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Status-of-an-Obstack">Status of an Obstack</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.9 Alignment of Data in Obstacks</h3>
|
|
|
|
<p><a name="index-alignment-_0028in-obstacks_0029-50"></a>
|
|
Each obstack has an <dfn>alignment boundary</dfn>; each object allocated in
|
|
the obstack automatically starts on an address that is a multiple of the
|
|
specified boundary. By default, this boundary is 4 bytes.
|
|
|
|
<p>To access an obstack's alignment boundary, use the macro
|
|
<code>obstack_alignment_mask</code>, whose function prototype looks like
|
|
this:
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Macro: int <b>obstack_alignment_mask</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005falignment_005fmask-51"></a></var><br>
|
|
<blockquote><p>The value is a bit mask; a bit that is 1 indicates that the corresponding
|
|
bit in the address of an object should be 0. The mask value should be one
|
|
less than a power of 2; the effect is that all object addresses are
|
|
multiples of that power of 2. The default value of the mask is 3, so that
|
|
addresses are multiples of 4. A mask value of 0 means an object can start
|
|
on any multiple of 1 (that is, no alignment is required).
|
|
|
|
<p>The expansion of the macro <code>obstack_alignment_mask</code> is an lvalue,
|
|
so you can alter the mask by assignment. For example, this statement:
|
|
|
|
<pre class="smallexample"> obstack_alignment_mask (obstack_ptr) = 0;
|
|
</pre>
|
|
<p class="noindent">has the effect of turning off alignment processing in the specified obstack.
|
|
</p></blockquote></div>
|
|
|
|
<p>Note that a change in alignment mask does not take effect until
|
|
<em>after</em> the next time an object is allocated or finished in the
|
|
obstack. If you are not growing an object, you can make the new
|
|
alignment mask take effect immediately by calling <code>obstack_finish</code>.
|
|
This will finish a zero-length object and then do proper alignment for
|
|
the next object.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Obstack-Chunks"></a>Next: <a rel="next" accesskey="n" href="#Summary-of-Obstacks">Summary of Obstacks</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.10 Obstack Chunks</h3>
|
|
|
|
<p><a name="index-efficiency-of-chunks-52"></a><a name="index-chunks-53"></a>
|
|
Obstacks work by allocating space for themselves in large chunks, and
|
|
then parceling out space in the chunks to satisfy your requests. Chunks
|
|
are normally 4096 bytes long unless you specify a different chunk size.
|
|
The chunk size includes 8 bytes of overhead that are not actually used
|
|
for storing objects. Regardless of the specified size, longer chunks
|
|
will be allocated when necessary for long objects.
|
|
|
|
<p>The obstack library allocates chunks by calling the function
|
|
<code>obstack_chunk_alloc</code>, which you must define. When a chunk is no
|
|
longer needed because you have freed all the objects in it, the obstack
|
|
library frees the chunk by calling <code>obstack_chunk_free</code>, which you
|
|
must also define.
|
|
|
|
<p>These two must be defined (as macros) or declared (as functions) in each
|
|
source file that uses <code>obstack_init</code> (see <a href="#Creating-Obstacks">Creating Obstacks</a>).
|
|
Most often they are defined as macros like this:
|
|
|
|
<pre class="smallexample"> #define obstack_chunk_alloc malloc
|
|
#define obstack_chunk_free free
|
|
</pre>
|
|
<p>Note that these are simple macros (no arguments). Macro definitions with
|
|
arguments will not work! It is necessary that <code>obstack_chunk_alloc</code>
|
|
or <code>obstack_chunk_free</code>, alone, expand into a function name if it is
|
|
not itself a function name.
|
|
|
|
<p>If you allocate chunks with <code>malloc</code>, the chunk size should be a
|
|
power of 2. The default chunk size, 4096, was chosen because it is long
|
|
enough to satisfy many typical requests on the obstack yet short enough
|
|
not to waste too much memory in the portion of the last chunk not yet used.
|
|
|
|
<!-- obstack.h -->
|
|
<!-- GNU -->
|
|
<div class="defun">
|
|
— Macro: int <b>obstack_chunk_size</b> (<var>struct obstack *obstack-ptr</var>)<var><a name="index-obstack_005fchunk_005fsize-54"></a></var><br>
|
|
<blockquote><p>This returns the chunk size of the given obstack.
|
|
</p></blockquote></div>
|
|
|
|
<p>Since this macro expands to an lvalue, you can specify a new chunk size by
|
|
assigning it a new value. Doing so does not affect the chunks already
|
|
allocated, but will change the size of chunks allocated for that particular
|
|
obstack in the future. It is unlikely to be useful to make the chunk size
|
|
smaller, but making it larger might improve efficiency if you are
|
|
allocating many objects whose size is comparable to the chunk size. Here
|
|
is how to do so cleanly:
|
|
|
|
<pre class="smallexample"> if (obstack_chunk_size (obstack_ptr) < <var>new-chunk-size</var>)
|
|
obstack_chunk_size (obstack_ptr) = <var>new-chunk-size</var>;
|
|
</pre>
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Summary-of-Obstacks"></a>Previous: <a rel="previous" accesskey="p" href="#Obstack-Chunks">Obstack Chunks</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Obstacks">Obstacks</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="section">3.11 Summary of Obstack Functions</h3>
|
|
|
|
<p>Here is a summary of all the functions associated with obstacks. Each
|
|
takes the address of an obstack (<code>struct obstack *</code>) as its first
|
|
argument.
|
|
|
|
<dl>
|
|
<dt><code>void obstack_init (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Initialize use of an obstack. See <a href="#Creating-Obstacks">Creating Obstacks</a>.
|
|
|
|
<br><dt><code>void *obstack_alloc (struct obstack *</code><var>obstack-ptr</var><code>, int </code><var>size</var><code>)</code><dd>Allocate an object of <var>size</var> uninitialized bytes.
|
|
See <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>.
|
|
|
|
<br><dt><code>void *obstack_copy (struct obstack *</code><var>obstack-ptr</var><code>, void *</code><var>address</var><code>, int </code><var>size</var><code>)</code><dd>Allocate an object of <var>size</var> bytes, with contents copied from
|
|
<var>address</var>. See <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>.
|
|
|
|
<br><dt><code>void *obstack_copy0 (struct obstack *</code><var>obstack-ptr</var><code>, void *</code><var>address</var><code>, int </code><var>size</var><code>)</code><dd>Allocate an object of <var>size</var>+1 bytes, with <var>size</var> of them copied
|
|
from <var>address</var>, followed by a null character at the end.
|
|
See <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a>.
|
|
|
|
<br><dt><code>void obstack_free (struct obstack *</code><var>obstack-ptr</var><code>, void *</code><var>object</var><code>)</code><dd>Free <var>object</var> (and everything allocated in the specified obstack
|
|
more recently than <var>object</var>). See <a href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a>.
|
|
|
|
<br><dt><code>void obstack_blank (struct obstack *</code><var>obstack-ptr</var><code>, int </code><var>size</var><code>)</code><dd>Add <var>size</var> uninitialized bytes to a growing object.
|
|
See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>void obstack_grow (struct obstack *</code><var>obstack-ptr</var><code>, void *</code><var>address</var><code>, int </code><var>size</var><code>)</code><dd>Add <var>size</var> bytes, copied from <var>address</var>, to a growing object.
|
|
See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>void obstack_grow0 (struct obstack *</code><var>obstack-ptr</var><code>, void *</code><var>address</var><code>, int </code><var>size</var><code>)</code><dd>Add <var>size</var> bytes, copied from <var>address</var>, to a growing object,
|
|
and then add another byte containing a null character. See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>void obstack_1grow (struct obstack *</code><var>obstack-ptr</var><code>, char </code><var>data-char</var><code>)</code><dd>Add one byte containing <var>data-char</var> to a growing object.
|
|
See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>void *obstack_finish (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Finalize the object that is growing and return its permanent address.
|
|
See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>int obstack_object_size (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Get the current size of the currently growing object. See <a href="#Growing-Objects">Growing Objects</a>.
|
|
|
|
<br><dt><code>void obstack_blank_fast (struct obstack *</code><var>obstack-ptr</var><code>, int </code><var>size</var><code>)</code><dd>Add <var>size</var> uninitialized bytes to a growing object without checking
|
|
that there is enough room. See <a href="#Extra-Fast-Growing">Extra Fast Growing</a>.
|
|
|
|
<br><dt><code>void obstack_1grow_fast (struct obstack *</code><var>obstack-ptr</var><code>, char </code><var>data-char</var><code>)</code><dd>Add one byte containing <var>data-char</var> to a growing object without
|
|
checking that there is enough room. See <a href="#Extra-Fast-Growing">Extra Fast Growing</a>.
|
|
|
|
<br><dt><code>int obstack_room (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Get the amount of room now available for growing the current object.
|
|
See <a href="#Extra-Fast-Growing">Extra Fast Growing</a>.
|
|
|
|
<br><dt><code>int obstack_alignment_mask (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>The mask used for aligning the beginning of an object. This is an
|
|
lvalue. See <a href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a>.
|
|
|
|
<br><dt><code>int obstack_chunk_size (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>The size for allocating chunks. This is an lvalue. See <a href="#Obstack-Chunks">Obstack Chunks</a>.
|
|
|
|
<br><dt><code>void *obstack_base (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Tentative starting address of the currently growing object.
|
|
See <a href="#Status-of-an-Obstack">Status of an Obstack</a>.
|
|
|
|
<br><dt><code>void *obstack_next_free (struct obstack *</code><var>obstack-ptr</var><code>)</code><dd>Address just after the end of the currently growing object.
|
|
See <a href="#Status-of-an-Obstack">Status of an Obstack</a>.
|
|
</dl>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Functions"></a>Next: <a rel="next" accesskey="n" href="#Obstacks">Obstacks</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Overview">Overview</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="chapter">4 Function, Variable, and Macro Listing.</h2>
|
|
|
|
<!-- Automatically generated from *.c and others (the comments before -->
|
|
<!-- each entry tell you which file and where in that file). DO NOT EDIT! -->
|
|
<!-- Edit the *.c files, configure with -enable-maintainer-mode, -->
|
|
<!-- and let gather-docs build you a new copy. -->
|
|
<!-- safe-ctype.c:25 -->
|
|
<div class="defun">
|
|
— Extension: <b>HOST_CHARSET</b><var><a name="index-HOST_005fCHARSET-55"></a></var><br>
|
|
<blockquote><p>This macro indicates the basic character set and encoding used by the
|
|
host: more precisely, the encoding used for character constants in
|
|
preprocessor <span class="samp">#if</span> statements (the C "execution character set").
|
|
It is defined by <span class="file">safe-ctype.h</span>, and will be an integer constant
|
|
with one of the following values:
|
|
|
|
<dl>
|
|
<dt><code>HOST_CHARSET_UNKNOWN</code><a name="index-HOST_005fCHARSET_005fUNKNOWN-56"></a><dd>The host character set is unknown - that is, not one of the next two
|
|
possibilities.
|
|
|
|
<br><dt><code>HOST_CHARSET_ASCII</code><a name="index-HOST_005fCHARSET_005fASCII-57"></a><dd>The host character set is ASCII.
|
|
|
|
<br><dt><code>HOST_CHARSET_EBCDIC</code><a name="index-HOST_005fCHARSET_005fEBCDIC-58"></a><dd>The host character set is some variant of EBCDIC. (Only one of the
|
|
nineteen EBCDIC varying characters is tested; exercise caution.)
|
|
</dl>
|
|
</p></blockquote></div>
|
|
|
|
<!-- alloca.c:26 -->
|
|
<div class="defun">
|
|
— Replacement: void* <b>alloca</b> (<var>size_t size</var>)<var><a name="index-alloca-59"></a></var><br>
|
|
<blockquote>
|
|
<p>This function allocates memory which will be automatically reclaimed
|
|
after the procedure exits. The <code>libiberty</code> implementation does not free
|
|
the memory immediately but will do so eventually during subsequent
|
|
calls to this function. Memory is allocated using <code>xmalloc</code> under
|
|
normal circumstances.
|
|
|
|
<p>The header file <span class="file">alloca-conf.h</span> can be used in conjunction with the
|
|
GNU Autoconf test <code>AC_FUNC_ALLOCA</code> to test for and properly make
|
|
available this function. The <code>AC_FUNC_ALLOCA</code> test requires that
|
|
client code use a block of preprocessor code to be safe (see the Autoconf
|
|
manual for more); this header incorporates that logic and more, including
|
|
the possibility of a GCC built-in function.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- asprintf.c:32 -->
|
|
<div class="defun">
|
|
— Extension: int <b>asprintf</b> (<var>char **resptr, const char *format, ...</var>)<var><a name="index-asprintf-60"></a></var><br>
|
|
<blockquote>
|
|
<p>Like <code>sprintf</code>, but instead of passing a pointer to a buffer, you
|
|
pass a pointer to a pointer. This function will compute the size of
|
|
the buffer needed, allocate memory with <code>malloc</code>, and store a
|
|
pointer to the allocated memory in <code>*</code><var>resptr</var>. The value
|
|
returned is the same as <code>sprintf</code> would return. If memory could
|
|
not be allocated, minus one is returned and <code>NULL</code> is stored in
|
|
<code>*</code><var>resptr</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- atexit.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>atexit</b> (<var>void </var>(<var>*f</var>)())<var><a name="index-atexit-61"></a></var><br>
|
|
<blockquote>
|
|
<p>Causes function <var>f</var> to be called at exit. Returns 0.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- basename.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>basename</b> (<var>const char *name</var>)<var><a name="index-basename-62"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to the last component of pathname <var>name</var>.
|
|
Behavior is undefined if the pathname ends in a directory separator.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- bcmp.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>bcmp</b> (<var>char *x, char *y, int count</var>)<var><a name="index-bcmp-63"></a></var><br>
|
|
<blockquote>
|
|
<p>Compares the first <var>count</var> bytes of two areas of memory. Returns
|
|
zero if they are the same, nonzero otherwise. Returns zero if
|
|
<var>count</var> is zero. A nonzero result only indicates a difference,
|
|
it does not indicate any sorting order (say, by having a positive
|
|
result mean <var>x</var> sorts before <var>y</var>).
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- bcopy.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: void <b>bcopy</b> (<var>char *in, char *out, int length</var>)<var><a name="index-bcopy-64"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies <var>length</var> bytes from memory region <var>in</var> to region
|
|
<var>out</var>. The use of <code>bcopy</code> is deprecated in new programs.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- bsearch.c:33 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>bsearch</b> (<var>const void *key, const void *base, size_t nmemb, size_t size, int </var>(<var>*compar</var>)(<var>const void *, const void *</var>))<var><a name="index-bsearch-65"></a></var><br>
|
|
<blockquote>
|
|
<p>Performs a search over an array of <var>nmemb</var> elements pointed to by
|
|
<var>base</var> for a member that matches the object pointed to by <var>key</var>.
|
|
The size of each member is specified by <var>size</var>. The array contents
|
|
should be sorted in ascending order according to the <var>compar</var>
|
|
comparison function. This routine should take two arguments pointing to
|
|
the <var>key</var> and to an array member, in that order, and should return an
|
|
integer less than, equal to, or greater than zero if the <var>key</var> object
|
|
is respectively less than, matching, or greater than the array member.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- argv.c:124 -->
|
|
<div class="defun">
|
|
— Extension: char** <b>buildargv</b> (<var>char *sp</var>)<var><a name="index-buildargv-66"></a></var><br>
|
|
<blockquote>
|
|
<p>Given a pointer to a string, parse the string extracting fields
|
|
separated by whitespace and optionally enclosed within either single
|
|
or double quotes (which are stripped off), and build a vector of
|
|
pointers to copies of the string for each field. The input string
|
|
remains unchanged. The last element of the vector is followed by a
|
|
<code>NULL</code> element.
|
|
|
|
<p>All of the memory for the pointer array and copies of the string
|
|
is obtained from <code>malloc</code>. All of the memory can be returned to the
|
|
system with the single function call <code>freeargv</code>, which takes the
|
|
returned result of <code>buildargv</code>, as it's argument.
|
|
|
|
<p>Returns a pointer to the argument vector if successful. Returns
|
|
<code>NULL</code> if <var>sp</var> is <code>NULL</code> or if there is insufficient
|
|
memory to complete building the argument vector.
|
|
|
|
<p>If the input is a null string (as opposed to a <code>NULL</code> pointer),
|
|
then buildarg returns an argument vector that has one arg, a null
|
|
string.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- bzero.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void <b>bzero</b> (<var>char *mem, int count</var>)<var><a name="index-bzero-67"></a></var><br>
|
|
<blockquote>
|
|
<p>Zeros <var>count</var> bytes starting at <var>mem</var>. Use of this function
|
|
is deprecated in favor of <code>memset</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- calloc.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>calloc</b> (<var>size_t nelem, size_t elsize</var>)<var><a name="index-calloc-68"></a></var><br>
|
|
<blockquote>
|
|
<p>Uses <code>malloc</code> to allocate storage for <var>nelem</var> objects of
|
|
<var>elsize</var> bytes each, then zeros the memory.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- choose-temp.c:42 -->
|
|
<div class="defun">
|
|
— Extension: char* <b>choose_temp_base</b> (<var>void</var>)<var><a name="index-choose_005ftemp_005fbase-69"></a></var><br>
|
|
<blockquote>
|
|
<p>Return a prefix for temporary file names or <code>NULL</code> if unable to
|
|
find one. The current directory is chosen if all else fails so the
|
|
program is exited if a temporary directory can't be found (<code>mktemp</code>
|
|
fails). The buffer for the result is obtained with <code>xmalloc</code>.
|
|
|
|
<p>This function is provided for backwards compatibility only. Its use is
|
|
not recommended.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- make-temp-file.c:87 -->
|
|
<div class="defun">
|
|
— Replacement: char* <b>choose_tmpdir</b> ()<var><a name="index-choose_005ftmpdir-70"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to a directory path suitable for creating temporary
|
|
files in.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- clock.c:27 -->
|
|
<div class="defun">
|
|
— Supplemental: long <b>clock</b> (<var>void</var>)<var><a name="index-clock-71"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns an approximation of the CPU time used by the process as a
|
|
<code>clock_t</code>; divide this number by <span class="samp">CLOCKS_PER_SEC</span> to get the
|
|
number of seconds used.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- concat.c:24 -->
|
|
<div class="defun">
|
|
— Extension: char* <b>concat</b> (<var>const char *s1, const char *s2, <small class="dots">...</small>, </var><code>NULL</code>)<var><a name="index-concat-72"></a></var><br>
|
|
<blockquote>
|
|
<p>Concatenate zero or more of strings and return the result in freshly
|
|
<code>xmalloc</code>ed memory. Returns <code>NULL</code> if insufficient memory is
|
|
available. The argument list is terminated by the first <code>NULL</code>
|
|
pointer encountered. Pointers to empty strings are ignored.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- argv.c:52 -->
|
|
<div class="defun">
|
|
— Extension: char** <b>dupargv</b> (<var>char **vector</var>)<var><a name="index-dupargv-73"></a></var><br>
|
|
<blockquote>
|
|
<p>Duplicate an argument vector. Simply scans through <var>vector</var>,
|
|
duplicating each argument until the terminating <code>NULL</code> is found.
|
|
Returns a pointer to the argument vector if successful. Returns
|
|
<code>NULL</code> if there is insufficient memory to complete building the
|
|
argument vector.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strerror.c:567 -->
|
|
<div class="defun">
|
|
— Extension: int <b>errno_max</b> (<var>void</var>)<var><a name="index-errno_005fmax-74"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the maximum <code>errno</code> value for which a corresponding
|
|
symbolic name or message is available. Note that in the case where we
|
|
use the <code>sys_errlist</code> supplied by the system, it is possible for
|
|
there to be more symbolic names than messages, or vice versa. In
|
|
fact, the manual page for <code>perror(3C)</code> explicitly warns that one
|
|
should check the size of the table (<code>sys_nerr</code>) before indexing
|
|
it, since new error codes may be added to the system before they are
|
|
added to the table. Thus <code>sys_nerr</code> might be smaller than value
|
|
implied by the largest <code>errno</code> value defined in <code><errno.h></code>.
|
|
|
|
<p>We return the maximum value that can be used to obtain a meaningful
|
|
symbolic name or message.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- argv.c:348 -->
|
|
<div class="defun">
|
|
— Extension: void <b>expandargv</b> (<var>int *argcp, char ***argvp</var>)<var><a name="index-expandargv-75"></a></var><br>
|
|
<blockquote>
|
|
<p>The <var>argcp</var> and <code>argvp</code> arguments are pointers to the usual
|
|
<code>argc</code> and <code>argv</code> arguments to <code>main</code>. This function
|
|
looks for arguments that begin with the character <span class="samp">@</span>. Any such
|
|
arguments are interpreted as “response files”. The contents of the
|
|
response file are interpreted as additional command line options. In
|
|
particular, the file is separated into whitespace-separated strings;
|
|
each such string is taken as a command-line option. The new options
|
|
are inserted in place of the option naming the response file, and
|
|
<code>*argcp</code> and <code>*argvp</code> will be updated. If the value of
|
|
<code>*argvp</code> is modified by this function, then the new value has
|
|
been dynamically allocated and can be deallocated by the caller with
|
|
<code>freeargv</code>. However, most callers will simply call
|
|
<code>expandargv</code> near the beginning of <code>main</code> and allow the
|
|
operating system to free the memory when the program exits.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fdmatch.c:23 -->
|
|
<div class="defun">
|
|
— Extension: int <b>fdmatch</b> (<var>int fd1, int fd2</var>)<var><a name="index-fdmatch-76"></a></var><br>
|
|
<blockquote>
|
|
<p>Check to see if two open file descriptors refer to the same file.
|
|
This is useful, for example, when we have an open file descriptor for
|
|
an unnamed file, and the name of a file that we believe to correspond
|
|
to that fd. This can happen when we are exec'd with an already open
|
|
file (<code>stdout</code> for example) or from the SVR4 <span class="file">/proc</span> calls
|
|
that return open file descriptors for mapped address spaces. All we
|
|
have to do is open the file by name and check the two file descriptors
|
|
for a match, which is done by comparing major and minor device numbers
|
|
and inode numbers.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fopen_unlocked.c:48 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>fdopen_unlocked</b> (<var>int fildes, const char * mode</var>)<var><a name="index-fdopen_005funlocked-77"></a></var><br>
|
|
<blockquote>
|
|
<p>Opens and returns a <code>FILE</code> pointer via <code>fdopen</code>. If the
|
|
operating system supports it, ensure that the stream is setup to avoid
|
|
any multi-threaded locking. Otherwise return the <code>FILE</code> pointer
|
|
unchanged.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- ffs.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>ffs</b> (<var>int valu</var>)<var><a name="index-ffs-78"></a></var><br>
|
|
<blockquote>
|
|
<p>Find the first (least significant) bit set in <var>valu</var>. Bits are
|
|
numbered from right to left, starting with bit 1 (corresponding to the
|
|
value 1). If <var>valu</var> is zero, zero is returned.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- filename_cmp.c:32 -->
|
|
<div class="defun">
|
|
— Extension: int <b>filename_cmp</b> (<var>const char *s1, const char *s2</var>)<var><a name="index-filename_005fcmp-79"></a></var><br>
|
|
<blockquote>
|
|
<p>Return zero if the two file names <var>s1</var> and <var>s2</var> are equivalent.
|
|
If not equivalent, the returned value is similar to what <code>strcmp</code>
|
|
would return. In other words, it returns a negative value if <var>s1</var>
|
|
is less than <var>s2</var>, or a positive value if <var>s2</var> is greater than
|
|
<var>s2</var>.
|
|
|
|
<p>This function does not normalize file names. As a result, this function
|
|
will treat filenames that are spelled differently as different even in
|
|
the case when the two filenames point to the same underlying file.
|
|
However, it does handle the fact that on DOS-like file systems, forward
|
|
and backward slashes are equal.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fnmatch.txh:1 -->
|
|
<div class="defun">
|
|
— Replacement: int <b>fnmatch</b> (<var>const char *pattern, const char *string, int flags</var>)<var><a name="index-fnmatch-80"></a></var><br>
|
|
<blockquote>
|
|
<p>Matches <var>string</var> against <var>pattern</var>, returning zero if it
|
|
matches, <code>FNM_NOMATCH</code> if not. <var>pattern</var> may contain the
|
|
wildcards <code>?</code> to match any one character, <code>*</code> to match any
|
|
zero or more characters, or a set of alternate characters in square
|
|
brackets, like <span class="samp">[a-gt8]</span>, which match one character (<code>a</code>
|
|
through <code>g</code>, or <code>t</code>, or <code>8</code>, in this example) if that one
|
|
character is in the set. A set may be inverted (i.e., match anything
|
|
except what's in the set) by giving <code>^</code> or <code>!</code> as the first
|
|
character in the set. To include those characters in the set, list them
|
|
as anything other than the first character of the set. To include a
|
|
dash in the set, list it last in the set. A backslash character makes
|
|
the following character not special, so for example you could match
|
|
against a literal asterisk with <span class="samp">\*</span>. To match a literal
|
|
backslash, use <span class="samp">\\</span>.
|
|
|
|
<p><code>flags</code> controls various aspects of the matching process, and is a
|
|
boolean OR of zero or more of the following values (defined in
|
|
<code><fnmatch.h></code>):
|
|
|
|
<dl>
|
|
<dt><code>FNM_PATHNAME</code><dt><code>FNM_FILE_NAME</code><dd><var>string</var> is assumed to be a path name. No wildcard will ever match
|
|
<code>/</code>.
|
|
|
|
<br><dt><code>FNM_NOESCAPE</code><dd>Do not interpret backslashes as quoting the following special character.
|
|
|
|
<br><dt><code>FNM_PERIOD</code><dd>A leading period (at the beginning of <var>string</var>, or if
|
|
<code>FNM_PATHNAME</code> after a slash) is not matched by <code>*</code> or
|
|
<code>?</code> but must be matched explicitly.
|
|
|
|
<br><dt><code>FNM_LEADING_DIR</code><dd>Means that <var>string</var> also matches <var>pattern</var> if some initial part
|
|
of <var>string</var> matches, and is followed by <code>/</code> and zero or more
|
|
characters. For example, <span class="samp">foo*</span> would match either <span class="samp">foobar</span>
|
|
or <span class="samp">foobar/grill</span>.
|
|
|
|
<br><dt><code>FNM_CASEFOLD</code><dd>Ignores case when performing the comparison.
|
|
|
|
</dl>
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fopen_unlocked.c:39 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>fopen_unlocked</b> (<var>const char *path, const char * mode</var>)<var><a name="index-fopen_005funlocked-81"></a></var><br>
|
|
<blockquote>
|
|
<p>Opens and returns a <code>FILE</code> pointer via <code>fopen</code>. If the
|
|
operating system supports it, ensure that the stream is setup to avoid
|
|
any multi-threaded locking. Otherwise return the <code>FILE</code> pointer
|
|
unchanged.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- argv.c:97 -->
|
|
<div class="defun">
|
|
— Extension: void <b>freeargv</b> (<var>char **vector</var>)<var><a name="index-freeargv-82"></a></var><br>
|
|
<blockquote>
|
|
<p>Free an argument vector that was built using <code>buildargv</code>. Simply
|
|
scans through <var>vector</var>, freeing the memory for each argument until
|
|
the terminating <code>NULL</code> is found, and then frees <var>vector</var>
|
|
itself.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fopen_unlocked.c:57 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>freopen_unlocked</b> (<var>const char * path, const char * mode, FILE * stream</var>)<var><a name="index-freopen_005funlocked-83"></a></var><br>
|
|
<blockquote>
|
|
<p>Opens and returns a <code>FILE</code> pointer via <code>freopen</code>. If the
|
|
operating system supports it, ensure that the stream is setup to avoid
|
|
any multi-threaded locking. Otherwise return the <code>FILE</code> pointer
|
|
unchanged.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- getruntime.c:82 -->
|
|
<div class="defun">
|
|
— Replacement: long <b>get_run_time</b> (<var>void</var>)<var><a name="index-get_005frun_005ftime-84"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the time used so far, in microseconds. If possible, this is
|
|
the time used by this process, else it is the elapsed time since the
|
|
process started.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- getcwd.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>getcwd</b> (<var>char *pathname, int len</var>)<var><a name="index-getcwd-85"></a></var><br>
|
|
<blockquote>
|
|
<p>Copy the absolute pathname for the current working directory into
|
|
<var>pathname</var>, which is assumed to point to a buffer of at least
|
|
<var>len</var> bytes, and return a pointer to the buffer. If the current
|
|
directory's path doesn't fit in <var>len</var> characters, the result is
|
|
<code>NULL</code> and <code>errno</code> is set. If <var>pathname</var> is a null pointer,
|
|
<code>getcwd</code> will obtain <var>len</var> bytes of space using
|
|
<code>malloc</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- getpagesize.c:5 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>getpagesize</b> (<var>void</var>)<var><a name="index-getpagesize-86"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the number of bytes in a page of memory. This is the
|
|
granularity of many of the system memory management routines. No
|
|
guarantee is made as to whether or not it is the same as the basic
|
|
memory management hardware page size.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- getpwd.c:5 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>getpwd</b> (<var>void</var>)<var><a name="index-getpwd-87"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the current working directory. This implementation caches the
|
|
result on the assumption that the process will not call <code>chdir</code>
|
|
between calls to <code>getpwd</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- gettimeofday.c:12 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>gettimeofday</b> (<var>struct timeval *tp, void *tz</var>)<var><a name="index-gettimeofday-88"></a></var><br>
|
|
<blockquote>
|
|
<p>Writes the current time to <var>tp</var>. This implementation requires
|
|
that <var>tz</var> be NULL. Returns 0 on success, -1 on failure.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- hex.c:33 -->
|
|
<div class="defun">
|
|
— Extension: void <b>hex_init</b> (<var>void</var>)<var><a name="index-hex_005finit-89"></a></var><br>
|
|
<blockquote>
|
|
<p>Initializes the array mapping the current character set to
|
|
corresponding hex values. This function must be called before any
|
|
call to <code>hex_p</code> or <code>hex_value</code>. If you fail to call it, a
|
|
default ASCII-based table will normally be used on ASCII systems.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- hex.c:42 -->
|
|
<div class="defun">
|
|
— Extension: int <b>hex_p</b> (<var>int c</var>)<var><a name="index-hex_005fp-90"></a></var><br>
|
|
<blockquote>
|
|
<p>Evaluates to non-zero if the given character is a valid hex character,
|
|
or zero if it is not. Note that the value you pass will be cast to
|
|
<code>unsigned char</code> within the macro.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- hex.c:50 -->
|
|
<div class="defun">
|
|
— Extension: unsigned int <b>hex_value</b> (<var>int c</var>)<var><a name="index-hex_005fvalue-91"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the numeric equivalent of the given character when interpreted
|
|
as a hexadecimal digit. The result is undefined if you pass an
|
|
invalid hex digit. Note that the value you pass will be cast to
|
|
<code>unsigned char</code> within the macro.
|
|
|
|
<p>The <code>hex_value</code> macro returns <code>unsigned int</code>, rather than
|
|
signed <code>int</code>, to make it easier to use in parsing addresses from
|
|
hex dump files: a signed <code>int</code> would be sign-extended when
|
|
converted to a wider unsigned type — like <code>bfd_vma</code>, on some
|
|
systems.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- index.c:5 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>index</b> (<var>char *s, int c</var>)<var><a name="index-index-92"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to the first occurrence of the character <var>c</var> in
|
|
the string <var>s</var>, or <code>NULL</code> if not found. The use of <code>index</code> is
|
|
deprecated in new programs in favor of <code>strchr</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- insque.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void <b>insque</b> (<var>struct qelem *elem, struct qelem *pred</var>)<var><a name="index-insque-93"></a></var><br>
|
|
— Supplemental: void <b>remque</b> (<var>struct qelem *elem</var>)<var><a name="index-remque-94"></a></var><br>
|
|
<blockquote>
|
|
<p>Routines to manipulate queues built from doubly linked lists. The
|
|
<code>insque</code> routine inserts <var>elem</var> in the queue immediately
|
|
after <var>pred</var>. The <code>remque</code> routine removes <var>elem</var> from
|
|
its containing queue. These routines expect to be passed pointers to
|
|
structures which have as their first members a forward pointer and a
|
|
back pointer, like this prototype (although no prototype is provided):
|
|
|
|
<pre class="example"> struct qelem {
|
|
struct qelem *q_forw;
|
|
struct qelem *q_back;
|
|
char q_data[];
|
|
};
|
|
</pre>
|
|
</blockquote></div>
|
|
|
|
<!-- safe-ctype.c:46 -->
|
|
<div class="defun">
|
|
— Extension: <b>ISALPHA</b> (<var>c</var>)<var><a name="index-ISALPHA-95"></a></var><br>
|
|
— Extension: <b>ISALNUM</b> (<var>c</var>)<var><a name="index-ISALNUM-96"></a></var><br>
|
|
— Extension: <b>ISBLANK</b> (<var>c</var>)<var><a name="index-ISBLANK-97"></a></var><br>
|
|
— Extension: <b>ISCNTRL</b> (<var>c</var>)<var><a name="index-ISCNTRL-98"></a></var><br>
|
|
— Extension: <b>ISDIGIT</b> (<var>c</var>)<var><a name="index-ISDIGIT-99"></a></var><br>
|
|
— Extension: <b>ISGRAPH</b> (<var>c</var>)<var><a name="index-ISGRAPH-100"></a></var><br>
|
|
— Extension: <b>ISLOWER</b> (<var>c</var>)<var><a name="index-ISLOWER-101"></a></var><br>
|
|
— Extension: <b>ISPRINT</b> (<var>c</var>)<var><a name="index-ISPRINT-102"></a></var><br>
|
|
— Extension: <b>ISPUNCT</b> (<var>c</var>)<var><a name="index-ISPUNCT-103"></a></var><br>
|
|
— Extension: <b>ISSPACE</b> (<var>c</var>)<var><a name="index-ISSPACE-104"></a></var><br>
|
|
— Extension: <b>ISUPPER</b> (<var>c</var>)<var><a name="index-ISUPPER-105"></a></var><br>
|
|
— Extension: <b>ISXDIGIT</b> (<var>c</var>)<var><a name="index-ISXDIGIT-106"></a></var><br>
|
|
<blockquote>
|
|
<p>These twelve macros are defined by <span class="file">safe-ctype.h</span>. Each has the
|
|
same meaning as the corresponding macro (with name in lowercase)
|
|
defined by the standard header <span class="file">ctype.h</span>. For example,
|
|
<code>ISALPHA</code> returns true for alphabetic characters and false for
|
|
others. However, there are two differences between these macros and
|
|
those provided by <span class="file">ctype.h</span>:
|
|
|
|
<ul>
|
|
<li>These macros are guaranteed to have well-defined behavior for all
|
|
values representable by <code>signed char</code> and <code>unsigned char</code>, and
|
|
for <code>EOF</code>.
|
|
|
|
<li>These macros ignore the current locale; they are true for these
|
|
fixed sets of characters:
|
|
<p><table summary=""><tr align="left"><td valign="top"><code>ALPHA</code> </td><td valign="top"><kbd>A-Za-z</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>ALNUM</code> </td><td valign="top"><kbd>A-Za-z0-9</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>BLANK</code> </td><td valign="top"><kbd>space tab</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>CNTRL</code> </td><td valign="top"><code>!PRINT</code>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>DIGIT</code> </td><td valign="top"><kbd>0-9</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>GRAPH</code> </td><td valign="top"><code>ALNUM || PUNCT</code>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>LOWER</code> </td><td valign="top"><kbd>a-z</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>PRINT</code> </td><td valign="top"><code>GRAPH ||</code> <kbd>space</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>PUNCT</code> </td><td valign="top"><kbd>`~!@#$%^&*()_-=+[{]}\|;:'",<.>/?</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>SPACE</code> </td><td valign="top"><kbd>space tab \n \r \f \v</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>UPPER</code> </td><td valign="top"><kbd>A-Z</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>XDIGIT</code> </td><td valign="top"><kbd>0-9A-Fa-f</kbd>
|
|
<br></td></tr></table>
|
|
|
|
<p>Note that, if the host character set is ASCII or a superset thereof,
|
|
all these macros will return false for all values of <code>char</code> outside
|
|
the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return
|
|
false for characters with numeric values from 128 to 255.
|
|
</ul>
|
|
</p></blockquote></div>
|
|
|
|
<!-- safe-ctype.c:95 -->
|
|
<div class="defun">
|
|
— Extension: <b>ISIDNUM</b> (<var>c</var>)<var><a name="index-ISIDNUM-107"></a></var><br>
|
|
— Extension: <b>ISIDST</b> (<var>c</var>)<var><a name="index-ISIDST-108"></a></var><br>
|
|
— Extension: <b>IS_VSPACE</b> (<var>c</var>)<var><a name="index-IS_005fVSPACE-109"></a></var><br>
|
|
— Extension: <b>IS_NVSPACE</b> (<var>c</var>)<var><a name="index-IS_005fNVSPACE-110"></a></var><br>
|
|
— Extension: <b>IS_SPACE_OR_NUL</b> (<var>c</var>)<var><a name="index-IS_005fSPACE_005fOR_005fNUL-111"></a></var><br>
|
|
— Extension: <b>IS_ISOBASIC</b> (<var>c</var>)<var><a name="index-IS_005fISOBASIC-112"></a></var><br>
|
|
<blockquote><p>These six macros are defined by <span class="file">safe-ctype.h</span> and provide
|
|
additional character classes which are useful when doing lexical
|
|
analysis of C or similar languages. They are true for the following
|
|
sets of characters:
|
|
|
|
<p><table summary=""><tr align="left"><td valign="top"><code>IDNUM</code> </td><td valign="top"><kbd>A-Za-z0-9_</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>IDST</code> </td><td valign="top"><kbd>A-Za-z_</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>VSPACE</code> </td><td valign="top"><kbd>\r \n</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>NVSPACE</code> </td><td valign="top"><kbd>space tab \f \v \0</kbd>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>SPACE_OR_NUL</code> </td><td valign="top"><code>VSPACE || NVSPACE</code>
|
|
<br></td></tr><tr align="left"><td valign="top"><code>ISOBASIC</code> </td><td valign="top"><code>VSPACE || NVSPACE || PRINT</code>
|
|
<br></td></tr></table>
|
|
</p></blockquote></div>
|
|
|
|
<!-- lbasename.c:23 -->
|
|
<div class="defun">
|
|
— Replacement: const char* <b>lbasename</b> (<var>const char *name</var>)<var><a name="index-lbasename-113"></a></var><br>
|
|
<blockquote>
|
|
<p>Given a pointer to a string containing a typical pathname
|
|
(<span class="samp">/usr/src/cmd/ls/ls.c</span> for example), returns a pointer to the
|
|
last component of the pathname (<span class="samp">ls.c</span> in this case). The
|
|
returned pointer is guaranteed to lie within the original
|
|
string. This latter fact is not true of many vendor C
|
|
libraries, which return special strings or modify the passed
|
|
strings for particular input.
|
|
|
|
<p>In particular, the empty string returns the same empty string,
|
|
and a path ending in <code>/</code> returns the empty string after it.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- lrealpath.c:25 -->
|
|
<div class="defun">
|
|
— Replacement: const char* <b>lrealpath</b> (<var>const char *name</var>)<var><a name="index-lrealpath-114"></a></var><br>
|
|
<blockquote>
|
|
<p>Given a pointer to a string containing a pathname, returns a canonical
|
|
version of the filename. Symlinks will be resolved, and “.” and “..”
|
|
components will be simplified. The returned value will be allocated using
|
|
<code>malloc</code>, or <code>NULL</code> will be returned on a memory allocation error.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- make-relative-prefix.c:24 -->
|
|
<div class="defun">
|
|
— Extension: const char* <b>make_relative_prefix</b> (<var>const char *progname, const char *bin_prefix, const char *prefix</var>)<var><a name="index-make_005frelative_005fprefix-115"></a></var><br>
|
|
<blockquote>
|
|
<p>Given three paths <var>progname</var>, <var>bin_prefix</var>, <var>prefix</var>,
|
|
return the path that is in the same position relative to
|
|
<var>progname</var>'s directory as <var>prefix</var> is relative to
|
|
<var>bin_prefix</var>. That is, a string starting with the directory
|
|
portion of <var>progname</var>, followed by a relative pathname of the
|
|
difference between <var>bin_prefix</var> and <var>prefix</var>.
|
|
|
|
<p>If <var>progname</var> does not contain any directory separators,
|
|
<code>make_relative_prefix</code> will search <span class="env">PATH</span> to find a program
|
|
named <var>progname</var>. Also, if <var>progname</var> is a symbolic link,
|
|
the symbolic link will be resolved.
|
|
|
|
<p>For example, if <var>bin_prefix</var> is <code>/alpha/beta/gamma/gcc/delta</code>,
|
|
<var>prefix</var> is <code>/alpha/beta/gamma/omega/</code>, and <var>progname</var> is
|
|
<code>/red/green/blue/gcc</code>, then this function will return
|
|
<code>/red/green/blue/../../omega/</code>.
|
|
|
|
<p>The return value is normally allocated via <code>malloc</code>. If no
|
|
relative prefix can be found, return <code>NULL</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- make-temp-file.c:137 -->
|
|
<div class="defun">
|
|
— Replacement: char* <b>make_temp_file</b> (<var>const char *suffix</var>)<var><a name="index-make_005ftemp_005ffile-116"></a></var><br>
|
|
<blockquote>
|
|
<p>Return a temporary file name (as a string) or <code>NULL</code> if unable to
|
|
create one. <var>suffix</var> is a suffix to append to the file name. The
|
|
string is <code>malloc</code>ed, and the temporary file has been created.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- memchr.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>memchr</b> (<var>const void *s, int c, size_t n</var>)<var><a name="index-memchr-117"></a></var><br>
|
|
<blockquote>
|
|
<p>This function searches memory starting at <code>*</code><var>s</var> for the
|
|
character <var>c</var>. The search only ends with the first occurrence of
|
|
<var>c</var>, or after <var>length</var> characters; in particular, a null
|
|
character does not terminate the search. If the character <var>c</var> is
|
|
found within <var>length</var> characters of <code>*</code><var>s</var>, a pointer
|
|
to the character is returned. If <var>c</var> is not found, then <code>NULL</code> is
|
|
returned.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- memcmp.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>memcmp</b> (<var>const void *x, const void *y, size_t count</var>)<var><a name="index-memcmp-118"></a></var><br>
|
|
<blockquote>
|
|
<p>Compares the first <var>count</var> bytes of two areas of memory. Returns
|
|
zero if they are the same, a value less than zero if <var>x</var> is
|
|
lexically less than <var>y</var>, or a value greater than zero if <var>x</var>
|
|
is lexically greater than <var>y</var>. Note that lexical order is determined
|
|
as if comparing unsigned char arrays.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- memcpy.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>memcpy</b> (<var>void *out, const void *in, size_t length</var>)<var><a name="index-memcpy-119"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies <var>length</var> bytes from memory region <var>in</var> to region
|
|
<var>out</var>. Returns a pointer to <var>out</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- memmove.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>memmove</b> (<var>void *from, const void *to, size_t count</var>)<var><a name="index-memmove-120"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies <var>count</var> bytes from memory area <var>from</var> to memory area
|
|
<var>to</var>, returning a pointer to <var>to</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- mempcpy.c:23 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>mempcpy</b> (<var>void *out, const void *in, size_t length</var>)<var><a name="index-mempcpy-121"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies <var>length</var> bytes from memory region <var>in</var> to region
|
|
<var>out</var>. Returns a pointer to <var>out</var> + <var>length</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- memset.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: void* <b>memset</b> (<var>void *s, int c, size_t count</var>)<var><a name="index-memset-122"></a></var><br>
|
|
<blockquote>
|
|
<p>Sets the first <var>count</var> bytes of <var>s</var> to the constant byte
|
|
<var>c</var>, returning a pointer to <var>s</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- mkstemps.c:58 -->
|
|
<div class="defun">
|
|
— Replacement: int <b>mkstemps</b> (<var>char *pattern, int suffix_len</var>)<var><a name="index-mkstemps-123"></a></var><br>
|
|
<blockquote>
|
|
<p>Generate a unique temporary file name from <var>pattern</var>.
|
|
<var>pattern</var> has the form:
|
|
|
|
<pre class="example"> <var>path</var>/ccXXXXXX<var>suffix</var>
|
|
</pre>
|
|
<p><var>suffix_len</var> tells us how long <var>suffix</var> is (it can be zero
|
|
length). The last six characters of <var>pattern</var> before <var>suffix</var>
|
|
must be <span class="samp">XXXXXX</span>; they are replaced with a string that makes the
|
|
filename unique. Returns a file descriptor open on the file for
|
|
reading and writing.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:266 -->
|
|
<div class="defun">
|
|
— Extension: void <b>pex_free</b> (<var>struct pex_obj obj</var>)<var><a name="index-pex_005ffree-124"></a></var><br>
|
|
<blockquote>
|
|
<p>Clean up and free all data associated with <var>obj</var>. If you have not
|
|
yet called <code>pex_get_times</code> or <code>pex_get_status</code>, this will
|
|
try to kill the subprocesses.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:241 -->
|
|
<div class="defun">
|
|
— Extension: int <b>pex_get_status</b> (<var>struct pex_obj *obj, int count, int *vector</var>)<var><a name="index-pex_005fget_005fstatus-125"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the exit status of all programs run using <var>obj</var>.
|
|
<var>count</var> is the number of results expected. The results will be
|
|
placed into <var>vector</var>. The results are in the order of the calls
|
|
to <code>pex_run</code>. Returns 0 on error, 1 on success.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:250 -->
|
|
<div class="defun">
|
|
— Extension: int <b>pex_get_times</b> (<var>struct pex_obj *obj, int count, struct pex_time *vector</var>)<var><a name="index-pex_005fget_005ftimes-126"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the process execution times of all programs run using
|
|
<var>obj</var>. <var>count</var> is the number of results expected. The
|
|
results will be placed into <var>vector</var>. The results are in the
|
|
order of the calls to <code>pex_run</code>. Returns 0 on error, 1 on
|
|
success.
|
|
|
|
<p><code>struct pex_time</code> has the following fields of the type
|
|
<code>unsigned long</code>: <code>user_seconds</code>,
|
|
<code>user_microseconds</code>, <code>system_seconds</code>,
|
|
<code>system_microseconds</code>. On systems which do not support reporting
|
|
process times, all the fields will be set to <code>0</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:2 -->
|
|
<div class="defun">
|
|
— Extension: struct pex_obj * <b>pex_init</b> (<var>int flags, const char *pname, const char *tempbase</var>)<var><a name="index-pex_005finit-127"></a></var><br>
|
|
<blockquote>
|
|
<p>Prepare to execute one or more programs, with standard output of each
|
|
program fed to standard input of the next. This is a system
|
|
independent interface to execute a pipeline.
|
|
|
|
<p><var>flags</var> is a bitwise combination of the following:
|
|
|
|
|
|
<a name="index-PEX_005fRECORD_005fTIMES-128"></a>
|
|
<dl><dt><code>PEX_RECORD_TIMES</code><dd>Record subprocess times if possible.
|
|
|
|
<p><a name="index-PEX_005fUSE_005fPIPES-129"></a><br><dt><code>PEX_USE_PIPES</code><dd>Use pipes for communication between processes, if possible.
|
|
|
|
<p><a name="index-PEX_005fSAVE_005fTEMPS-130"></a><br><dt><code>PEX_SAVE_TEMPS</code><dd>Don't delete temporary files used for communication between
|
|
processes.
|
|
|
|
</dl>
|
|
|
|
<p><var>pname</var> is the name of program to be executed, used in error
|
|
messages. <var>tempbase</var> is a base name to use for any required
|
|
temporary files; it may be <code>NULL</code> to use a randomly chosen name.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:155 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>pex_input_file</b> (<var>struct pex_obj *obj, int flags, const char *in_name</var>)<var><a name="index-pex_005finput_005ffile-131"></a></var><br>
|
|
<blockquote>
|
|
<p>Return a stream for a temporary file to pass to the first program in
|
|
the pipeline as input.
|
|
|
|
<p>The name of the input file is chosen according to the same rules
|
|
<code>pex_run</code> uses to choose output file names, based on
|
|
<var>in_name</var>, <var>obj</var> and the <code>PEX_SUFFIX</code> bit in <var>flags</var>.
|
|
|
|
<p>Don't call <code>fclose</code> on the returned stream; the first call to
|
|
<code>pex_run</code> closes it automatically.
|
|
|
|
<p>If <var>flags</var> includes <code>PEX_BINARY_OUTPUT</code>, open the stream in
|
|
binary mode; otherwise, open it in the default mode. Including
|
|
<code>PEX_BINARY_OUTPUT</code> in <var>flags</var> has no effect on Unix.
|
|
</p></blockquote></div>
|
|
|
|
<!-- pexecute.txh:172 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>pex_input_pipe</b> (<var>struct pex_obj *obj, int binary</var>)<var><a name="index-pex_005finput_005fpipe-132"></a></var><br>
|
|
<blockquote>
|
|
<p>Return a stream <var>fp</var> for a pipe connected to the standard input of
|
|
the first program in the pipeline; <var>fp</var> is opened for writing.
|
|
You must have passed <code>PEX_USE_PIPES</code> to the <code>pex_init</code> call
|
|
that returned <var>obj</var>.
|
|
|
|
<p>You must close <var>fp</var> using <code>fclose</code> yourself when you have
|
|
finished writing data to the pipeline.
|
|
|
|
<p>The file descriptor underlying <var>fp</var> is marked not to be inherited
|
|
by child processes.
|
|
|
|
<p>On systems that do not support pipes, this function returns
|
|
<code>NULL</code>, and sets <code>errno</code> to <code>EINVAL</code>. If you would
|
|
like to write code that is portable to all systems the <code>pex</code>
|
|
functions support, consider using <code>pex_input_file</code> instead.
|
|
|
|
<p>There are two opportunities for deadlock using
|
|
<code>pex_input_pipe</code>:
|
|
|
|
<ul>
|
|
<li>Most systems' pipes can buffer only a fixed amount of data; a process
|
|
that writes to a full pipe blocks. Thus, if you write to <span class="file">fp</span>
|
|
before starting the first process, you run the risk of blocking when
|
|
there is no child process yet to read the data and allow you to
|
|
continue. <code>pex_input_pipe</code> makes no promises about the
|
|
size of the pipe's buffer, so if you need to write any data at all
|
|
before starting the first process in the pipeline, consider using
|
|
<code>pex_input_file</code> instead.
|
|
|
|
<li>Using <code>pex_input_pipe</code> and <code>pex_read_output</code> together
|
|
may also cause deadlock. If the output pipe fills up, so that each
|
|
program in the pipeline is waiting for the next to read more data, and
|
|
you fill the input pipe by writing more data to <var>fp</var>, then there
|
|
is no way to make progress: the only process that could read data from
|
|
the output pipe is you, but you are blocked on the input pipe.
|
|
|
|
</ul>
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:274 -->
|
|
<div class="defun">
|
|
— Extension: const char * <b>pex_one</b> (<var>int flags, const char *executable, char * const *argv, const char *pname, const char *outname, const char *errname, int *status, int *err</var>)<var><a name="index-pex_005fone-133"></a></var><br>
|
|
<blockquote>
|
|
<p>An interface to permit the easy execution of a
|
|
single program. The return value and most of the parameters are as
|
|
for a call to <code>pex_run</code>. <var>flags</var> is restricted to a
|
|
combination of <code>PEX_SEARCH</code>, <code>PEX_STDERR_TO_STDOUT</code>, and
|
|
<code>PEX_BINARY_OUTPUT</code>. <var>outname</var> is interpreted as if
|
|
<code>PEX_LAST</code> were set. On a successful return, <code>*</code><var>status</var> will
|
|
be set to the exit status of the program.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:228 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>pex_read_err</b> (<var>struct pex_obj *obj, int binary</var>)<var><a name="index-pex_005fread_005ferr-134"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a <code>FILE</code> pointer which may be used to read the standard
|
|
error of the last program in the pipeline. When this is used,
|
|
<code>PEX_LAST</code> should not be used in a call to <code>pex_run</code>. After
|
|
this is called, <code>pex_run</code> may no longer be called with the same
|
|
<var>obj</var>. <var>binary</var> should be non-zero if the file should be
|
|
opened in binary mode. Don't call <code>fclose</code> on the returned file;
|
|
it will be closed by <code>pex_free</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:216 -->
|
|
<div class="defun">
|
|
— Extension: FILE * <b>pex_read_output</b> (<var>struct pex_obj *obj, int binary</var>)<var><a name="index-pex_005fread_005foutput-135"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a <code>FILE</code> pointer which may be used to read the standard
|
|
output of the last program in the pipeline. When this is used,
|
|
<code>PEX_LAST</code> should not be used in a call to <code>pex_run</code>. After
|
|
this is called, <code>pex_run</code> may no longer be called with the same
|
|
<var>obj</var>. <var>binary</var> should be non-zero if the file should be
|
|
opened in binary mode. Don't call <code>fclose</code> on the returned file;
|
|
it will be closed by <code>pex_free</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:33 -->
|
|
<div class="defun">
|
|
— Extension: const char * <b>pex_run</b> (<var>struct pex_obj *obj, int flags, const char *executable, char * const *argv, const char *outname, const char *errname, int *err</var>)<var><a name="index-pex_005frun-136"></a></var><br>
|
|
<blockquote>
|
|
<p>Execute one program in a pipeline. On success this returns
|
|
<code>NULL</code>. On failure it returns an error message, a statically
|
|
allocated string.
|
|
|
|
<p><var>obj</var> is returned by a previous call to <code>pex_init</code>.
|
|
|
|
<p><var>flags</var> is a bitwise combination of the following:
|
|
|
|
|
|
<a name="index-PEX_005fLAST-137"></a>
|
|
<dl><dt><code>PEX_LAST</code><dd>This must be set on the last program in the pipeline. In particular,
|
|
it should be set when executing a single program. The standard output
|
|
of the program will be sent to <var>outname</var>, or, if <var>outname</var> is
|
|
<code>NULL</code>, to the standard output of the calling program. Do <em>not</em>
|
|
set this bit if you want to call <code>pex_read_output</code>
|
|
(described below). After a call to <code>pex_run</code> with this bit set,
|
|
<var>pex_run</var> may no longer be called with the same <var>obj</var>.
|
|
|
|
<p><a name="index-PEX_005fSEARCH-138"></a><br><dt><code>PEX_SEARCH</code><dd>Search for the program using the user's executable search path.
|
|
|
|
<p><a name="index-PEX_005fSUFFIX-139"></a><br><dt><code>PEX_SUFFIX</code><dd><var>outname</var> is a suffix. See the description of <var>outname</var>,
|
|
below.
|
|
|
|
<p><a name="index-PEX_005fSTDERR_005fTO_005fSTDOUT-140"></a><br><dt><code>PEX_STDERR_TO_STDOUT</code><dd>Send the program's standard error to standard output, if possible.
|
|
|
|
<p><a name="index-PEX_005fBINARY_005fINPUT-141"></a><a name="index-PEX_005fBINARY_005fOUTPUT-142"></a><a name="index-PEX_005fBINARY_005fERROR-143"></a><br><dt><code>PEX_BINARY_INPUT</code><dt><code>PEX_BINARY_OUTPUT</code><dt><code>PEX_BINARY_ERROR</code><dd>The standard input (output or error) of the program should be read (written) in
|
|
binary mode rather than text mode. These flags are ignored on systems
|
|
which do not distinguish binary mode and text mode, such as Unix. For
|
|
proper behavior these flags should match appropriately—a call to
|
|
<code>pex_run</code> using <code>PEX_BINARY_OUTPUT</code> should be followed by a
|
|
call using <code>PEX_BINARY_INPUT</code>.
|
|
|
|
<p><a name="index-PEX_005fSTDERR_005fTO_005fPIPE-144"></a><br><dt><code>PEX_STDERR_TO_PIPE</code><dd>Send the program's standard error to a pipe, if possible. This flag
|
|
cannot be specified together with <code>PEX_STDERR_TO_STDOUT</code>. This
|
|
flag can be specified only on the last program in pipeline.
|
|
|
|
</dl>
|
|
|
|
<p><var>executable</var> is the program to execute. <var>argv</var> is the set of
|
|
arguments to pass to the program; normally <var>argv</var><code>[0]</code> will
|
|
be a copy of <var>executable</var>.
|
|
|
|
<p><var>outname</var> is used to set the name of the file to use for standard
|
|
output. There are two cases in which no output file will be used:
|
|
|
|
<ol type=1 start=1>
|
|
<li>if <code>PEX_LAST</code> is not set in <var>flags</var>, and <code>PEX_USE_PIPES</code>
|
|
was set in the call to <code>pex_init</code>, and the system supports pipes
|
|
|
|
<li>if <code>PEX_LAST</code> is set in <var>flags</var>, and <var>outname</var> is
|
|
<code>NULL</code>
|
|
</ol>
|
|
|
|
<p class="noindent">Otherwise the code will use a file to hold standard
|
|
output. If <code>PEX_LAST</code> is not set, this file is considered to be
|
|
a temporary file, and it will be removed when no longer needed, unless
|
|
<code>PEX_SAVE_TEMPS</code> was set in the call to <code>pex_init</code>.
|
|
|
|
<p>There are two cases to consider when setting the name of the file to
|
|
hold standard output.
|
|
|
|
<ol type=1 start=1>
|
|
<li><code>PEX_SUFFIX</code> is set in <var>flags</var>. In this case
|
|
<var>outname</var> may not be <code>NULL</code>. If the <var>tempbase</var> parameter
|
|
to <code>pex_init</code> was not <code>NULL</code>, then the output file name is
|
|
the concatenation of <var>tempbase</var> and <var>outname</var>. If
|
|
<var>tempbase</var> was <code>NULL</code>, then the output file name is a random
|
|
file name ending in <var>outname</var>.
|
|
|
|
<li><code>PEX_SUFFIX</code> was not set in <var>flags</var>. In this
|
|
case, if <var>outname</var> is not <code>NULL</code>, it is used as the output
|
|
file name. If <var>outname</var> is <code>NULL</code>, and <var>tempbase</var> was
|
|
not NULL, the output file name is randomly chosen using
|
|
<var>tempbase</var>. Otherwise the output file name is chosen completely
|
|
at random.
|
|
</ol>
|
|
|
|
<p><var>errname</var> is the file name to use for standard error output. If
|
|
it is <code>NULL</code>, standard error is the same as the caller's.
|
|
Otherwise, standard error is written to the named file.
|
|
|
|
<p>On an error return, the code sets <code>*</code><var>err</var> to an <code>errno</code>
|
|
value, or to 0 if there is no relevant <code>errno</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:142 -->
|
|
<div class="defun">
|
|
— Extension: const char * <b>pex_run_in_environment</b> (<var>struct pex_obj *obj, int flags, const char *executable, char * const *argv, char * const *env, int env_size, const char *outname, const char *errname, int *err</var>)<var><a name="index-pex_005frun_005fin_005fenvironment-145"></a></var><br>
|
|
<blockquote>
|
|
<p>Execute one program in a pipeline, permitting the environment for the
|
|
program to be specified. Behaviour and parameters not listed below are
|
|
as for <code>pex_run</code>.
|
|
|
|
<p><var>env</var> is the environment for the child process, specified as an array of
|
|
character pointers. Each element of the array should point to a string of the
|
|
form <code>VAR=VALUE</code>, with the exception of the last element that must be
|
|
<code>NULL</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:286 -->
|
|
<div class="defun">
|
|
— Extension: int <b>pexecute</b> (<var>const char *program, char * const *argv, const char *this_pname, const char *temp_base, char **errmsg_fmt, char **errmsg_arg, int flags</var>)<var><a name="index-pexecute-146"></a></var><br>
|
|
<blockquote>
|
|
<p>This is the old interface to execute one or more programs. It is
|
|
still supported for compatibility purposes, but is no longer
|
|
documented.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strsignal.c:541 -->
|
|
<div class="defun">
|
|
— Supplemental: void <b>psignal</b> (<var>int signo, char *message</var>)<var><a name="index-psignal-147"></a></var><br>
|
|
<blockquote>
|
|
<p>Print <var>message</var> to the standard error, followed by a colon,
|
|
followed by the description of the signal specified by <var>signo</var>,
|
|
followed by a newline.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- putenv.c:21 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>putenv</b> (<var>const char *string</var>)<var><a name="index-putenv-148"></a></var><br>
|
|
<blockquote>
|
|
<p>Uses <code>setenv</code> or <code>unsetenv</code> to put <var>string</var> into
|
|
the environment or remove it. If <var>string</var> is of the form
|
|
<span class="samp">name=value</span> the string is added; if no <span class="samp">=</span> is present the
|
|
name is unset/removed.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- pexecute.txh:294 -->
|
|
<div class="defun">
|
|
— Extension: int <b>pwait</b> (<var>int pid, int *status, int flags</var>)<var><a name="index-pwait-149"></a></var><br>
|
|
<blockquote>
|
|
<p>Another part of the old execution interface.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- random.c:39 -->
|
|
<div class="defun">
|
|
— Supplement: long int <b>random</b> (<var>void</var>)<var><a name="index-random-150"></a></var><br>
|
|
— Supplement: void <b>srandom</b> (<var>unsigned int seed</var>)<var><a name="index-srandom-151"></a></var><br>
|
|
— Supplement: void* <b>initstate</b> (<var>unsigned int seed, void *arg_state, unsigned long n</var>)<var><a name="index-initstate-152"></a></var><br>
|
|
— Supplement: void* <b>setstate</b> (<var>void *arg_state</var>)<var><a name="index-setstate-153"></a></var><br>
|
|
<blockquote>
|
|
<p>Random number functions. <code>random</code> returns a random number in the
|
|
range 0 to <code>LONG_MAX</code>. <code>srandom</code> initializes the random
|
|
number generator to some starting point determined by <var>seed</var>
|
|
(else, the values returned by <code>random</code> are always the same for each
|
|
run of the program). <code>initstate</code> and <code>setstate</code> allow fine-grained
|
|
control over the state of the random number generator.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- concat.c:173 -->
|
|
<div class="defun">
|
|
— Extension: char* <b>reconcat</b> (<var>char *optr, const char *s1, <small class="dots">...</small>, </var><code>NULL</code>)<var><a name="index-reconcat-154"></a></var><br>
|
|
<blockquote>
|
|
<p>Same as <code>concat</code>, except that if <var>optr</var> is not <code>NULL</code> it
|
|
is freed after the string is created. This is intended to be useful
|
|
when you're extending an existing string or building up a string in a
|
|
loop:
|
|
|
|
<pre class="example"> str = reconcat (str, "pre-", str, NULL);
|
|
</pre>
|
|
</blockquote></div>
|
|
|
|
<!-- rename.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>rename</b> (<var>const char *old, const char *new</var>)<var><a name="index-rename-155"></a></var><br>
|
|
<blockquote>
|
|
<p>Renames a file from <var>old</var> to <var>new</var>. If <var>new</var> already
|
|
exists, it is removed.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- rindex.c:5 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>rindex</b> (<var>const char *s, int c</var>)<var><a name="index-rindex-156"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to the last occurrence of the character <var>c</var> in
|
|
the string <var>s</var>, or <code>NULL</code> if not found. The use of <code>rindex</code> is
|
|
deprecated in new programs in favor of <code>strrchr</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- setenv.c:22 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>setenv</b> (<var>const char *name, const char *value, int overwrite</var>)<var><a name="index-setenv-157"></a></var><br>
|
|
— Supplemental: void <b>unsetenv</b> (<var>const char *name</var>)<var><a name="index-unsetenv-158"></a></var><br>
|
|
<blockquote>
|
|
<p><code>setenv</code> adds <var>name</var> to the environment with value
|
|
<var>value</var>. If the name was already present in the environment,
|
|
the new value will be stored only if <var>overwrite</var> is nonzero.
|
|
The companion <code>unsetenv</code> function removes <var>name</var> from the
|
|
environment. This implementation is not safe for multithreaded code.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strsignal.c:348 -->
|
|
<div class="defun">
|
|
— Extension: int <b>signo_max</b> (<var>void</var>)<var><a name="index-signo_005fmax-159"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns the maximum signal value for which a corresponding symbolic
|
|
name or message is available. Note that in the case where we use the
|
|
<code>sys_siglist</code> supplied by the system, it is possible for there to
|
|
be more symbolic names than messages, or vice versa. In fact, the
|
|
manual page for <code>psignal(3b)</code> explicitly warns that one should
|
|
check the size of the table (<code>NSIG</code>) before indexing it, since
|
|
new signal codes may be added to the system before they are added to
|
|
the table. Thus <code>NSIG</code> might be smaller than value implied by
|
|
the largest signo value defined in <code><signal.h></code>.
|
|
|
|
<p>We return the maximum value that can be used to obtain a meaningful
|
|
symbolic name or message.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- sigsetmask.c:8 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>sigsetmask</b> (<var>int set</var>)<var><a name="index-sigsetmask-160"></a></var><br>
|
|
<blockquote>
|
|
<p>Sets the signal mask to the one provided in <var>set</var> and returns
|
|
the old mask (which, for libiberty's implementation, will always
|
|
be the value <code>1</code>).
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- snprintf.c:28 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>snprintf</b> (<var>char *buf, size_t n, const char *format, ...</var>)<var><a name="index-snprintf-161"></a></var><br>
|
|
<blockquote>
|
|
<p>This function is similar to sprintf, but it will print at most <var>n</var>
|
|
characters. On error the return value is -1, otherwise it returns the
|
|
number of characters that would have been printed had <var>n</var> been
|
|
sufficiently large, regardless of the actual value of <var>n</var>. Note
|
|
some pre-C99 system libraries do not implement this correctly so users
|
|
cannot generally rely on the return value if the system version of
|
|
this function is used.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- spaces.c:22 -->
|
|
<div class="defun">
|
|
— Extension: char* <b>spaces</b> (<var>int count</var>)<var><a name="index-spaces-162"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to a memory region filled with the specified
|
|
number of spaces and null terminated. The returned pointer is
|
|
valid until at least the next call.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- stpcpy.c:23 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>stpcpy</b> (<var>char *dst, const char *src</var>)<var><a name="index-stpcpy-163"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies the string <var>src</var> into <var>dst</var>. Returns a pointer to
|
|
<var>dst</var> + strlen(<var>src</var>).
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- stpncpy.c:23 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>stpncpy</b> (<var>char *dst, const char *src, size_t len</var>)<var><a name="index-stpncpy-164"></a></var><br>
|
|
<blockquote>
|
|
<p>Copies the string <var>src</var> into <var>dst</var>, copying exactly <var>len</var>
|
|
and padding with zeros if necessary. If <var>len</var> < strlen(<var>src</var>)
|
|
then return <var>dst</var> + <var>len</var>, otherwise returns <var>dst</var> +
|
|
strlen(<var>src</var>).
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strcasecmp.c:15 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>strcasecmp</b> (<var>const char *s1, const char *s2</var>)<var><a name="index-strcasecmp-165"></a></var><br>
|
|
<blockquote>
|
|
<p>A case-insensitive <code>strcmp</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strchr.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>strchr</b> (<var>const char *s, int c</var>)<var><a name="index-strchr-166"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to the first occurrence of the character <var>c</var> in
|
|
the string <var>s</var>, or <code>NULL</code> if not found. If <var>c</var> is itself the
|
|
null character, the results are undefined.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strdup.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>strdup</b> (<var>const char *s</var>)<var><a name="index-strdup-167"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to a copy of <var>s</var> in memory obtained from
|
|
<code>malloc</code>, or <code>NULL</code> if insufficient memory was available.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strerror.c:670 -->
|
|
<div class="defun">
|
|
— Replacement: const char* <b>strerrno</b> (<var>int errnum</var>)<var><a name="index-strerrno-168"></a></var><br>
|
|
<blockquote>
|
|
<p>Given an error number returned from a system call (typically returned
|
|
in <code>errno</code>), returns a pointer to a string containing the
|
|
symbolic name of that error number, as found in <code><errno.h></code>.
|
|
|
|
<p>If the supplied error number is within the valid range of indices for
|
|
symbolic names, but no name is available for the particular error
|
|
number, then returns the string <span class="samp">Error </span><var>num</var>, where <var>num</var>
|
|
is the error number.
|
|
|
|
<p>If the supplied error number is not within the range of valid
|
|
indices, then returns <code>NULL</code>.
|
|
|
|
<p>The contents of the location pointed to are only guaranteed to be
|
|
valid until the next call to <code>strerrno</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strerror.c:603 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>strerror</b> (<var>int errnoval</var>)<var><a name="index-strerror-169"></a></var><br>
|
|
<blockquote>
|
|
<p>Maps an <code>errno</code> number to an error message string, the contents
|
|
of which are implementation defined. On systems which have the
|
|
external variables <code>sys_nerr</code> and <code>sys_errlist</code>, these
|
|
strings will be the same as the ones used by <code>perror</code>.
|
|
|
|
<p>If the supplied error number is within the valid range of indices for
|
|
the <code>sys_errlist</code>, but no message is available for the particular
|
|
error number, then returns the string <span class="samp">Error </span><var>num</var>, where
|
|
<var>num</var> is the error number.
|
|
|
|
<p>If the supplied error number is not a valid index into
|
|
<code>sys_errlist</code>, returns <code>NULL</code>.
|
|
|
|
<p>The returned string is only guaranteed to be valid only until the
|
|
next call to <code>strerror</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strncasecmp.c:15 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>strncasecmp</b> (<var>const char *s1, const char *s2</var>)<var><a name="index-strncasecmp-170"></a></var><br>
|
|
<blockquote>
|
|
<p>A case-insensitive <code>strncmp</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strncmp.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>strncmp</b> (<var>const char *s1, const char *s2, size_t n</var>)<var><a name="index-strncmp-171"></a></var><br>
|
|
<blockquote>
|
|
<p>Compares the first <var>n</var> bytes of two strings, returning a value as
|
|
<code>strcmp</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strndup.c:23 -->
|
|
<div class="defun">
|
|
— Extension: char* <b>strndup</b> (<var>const char *s, size_t n</var>)<var><a name="index-strndup-172"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to a copy of <var>s</var> with at most <var>n</var> characters
|
|
in memory obtained from <code>malloc</code>, or <code>NULL</code> if insufficient
|
|
memory was available. The result is always NUL terminated.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strrchr.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>strrchr</b> (<var>const char *s, int c</var>)<var><a name="index-strrchr-173"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to the last occurrence of the character <var>c</var> in
|
|
the string <var>s</var>, or <code>NULL</code> if not found. If <var>c</var> is itself the
|
|
null character, the results are undefined.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strsignal.c:383 -->
|
|
<div class="defun">
|
|
— Supplemental: const char * <b>strsignal</b> (<var>int signo</var>)<var><a name="index-strsignal-174"></a></var><br>
|
|
<blockquote>
|
|
<p>Maps an signal number to an signal message string, the contents of
|
|
which are implementation defined. On systems which have the external
|
|
variable <code>sys_siglist</code>, these strings will be the same as the
|
|
ones used by <code>psignal()</code>.
|
|
|
|
<p>If the supplied signal number is within the valid range of indices for
|
|
the <code>sys_siglist</code>, but no message is available for the particular
|
|
signal number, then returns the string <span class="samp">Signal </span><var>num</var>, where
|
|
<var>num</var> is the signal number.
|
|
|
|
<p>If the supplied signal number is not a valid index into
|
|
<code>sys_siglist</code>, returns <code>NULL</code>.
|
|
|
|
<p>The returned string is only guaranteed to be valid only until the next
|
|
call to <code>strsignal</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strsignal.c:448 -->
|
|
<div class="defun">
|
|
— Extension: const char* <b>strsigno</b> (<var>int signo</var>)<var><a name="index-strsigno-175"></a></var><br>
|
|
<blockquote>
|
|
<p>Given an signal number, returns a pointer to a string containing the
|
|
symbolic name of that signal number, as found in <code><signal.h></code>.
|
|
|
|
<p>If the supplied signal number is within the valid range of indices for
|
|
symbolic names, but no name is available for the particular signal
|
|
number, then returns the string <span class="samp">Signal </span><var>num</var>, where
|
|
<var>num</var> is the signal number.
|
|
|
|
<p>If the supplied signal number is not within the range of valid
|
|
indices, then returns <code>NULL</code>.
|
|
|
|
<p>The contents of the location pointed to are only guaranteed to be
|
|
valid until the next call to <code>strsigno</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strstr.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>strstr</b> (<var>const char *string, const char *sub</var>)<var><a name="index-strstr-176"></a></var><br>
|
|
<blockquote>
|
|
<p>This function searches for the substring <var>sub</var> in the string
|
|
<var>string</var>, not including the terminating null characters. A pointer
|
|
to the first occurrence of <var>sub</var> is returned, or <code>NULL</code> if the
|
|
substring is absent. If <var>sub</var> points to a string with zero
|
|
length, the function returns <var>string</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strtod.c:27 -->
|
|
<div class="defun">
|
|
— Supplemental: double <b>strtod</b> (<var>const char *string, char **endptr</var>)<var><a name="index-strtod-177"></a></var><br>
|
|
<blockquote>
|
|
<p>This ISO C function converts the initial portion of <var>string</var> to a
|
|
<code>double</code>. If <var>endptr</var> is not <code>NULL</code>, a pointer to the
|
|
character after the last character used in the conversion is stored in
|
|
the location referenced by <var>endptr</var>. If no conversion is
|
|
performed, zero is returned and the value of <var>string</var> is stored in
|
|
the location referenced by <var>endptr</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strerror.c:729 -->
|
|
<div class="defun">
|
|
— Extension: int <b>strtoerrno</b> (<var>const char *name</var>)<var><a name="index-strtoerrno-178"></a></var><br>
|
|
<blockquote>
|
|
<p>Given the symbolic name of a error number (e.g., <code>EACCES</code>), map it
|
|
to an errno value. If no translation is found, returns 0.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strtol.c:33 -->
|
|
<div class="defun">
|
|
— Supplemental: long int <b>strtol</b> (<var>const char *string, char **endptr, int base</var>)<var><a name="index-strtol-179"></a></var><br>
|
|
— Supplemental: unsigned long int <b>strtoul</b> (<var>const char *string, char **endptr, int base</var>)<var><a name="index-strtoul-180"></a></var><br>
|
|
<blockquote>
|
|
<p>The <code>strtol</code> function converts the string in <var>string</var> to a
|
|
long integer value according to the given <var>base</var>, which must be
|
|
between 2 and 36 inclusive, or be the special value 0. If <var>base</var>
|
|
is 0, <code>strtol</code> will look for the prefixes <code>0</code> and <code>0x</code>
|
|
to indicate bases 8 and 16, respectively, else default to base 10.
|
|
When the base is 16 (either explicitly or implicitly), a prefix of
|
|
<code>0x</code> is allowed. The handling of <var>endptr</var> is as that of
|
|
<code>strtod</code> above. The <code>strtoul</code> function is the same, except
|
|
that the converted value is unsigned.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strsignal.c:502 -->
|
|
<div class="defun">
|
|
— Extension: int <b>strtosigno</b> (<var>const char *name</var>)<var><a name="index-strtosigno-181"></a></var><br>
|
|
<blockquote>
|
|
<p>Given the symbolic name of a signal, map it to a signal number. If no
|
|
translation is found, returns 0.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- strverscmp.c:25 -->
|
|
<div class="defun">
|
|
— Function: int <b>strverscmp</b> (<var>const char *s1, const char *s2</var>)<var><a name="index-strverscmp-182"></a></var><br>
|
|
<blockquote><p>The <code>strverscmp</code> function compares the string <var>s1</var> against
|
|
<var>s2</var>, considering them as holding indices/version numbers. Return
|
|
value follows the same conventions as found in the <code>strverscmp</code>
|
|
function. In fact, if <var>s1</var> and <var>s2</var> contain no digits,
|
|
<code>strverscmp</code> behaves like <code>strcmp</code>.
|
|
|
|
<p>Basically, we compare strings normally (character by character), until
|
|
we find a digit in each string - then we enter a special comparison
|
|
mode, where each sequence of digits is taken as a whole. If we reach the
|
|
end of these two parts without noticing a difference, we return to the
|
|
standard comparison mode. There are two types of numeric parts:
|
|
"integral" and "fractional" (those begin with a '0'). The types
|
|
of the numeric parts affect the way we sort them:
|
|
|
|
<ul>
|
|
<li>integral/integral: we compare values as you would expect.
|
|
|
|
<li>fractional/integral: the fractional part is less than the integral one.
|
|
Again, no surprise.
|
|
|
|
<li>fractional/fractional: the things become a bit more complex.
|
|
If the common prefix contains only leading zeroes, the longest part is less
|
|
than the other one; else the comparison behaves normally.
|
|
</ul>
|
|
|
|
<pre class="smallexample"> strverscmp ("no digit", "no digit")
|
|
=> 0 // <span class="roman">same behavior as strcmp.</span>
|
|
strverscmp ("item#99", "item#100")
|
|
=> <0 // <span class="roman">same prefix, but 99 < 100.</span>
|
|
strverscmp ("alpha1", "alpha001")
|
|
=> >0 // <span class="roman">fractional part inferior to integral one.</span>
|
|
strverscmp ("part1_f012", "part1_f01")
|
|
=> >0 // <span class="roman">two fractional parts.</span>
|
|
strverscmp ("foo.009", "foo.0")
|
|
=> <0 // <span class="roman">idem, but with leading zeroes only.</span>
|
|
</pre>
|
|
<p>This function is especially useful when dealing with filename sorting,
|
|
because filenames frequently hold indices/version numbers.
|
|
</p></blockquote></div>
|
|
|
|
<!-- tmpnam.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: char* <b>tmpnam</b> (<var>char *s</var>)<var><a name="index-tmpnam-183"></a></var><br>
|
|
<blockquote>
|
|
<p>This function attempts to create a name for a temporary file, which
|
|
will be a valid file name yet not exist when <code>tmpnam</code> checks for
|
|
it. <var>s</var> must point to a buffer of at least <code>L_tmpnam</code> bytes,
|
|
or be <code>NULL</code>. Use of this function creates a security risk, and it must
|
|
not be used in new projects. Use <code>mkstemp</code> instead.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- unlink-if-ordinary.c:27 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>unlink_if_ordinary</b> (<var>const char*</var>)<var><a name="index-unlink_005fif_005fordinary-184"></a></var><br>
|
|
<blockquote>
|
|
<p>Unlinks the named file, unless it is special (e.g. a device file).
|
|
Returns 0 when the file was unlinked, a negative value (and errno set) when
|
|
there was an error deleting the file, and a positive value if no attempt
|
|
was made to unlink the file because it is special.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fopen_unlocked.c:31 -->
|
|
<div class="defun">
|
|
— Extension: void <b>unlock_std_streams</b> (<var>void</var>)<var><a name="index-unlock_005fstd_005fstreams-185"></a></var><br>
|
|
<blockquote>
|
|
<p>If the OS supports it, ensure that the standard I/O streams,
|
|
<code>stdin</code>, <code>stdout</code> and <code>stderr</code> are setup to avoid any
|
|
multi-threaded locking. Otherwise do nothing.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- fopen_unlocked.c:23 -->
|
|
<div class="defun">
|
|
— Extension: void <b>unlock_stream</b> (<var>FILE * stream</var>)<var><a name="index-unlock_005fstream-186"></a></var><br>
|
|
<blockquote>
|
|
<p>If the OS supports it, ensure that the supplied stream is setup to
|
|
avoid any multi-threaded locking. Otherwise leave the <code>FILE</code>
|
|
pointer unchanged. If the <var>stream</var> is <code>NULL</code> do nothing.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- vasprintf.c:47 -->
|
|
<div class="defun">
|
|
— Extension: int <b>vasprintf</b> (<var>char **resptr, const char *format, va_list args</var>)<var><a name="index-vasprintf-187"></a></var><br>
|
|
<blockquote>
|
|
<p>Like <code>vsprintf</code>, but instead of passing a pointer to a buffer,
|
|
you pass a pointer to a pointer. This function will compute the size
|
|
of the buffer needed, allocate memory with <code>malloc</code>, and store a
|
|
pointer to the allocated memory in <code>*</code><var>resptr</var>. The value
|
|
returned is the same as <code>vsprintf</code> would return. If memory could
|
|
not be allocated, minus one is returned and <code>NULL</code> is stored in
|
|
<code>*</code><var>resptr</var>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- vfork.c:6 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>vfork</b> (<var>void</var>)<var><a name="index-vfork-188"></a></var><br>
|
|
<blockquote>
|
|
<p>Emulates <code>vfork</code> by calling <code>fork</code> and returning its value.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- vprintf.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>vprintf</b> (<var>const char *format, va_list ap</var>)<var><a name="index-vprintf-189"></a></var><br>
|
|
— Supplemental: int <b>vfprintf</b> (<var>FILE *stream, const char *format, va_list ap</var>)<var><a name="index-vfprintf-190"></a></var><br>
|
|
— Supplemental: int <b>vsprintf</b> (<var>char *str, const char *format, va_list ap</var>)<var><a name="index-vsprintf-191"></a></var><br>
|
|
<blockquote>
|
|
<p>These functions are the same as <code>printf</code>, <code>fprintf</code>, and
|
|
<code>sprintf</code>, respectively, except that they are called with a
|
|
<code>va_list</code> instead of a variable number of arguments. Note that
|
|
they do not call <code>va_end</code>; this is the application's
|
|
responsibility. In <code>libiberty</code> they are implemented in terms of the
|
|
nonstandard but common function <code>_doprnt</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- vsnprintf.c:28 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>vsnprintf</b> (<var>char *buf, size_t n, const char *format, va_list ap</var>)<var><a name="index-vsnprintf-192"></a></var><br>
|
|
<blockquote>
|
|
<p>This function is similar to vsprintf, but it will print at most
|
|
<var>n</var> characters. On error the return value is -1, otherwise it
|
|
returns the number of characters that would have been printed had
|
|
<var>n</var> been sufficiently large, regardless of the actual value of
|
|
<var>n</var>. Note some pre-C99 system libraries do not implement this
|
|
correctly so users cannot generally rely on the return value if the
|
|
system version of this function is used.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- waitpid.c:3 -->
|
|
<div class="defun">
|
|
— Supplemental: int <b>waitpid</b> (<var>int pid, int *status, int</var>)<var><a name="index-waitpid-193"></a></var><br>
|
|
<blockquote>
|
|
<p>This is a wrapper around the <code>wait</code> function. Any “special”
|
|
values of <var>pid</var> depend on your implementation of <code>wait</code>, as
|
|
does the return value. The third argument is unused in <code>libiberty</code>.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- argv.c:293 -->
|
|
<div class="defun">
|
|
— Extension: int <b>writeargv</b> (<var>const char **argv, FILE *file</var>)<var><a name="index-writeargv-194"></a></var><br>
|
|
<blockquote>
|
|
<p>Write each member of ARGV, handling all necessary quoting, to the file
|
|
named by FILE, separated by whitespace. Return 0 on success, non-zero
|
|
if an error occurred while writing to FILE.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xatexit.c:11 -->
|
|
<div class="defun">
|
|
— Function: int <b>xatexit</b> (<var>void </var>(<var>*fn</var>) (<var>void</var>))<var><a name="index-xatexit-195"></a></var><br>
|
|
<blockquote>
|
|
<p>Behaves as the standard <code>atexit</code> function, but with no limit on
|
|
the number of registered functions. Returns 0 on success, or −1 on
|
|
failure. If you use <code>xatexit</code> to register functions, you must use
|
|
<code>xexit</code> to terminate your program.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmalloc.c:38 -->
|
|
<div class="defun">
|
|
— Replacement: void* <b>xcalloc</b> (<var>size_t nelem, size_t elsize</var>)<var><a name="index-xcalloc-196"></a></var><br>
|
|
<blockquote>
|
|
<p>Allocate memory without fail, and set it to zero. This routine functions
|
|
like <code>calloc</code>, but will behave the same as <code>xmalloc</code> if memory
|
|
cannot be found.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xexit.c:22 -->
|
|
<div class="defun">
|
|
— Replacement: void <b>xexit</b> (<var>int code</var>)<var><a name="index-xexit-197"></a></var><br>
|
|
<blockquote>
|
|
<p>Terminates the program. If any functions have been registered with
|
|
the <code>xatexit</code> replacement function, they will be called first.
|
|
Termination is handled via the system's normal <code>exit</code> call.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmalloc.c:22 -->
|
|
<div class="defun">
|
|
— Replacement: void* <b>xmalloc</b> (<var>size_t</var>)<var><a name="index-xmalloc-198"></a></var><br>
|
|
<blockquote>
|
|
<p>Allocate memory without fail. If <code>malloc</code> fails, this will print
|
|
a message to <code>stderr</code> (using the name set by
|
|
<code>xmalloc_set_program_name</code>,
|
|
if any) and then call <code>xexit</code>. Note that it is therefore safe for
|
|
a program to contain <code>#define malloc xmalloc</code> in its source.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmalloc.c:53 -->
|
|
<div class="defun">
|
|
— Replacement: void <b>xmalloc_failed</b> (<var>size_t</var>)<var><a name="index-xmalloc_005ffailed-199"></a></var><br>
|
|
<blockquote>
|
|
<p>This function is not meant to be called by client code, and is listed
|
|
here for completeness only. If any of the allocation routines fail, this
|
|
function will be called to print an error message and terminate execution.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmalloc.c:46 -->
|
|
<div class="defun">
|
|
— Replacement: void <b>xmalloc_set_program_name</b> (<var>const char *name</var>)<var><a name="index-xmalloc_005fset_005fprogram_005fname-200"></a></var><br>
|
|
<blockquote>
|
|
<p>You can use this to set the name of the program used by
|
|
<code>xmalloc_failed</code> when printing a failure message.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmemdup.c:7 -->
|
|
<div class="defun">
|
|
— Replacement: void* <b>xmemdup</b> (<var>void *input, size_t copy_size, size_t alloc_size</var>)<var><a name="index-xmemdup-201"></a></var><br>
|
|
<blockquote>
|
|
<p>Duplicates a region of memory without fail. First, <var>alloc_size</var> bytes
|
|
are allocated, then <var>copy_size</var> bytes from <var>input</var> are copied into
|
|
it, and the new memory is returned. If fewer bytes are copied than were
|
|
allocated, the remaining memory is zeroed.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xmalloc.c:32 -->
|
|
<div class="defun">
|
|
— Replacement: void* <b>xrealloc</b> (<var>void *ptr, size_t size</var>)<var><a name="index-xrealloc-202"></a></var><br>
|
|
<blockquote><p>Reallocate memory without fail. This routine functions like <code>realloc</code>,
|
|
but will behave the same as <code>xmalloc</code> if memory cannot be found.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xstrdup.c:7 -->
|
|
<div class="defun">
|
|
— Replacement: char* <b>xstrdup</b> (<var>const char *s</var>)<var><a name="index-xstrdup-203"></a></var><br>
|
|
<blockquote>
|
|
<p>Duplicates a character string without fail, using <code>xmalloc</code> to
|
|
obtain memory.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xstrerror.c:7 -->
|
|
<div class="defun">
|
|
— Replacement: char* <b>xstrerror</b> (<var>int errnum</var>)<var><a name="index-xstrerror-204"></a></var><br>
|
|
<blockquote>
|
|
<p>Behaves exactly like the standard <code>strerror</code> function, but
|
|
will never return a <code>NULL</code> pointer.
|
|
|
|
</blockquote></div>
|
|
|
|
<!-- xstrndup.c:23 -->
|
|
<div class="defun">
|
|
— Replacement: char* <b>xstrndup</b> (<var>const char *s, size_t n</var>)<var><a name="index-xstrndup-205"></a></var><br>
|
|
<blockquote>
|
|
<p>Returns a pointer to a copy of <var>s</var> with at most <var>n</var> characters
|
|
without fail, using <code>xmalloc</code> to obtain memory. The result is
|
|
always NUL terminated.
|
|
|
|
</blockquote></div>
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Licenses"></a>Next: <a rel="next" accesskey="n" href="#Index">Index</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="#Obstacks">Obstacks</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="appendix">Appendix A Licenses</h2>
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="#Library-Copying">Library Copying</a>: The GNU Library General Public License
|
|
<li><a accesskey="2" href="#BSD">BSD</a>: Regents of the University of California
|
|
|
|
</ul>
|
|
|
|
<!-- This takes care of Library Copying. It is the copying-lib.texi from the -->
|
|
<!-- GNU web site, with its @node line altered to make makeinfo shut up. -->
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Library-Copying"></a>Next: <a rel="next" accesskey="n" href="#BSD">BSD</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Licenses">Licenses</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="appendixsec">A.1 GNU LESSER GENERAL PUBLIC LICENSE</h3>
|
|
|
|
<p><a name="index-LGPL_002c-Lesser-General-Public-License-206"></a><div align="center">Version 2.1, February 1999</div>
|
|
|
|
<pre class="display"> Copyright © 1991, 1999 Free Software Foundation, Inc.
|
|
51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
[This is the first released version of the Lesser GPL. It also counts
|
|
as the successor of the GNU Library Public License, version 2, hence the
|
|
version number 2.1.]
|
|
</pre>
|
|
<h4 class="appendixsubsec">A.1.1 Preamble</h4>
|
|
|
|
<p>The licenses for most software are designed to take away your
|
|
freedom to share and change it. By contrast, the GNU General Public
|
|
Licenses are intended to guarantee your freedom to share and change
|
|
free software—to make sure the software is free for all its users.
|
|
|
|
<p>This license, the Lesser General Public License, applies to some
|
|
specially designated software—typically libraries—of the Free
|
|
Software Foundation and other authors who decide to use it. You can use
|
|
it too, but we suggest you first think carefully about whether this
|
|
license or the ordinary General Public License is the better strategy to
|
|
use in any particular case, based on the explanations below.
|
|
|
|
<p>When we speak of free software, we are referring to freedom of use,
|
|
not price. Our General Public Licenses are designed to make sure that
|
|
you have the freedom to distribute copies of free software (and charge
|
|
for this service if you wish); that you receive source code or can get
|
|
it if you want it; that you can change the software and use pieces of it
|
|
in new free programs; and that you are informed that you can do these
|
|
things.
|
|
|
|
<p>To protect your rights, we need to make restrictions that forbid
|
|
distributors to deny you these rights or to ask you to surrender these
|
|
rights. These restrictions translate to certain responsibilities for
|
|
you if you distribute copies of the library or if you modify it.
|
|
|
|
<p>For example, if you distribute copies of the library, whether gratis
|
|
or for a fee, you must give the recipients all the rights that we gave
|
|
you. You must make sure that they, too, receive or can get the source
|
|
code. If you link other code with the library, you must provide
|
|
complete object files to the recipients, so that they can relink them
|
|
with the library after making changes to the library and recompiling
|
|
it. And you must show them these terms so they know their rights.
|
|
|
|
<p>We protect your rights with a two-step method: (1) we copyright the
|
|
library, and (2) we offer you this license, which gives you legal
|
|
permission to copy, distribute and/or modify the library.
|
|
|
|
<p>To protect each distributor, we want to make it very clear that
|
|
there is no warranty for the free library. Also, if the library is
|
|
modified by someone else and passed on, the recipients should know
|
|
that what they have is not the original version, so that the original
|
|
author's reputation will not be affected by problems that might be
|
|
introduced by others.
|
|
|
|
<p>Finally, software patents pose a constant threat to the existence of
|
|
any free program. We wish to make sure that a company cannot
|
|
effectively restrict the users of a free program by obtaining a
|
|
restrictive license from a patent holder. Therefore, we insist that
|
|
any patent license obtained for a version of the library must be
|
|
consistent with the full freedom of use specified in this license.
|
|
|
|
<p>Most GNU software, including some libraries, is covered by the
|
|
ordinary GNU General Public License. This license, the GNU Lesser
|
|
General Public License, applies to certain designated libraries, and
|
|
is quite different from the ordinary General Public License. We use
|
|
this license for certain libraries in order to permit linking those
|
|
libraries into non-free programs.
|
|
|
|
<p>When a program is linked with a library, whether statically or using
|
|
a shared library, the combination of the two is legally speaking a
|
|
combined work, a derivative of the original library. The ordinary
|
|
General Public License therefore permits such linking only if the
|
|
entire combination fits its criteria of freedom. The Lesser General
|
|
Public License permits more lax criteria for linking other code with
|
|
the library.
|
|
|
|
<p>We call this license the <dfn>Lesser</dfn> General Public License because it
|
|
does <em>Less</em> to protect the user's freedom than the ordinary General
|
|
Public License. It also provides other free software developers Less
|
|
of an advantage over competing non-free programs. These disadvantages
|
|
are the reason we use the ordinary General Public License for many
|
|
libraries. However, the Lesser license provides advantages in certain
|
|
special circumstances.
|
|
|
|
<p>For example, on rare occasions, there may be a special need to
|
|
encourage the widest possible use of a certain library, so that it becomes
|
|
a de-facto standard. To achieve this, non-free programs must be
|
|
allowed to use the library. A more frequent case is that a free
|
|
library does the same job as widely used non-free libraries. In this
|
|
case, there is little to gain by limiting the free library to free
|
|
software only, so we use the Lesser General Public License.
|
|
|
|
<p>In other cases, permission to use a particular library in non-free
|
|
programs enables a greater number of people to use a large body of
|
|
free software. For example, permission to use the GNU C Library in
|
|
non-free programs enables many more people to use the whole GNU
|
|
operating system, as well as its variant, the GNU/Linux operating
|
|
system.
|
|
|
|
<p>Although the Lesser General Public License is Less protective of the
|
|
users' freedom, it does ensure that the user of a program that is
|
|
linked with the Library has the freedom and the wherewithal to run
|
|
that program using a modified version of the Library.
|
|
|
|
<p>The precise terms and conditions for copying, distribution and
|
|
modification follow. Pay close attention to the difference between a
|
|
“work based on the library” and a “work that uses the library”. The
|
|
former contains code derived from the library, whereas the latter must
|
|
be combined with the library in order to run.
|
|
|
|
<ol type=1 start=0>
|
|
<li>This License Agreement applies to any software library or other program
|
|
which contains a notice placed by the copyright holder or other
|
|
authorized party saying it may be distributed under the terms of this
|
|
Lesser General Public License (also called “this License”). Each
|
|
licensee is addressed as “you”.
|
|
|
|
<p>A “library” means a collection of software functions and/or data
|
|
prepared so as to be conveniently linked with application programs
|
|
(which use some of those functions and data) to form executables.
|
|
|
|
<p>The “Library”, below, refers to any such software library or work
|
|
which has been distributed under these terms. A “work based on the
|
|
Library” means either the Library or any derivative work under
|
|
copyright law: that is to say, a work containing the Library or a
|
|
portion of it, either verbatim or with modifications and/or translated
|
|
straightforwardly into another language. (Hereinafter, translation is
|
|
included without limitation in the term “modification”.)
|
|
|
|
<p>“Source code” for a work means the preferred form of the work for
|
|
making modifications to it. For a library, complete source code means
|
|
all the source code for all modules it contains, plus any associated
|
|
interface definition files, plus the scripts used to control compilation
|
|
and installation of the library.
|
|
|
|
<p>Activities other than copying, distribution and modification are not
|
|
covered by this License; they are outside its scope. The act of
|
|
running a program using the Library is not restricted, and output from
|
|
such a program is covered only if its contents constitute a work based
|
|
on the Library (independent of the use of the Library in a tool for
|
|
writing it). Whether that is true depends on what the Library does
|
|
and what the program that uses the Library does.
|
|
|
|
<li>You may copy and distribute verbatim copies of the Library's
|
|
complete source code as you receive it, in any medium, provided that
|
|
you conspicuously and appropriately publish on each copy an
|
|
appropriate copyright notice and disclaimer of warranty; keep intact
|
|
all the notices that refer to this License and to the absence of any
|
|
warranty; and distribute a copy of this License along with the
|
|
Library.
|
|
|
|
<p>You may charge a fee for the physical act of transferring a copy,
|
|
and you may at your option offer warranty protection in exchange for a
|
|
fee.
|
|
|
|
<li>You may modify your copy or copies of the Library or any portion
|
|
of it, thus forming a work based on the Library, and copy and
|
|
distribute such modifications or work under the terms of Section 1
|
|
above, provided that you also meet all of these conditions:
|
|
|
|
<ol type=a start=1>
|
|
<li>The modified work must itself be a software library.
|
|
|
|
<li>You must cause the files modified to carry prominent notices
|
|
stating that you changed the files and the date of any change.
|
|
|
|
<li>You must cause the whole of the work to be licensed at no
|
|
charge to all third parties under the terms of this License.
|
|
|
|
<li>If a facility in the modified Library refers to a function or a
|
|
table of data to be supplied by an application program that uses
|
|
the facility, other than as an argument passed when the facility
|
|
is invoked, then you must make a good faith effort to ensure that,
|
|
in the event an application does not supply such function or
|
|
table, the facility still operates, and performs whatever part of
|
|
its purpose remains meaningful.
|
|
|
|
<p>(For example, a function in a library to compute square roots has
|
|
a purpose that is entirely well-defined independent of the
|
|
application. Therefore, Subsection 2d requires that any
|
|
application-supplied function or table used by this function must
|
|
be optional: if the application does not supply it, the square
|
|
root function must still compute square roots.)
|
|
</ol>
|
|
|
|
<p>These requirements apply to the modified work as a whole. If
|
|
identifiable sections of that work are not derived from the Library,
|
|
and can be reasonably considered independent and separate works in
|
|
themselves, then this License, and its terms, do not apply to those
|
|
sections when you distribute them as separate works. But when you
|
|
distribute the same sections as part of a whole which is a work based
|
|
on the Library, the distribution of the whole must be on the terms of
|
|
this License, whose permissions for other licensees extend to the
|
|
entire whole, and thus to each and every part regardless of who wrote
|
|
it.
|
|
|
|
<p>Thus, it is not the intent of this section to claim rights or contest
|
|
your rights to work written entirely by you; rather, the intent is to
|
|
exercise the right to control the distribution of derivative or
|
|
collective works based on the Library.
|
|
|
|
<p>In addition, mere aggregation of another work not based on the Library
|
|
with the Library (or with a work based on the Library) on a volume of
|
|
a storage or distribution medium does not bring the other work under
|
|
the scope of this License.
|
|
|
|
<li>You may opt to apply the terms of the ordinary GNU General Public
|
|
License instead of this License to a given copy of the Library. To do
|
|
this, you must alter all the notices that refer to this License, so
|
|
that they refer to the ordinary GNU General Public License, version 2,
|
|
instead of to this License. (If a newer version than version 2 of the
|
|
ordinary GNU General Public License has appeared, then you can specify
|
|
that version instead if you wish.) Do not make any other change in
|
|
these notices.
|
|
|
|
<p>Once this change is made in a given copy, it is irreversible for
|
|
that copy, so the ordinary GNU General Public License applies to all
|
|
subsequent copies and derivative works made from that copy.
|
|
|
|
<p>This option is useful when you wish to copy part of the code of
|
|
the Library into a program that is not a library.
|
|
|
|
<li>You may copy and distribute the Library (or a portion or
|
|
derivative of it, under Section 2) in object code or executable form
|
|
under the terms of Sections 1 and 2 above provided that you accompany
|
|
it with the complete corresponding machine-readable source code, which
|
|
must be distributed under the terms of Sections 1 and 2 above on a
|
|
medium customarily used for software interchange.
|
|
|
|
<p>If distribution of object code is made by offering access to copy
|
|
from a designated place, then offering equivalent access to copy the
|
|
source code from the same place satisfies the requirement to
|
|
distribute the source code, even though third parties are not
|
|
compelled to copy the source along with the object code.
|
|
|
|
<li>A program that contains no derivative of any portion of the
|
|
Library, but is designed to work with the Library by being compiled or
|
|
linked with it, is called a “work that uses the Library”. Such a
|
|
work, in isolation, is not a derivative work of the Library, and
|
|
therefore falls outside the scope of this License.
|
|
|
|
<p>However, linking a “work that uses the Library” with the Library
|
|
creates an executable that is a derivative of the Library (because it
|
|
contains portions of the Library), rather than a “work that uses the
|
|
library”. The executable is therefore covered by this License.
|
|
Section 6 states terms for distribution of such executables.
|
|
|
|
<p>When a “work that uses the Library” uses material from a header file
|
|
that is part of the Library, the object code for the work may be a
|
|
derivative work of the Library even though the source code is not.
|
|
Whether this is true is especially significant if the work can be
|
|
linked without the Library, or if the work is itself a library. The
|
|
threshold for this to be true is not precisely defined by law.
|
|
|
|
<p>If such an object file uses only numerical parameters, data
|
|
structure layouts and accessors, and small macros and small inline
|
|
functions (ten lines or less in length), then the use of the object
|
|
file is unrestricted, regardless of whether it is legally a derivative
|
|
work. (Executables containing this object code plus portions of the
|
|
Library will still fall under Section 6.)
|
|
|
|
<p>Otherwise, if the work is a derivative of the Library, you may
|
|
distribute the object code for the work under the terms of Section 6.
|
|
Any executables containing that work also fall under Section 6,
|
|
whether or not they are linked directly with the Library itself.
|
|
|
|
<li>As an exception to the Sections above, you may also combine or
|
|
link a “work that uses the Library” with the Library to produce a
|
|
work containing portions of the Library, and distribute that work
|
|
under terms of your choice, provided that the terms permit
|
|
modification of the work for the customer's own use and reverse
|
|
engineering for debugging such modifications.
|
|
|
|
<p>You must give prominent notice with each copy of the work that the
|
|
Library is used in it and that the Library and its use are covered by
|
|
this License. You must supply a copy of this License. If the work
|
|
during execution displays copyright notices, you must include the
|
|
copyright notice for the Library among them, as well as a reference
|
|
directing the user to the copy of this License. Also, you must do one
|
|
of these things:
|
|
|
|
<ol type=a start=1>
|
|
<li>Accompany the work with the complete corresponding
|
|
machine-readable source code for the Library including whatever
|
|
changes were used in the work (which must be distributed under
|
|
Sections 1 and 2 above); and, if the work is an executable linked
|
|
with the Library, with the complete machine-readable “work that
|
|
uses the Library”, as object code and/or source code, so that the
|
|
user can modify the Library and then relink to produce a modified
|
|
executable containing the modified Library. (It is understood
|
|
that the user who changes the contents of definitions files in the
|
|
Library will not necessarily be able to recompile the application
|
|
to use the modified definitions.)
|
|
|
|
<li>Use a suitable shared library mechanism for linking with the Library. A
|
|
suitable mechanism is one that (1) uses at run time a copy of the
|
|
library already present on the user's computer system, rather than
|
|
copying library functions into the executable, and (2) will operate
|
|
properly with a modified version of the library, if the user installs
|
|
one, as long as the modified version is interface-compatible with the
|
|
version that the work was made with.
|
|
|
|
<li>Accompany the work with a written offer, valid for at
|
|
least three years, to give the same user the materials
|
|
specified in Subsection 6a, above, for a charge no more
|
|
than the cost of performing this distribution.
|
|
|
|
<li>If distribution of the work is made by offering access to copy
|
|
from a designated place, offer equivalent access to copy the above
|
|
specified materials from the same place.
|
|
|
|
<li>Verify that the user has already received a copy of these
|
|
materials or that you have already sent this user a copy.
|
|
</ol>
|
|
|
|
<p>For an executable, the required form of the “work that uses the
|
|
Library” must include any data and utility programs needed for
|
|
reproducing the executable from it. However, as a special exception,
|
|
the materials to be distributed need not include anything that is
|
|
normally distributed (in either source or binary form) with the major
|
|
components (compiler, kernel, and so on) of the operating system on
|
|
which the executable runs, unless that component itself accompanies the
|
|
executable.
|
|
|
|
<p>It may happen that this requirement contradicts the license
|
|
restrictions of other proprietary libraries that do not normally
|
|
accompany the operating system. Such a contradiction means you cannot
|
|
use both them and the Library together in an executable that you
|
|
distribute.
|
|
|
|
<li>You may place library facilities that are a work based on the
|
|
Library side-by-side in a single library together with other library
|
|
facilities not covered by this License, and distribute such a combined
|
|
library, provided that the separate distribution of the work based on
|
|
the Library and of the other library facilities is otherwise
|
|
permitted, and provided that you do these two things:
|
|
|
|
<ol type=a start=1>
|
|
<li>Accompany the combined library with a copy of the same work
|
|
based on the Library, uncombined with any other library
|
|
facilities. This must be distributed under the terms of the
|
|
Sections above.
|
|
|
|
<li>Give prominent notice with the combined library of the fact
|
|
that part of it is a work based on the Library, and explaining
|
|
where to find the accompanying uncombined form of the same work.
|
|
</ol>
|
|
|
|
<li>You may not copy, modify, sublicense, link with, or distribute
|
|
the Library except as expressly provided under this License. Any
|
|
attempt otherwise to copy, modify, sublicense, link with, or
|
|
distribute the Library is void, and will automatically terminate your
|
|
rights under this License. However, parties who have received copies,
|
|
or rights, from you under this License will not have their licenses
|
|
terminated so long as such parties remain in full compliance.
|
|
|
|
<li>You are not required to accept this License, since you have not
|
|
signed it. However, nothing else grants you permission to modify or
|
|
distribute the Library or its derivative works. These actions are
|
|
prohibited by law if you do not accept this License. Therefore, by
|
|
modifying or distributing the Library (or any work based on the
|
|
Library), you indicate your acceptance of this License to do so, and
|
|
all its terms and conditions for copying, distributing or modifying
|
|
the Library or works based on it.
|
|
|
|
<li>Each time you redistribute the Library (or any work based on the
|
|
Library), the recipient automatically receives a license from the
|
|
original licensor to copy, distribute, link with or modify the Library
|
|
subject to these terms and conditions. You may not impose any further
|
|
restrictions on the recipients' exercise of the rights granted herein.
|
|
You are not responsible for enforcing compliance by third parties with
|
|
this License.
|
|
|
|
<li>If, as a consequence of a court judgment or allegation of patent
|
|
infringement or for any other reason (not limited to patent issues),
|
|
conditions are imposed on you (whether by court order, agreement or
|
|
otherwise) that contradict the conditions of this License, they do not
|
|
excuse you from the conditions of this License. If you cannot
|
|
distribute so as to satisfy simultaneously your obligations under this
|
|
License and any other pertinent obligations, then as a consequence you
|
|
may not distribute the Library at all. For example, if a patent
|
|
license would not permit royalty-free redistribution of the Library by
|
|
all those who receive copies directly or indirectly through you, then
|
|
the only way you could satisfy both it and this License would be to
|
|
refrain entirely from distribution of the Library.
|
|
|
|
<p>If any portion of this section is held invalid or unenforceable under any
|
|
particular circumstance, the balance of the section is intended to apply,
|
|
and the section as a whole is intended to apply in other circumstances.
|
|
|
|
<p>It is not the purpose of this section to induce you to infringe any
|
|
patents or other property right claims or to contest validity of any
|
|
such claims; this section has the sole purpose of protecting the
|
|
integrity of the free software distribution system which is
|
|
implemented by public license practices. Many people have made
|
|
generous contributions to the wide range of software distributed
|
|
through that system in reliance on consistent application of that
|
|
system; it is up to the author/donor to decide if he or she is willing
|
|
to distribute software through any other system and a licensee cannot
|
|
impose that choice.
|
|
|
|
<p>This section is intended to make thoroughly clear what is believed to
|
|
be a consequence of the rest of this License.
|
|
|
|
<li>If the distribution and/or use of the Library is restricted in
|
|
certain countries either by patents or by copyrighted interfaces, the
|
|
original copyright holder who places the Library under this License may add
|
|
an explicit geographical distribution limitation excluding those countries,
|
|
so that distribution is permitted only in or among countries not thus
|
|
excluded. In such case, this License incorporates the limitation as if
|
|
written in the body of this License.
|
|
|
|
<li>The Free Software Foundation may publish revised and/or new
|
|
versions of the Lesser General Public License from time to time.
|
|
Such new versions will be similar in spirit to the present version,
|
|
but may differ in detail to address new problems or concerns.
|
|
|
|
<p>Each version is given a distinguishing version number. If the Library
|
|
specifies a version number of this License which applies to it and
|
|
“any later version”, you have the option of following the terms and
|
|
conditions either of that version or of any later version published by
|
|
the Free Software Foundation. If the Library does not specify a
|
|
license version number, you may choose any version ever published by
|
|
the Free Software Foundation.
|
|
|
|
<li>If you wish to incorporate parts of the Library into other free
|
|
programs whose distribution conditions are incompatible with these,
|
|
write to the author to ask for permission. For software which is
|
|
copyrighted by the Free Software Foundation, write to the Free
|
|
Software Foundation; we sometimes make exceptions for this. Our
|
|
decision will be guided by the two goals of preserving the free status
|
|
of all derivatives of our free software and of promoting the sharing
|
|
and reuse of software generally.
|
|
|
|
<li>BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
|
|
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
|
|
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
|
|
OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY
|
|
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
|
|
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
|
|
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
|
|
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
|
|
|
<li>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
|
|
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
|
|
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
|
|
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
|
|
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
|
|
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
|
|
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
|
|
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
|
|
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
|
|
DAMAGES.
|
|
</ol>
|
|
|
|
<h4 class="appendixsubsec">A.1.2 How to Apply These Terms to Your New Libraries</h4>
|
|
|
|
<p>If you develop a new library, and you want it to be of the greatest
|
|
possible use to the public, we recommend making it free software that
|
|
everyone can redistribute and change. You can do so by permitting
|
|
redistribution under these terms (or, alternatively, under the terms of the
|
|
ordinary General Public License).
|
|
|
|
<p>To apply these terms, attach the following notices to the library. It is
|
|
safest to attach them to the start of each source file to most effectively
|
|
convey the exclusion of warranty; and each file should have at least the
|
|
“copyright” line and a pointer to where the full notice is found.
|
|
|
|
<pre class="smallexample"> <var>one line to give the library's name and an idea of what it does.</var>
|
|
Copyright (C) <var>year</var> <var>name of author</var>
|
|
|
|
This library is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or (at
|
|
your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the Free Software
|
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
|
|
USA.
|
|
</pre>
|
|
<p>Also add information on how to contact you by electronic and paper mail.
|
|
|
|
<p>You should also get your employer (if you work as a programmer) or your
|
|
school, if any, to sign a “copyright disclaimer” for the library, if
|
|
necessary. Here is a sample; alter the names:
|
|
|
|
<pre class="smallexample"> Yoyodyne, Inc., hereby disclaims all copyright interest in the library
|
|
`Frob' (a library for tweaking knobs) written by James Random Hacker.
|
|
|
|
<var>signature of Ty Coon</var>, 1 April 1990
|
|
Ty Coon, President of Vice
|
|
</pre>
|
|
<p>That's all there is to it!
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="BSD"></a>Previous: <a rel="previous" accesskey="p" href="#Library-Copying">Library Copying</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Licenses">Licenses</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h3 class="appendixsec">A.2 BSD</h3>
|
|
|
|
<p>Copyright © 1990 Regents of the University of California.
|
|
All rights reserved.
|
|
|
|
<p>Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
<ol type=1 start=1>
|
|
|
|
<li>Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
<li>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.
|
|
|
|
<li>[rescinded 22 July 1999]
|
|
|
|
<li>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.
|
|
|
|
</ol>
|
|
|
|
<p>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.
|
|
|
|
<div class="node">
|
|
<p><hr>
|
|
<a name="Index"></a>Previous: <a rel="previous" accesskey="p" href="#Licenses">Licenses</a>,
|
|
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
|
|
<br>
|
|
</div>
|
|
|
|
<h2 class="unnumbered">Index</h2>
|
|
|
|
<ul class="index-cp" compact>
|
|
<li><a href="#index-alignment-_0028in-obstacks_0029-50">alignment (in obstacks)</a>: <a href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a></li>
|
|
<li><a href="#index-alloca-59"><code>alloca</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-allocation-_0028obstacks_0029-21">allocation (obstacks)</a>: <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a></li>
|
|
<li><a href="#index-asprintf-60"><code>asprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-atexit-61"><code>atexit</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-basename-62"><code>basename</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-bcmp-63"><code>bcmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-bcopy-64"><code>bcopy</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-bsearch-65"><code>bsearch</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-buildargv-66"><code>buildargv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-bzero-67"><code>bzero</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-calloc-68"><code>calloc</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-changing-the-size-of-a-block-_0028obstacks_0029-29">changing the size of a block (obstacks)</a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-choose_005ftemp_005fbase-69"><code>choose_temp_base</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-choose_005ftmpdir-70"><code>choose_tmpdir</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-chunks-53">chunks</a>: <a href="#Obstack-Chunks">Obstack Chunks</a></li>
|
|
<li><a href="#index-clock-71"><code>clock</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-concat-72"><code>concat</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-dupargv-73"><code>dupargv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-efficiency-and-obstacks-39">efficiency and obstacks</a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-efficiency-of-chunks-52">efficiency of chunks</a>: <a href="#Obstack-Chunks">Obstack Chunks</a></li>
|
|
<li><a href="#index-errno_005fmax-74"><code>errno_max</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-error-reporting-11">error reporting</a>: <a href="#Error-Reporting">Error Reporting</a></li>
|
|
<li><a href="#index-exit-handlers-10">exit handlers</a>: <a href="#Exit-Handlers">Exit Handlers</a></li>
|
|
<li><a href="#index-expandargv-75"><code>expandargv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-extensions-12">extensions</a>: <a href="#Extensions">Extensions</a></li>
|
|
<li><a href="#index-fdmatch-76"><code>fdmatch</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-fdopen_005funlocked-77"><code>fdopen_unlocked</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ffs-78"><code>ffs</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-filename_005fcmp-79"><code>filename_cmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-fnmatch-80"><code>fnmatch</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-fopen_005funlocked-81"><code>fopen_unlocked</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-freeargv-82"><code>freeargv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-freeing-_0028obstacks_0029-25">freeing (obstacks)</a>: <a href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a></li>
|
|
<li><a href="#index-freopen_005funlocked-83"><code>freopen_unlocked</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-functions_002c-extension-13">functions, extension</a>: <a href="#Extensions">Extensions</a></li>
|
|
<li><a href="#index-functions_002c-missing-6">functions, missing</a>: <a href="#Supplemental-Functions">Supplemental Functions</a></li>
|
|
<li><a href="#index-functions_002c-replacement-8">functions, replacement</a>: <a href="#Replacement-Functions">Replacement Functions</a></li>
|
|
<li><a href="#index-functions_002c-supplemental-5">functions, supplemental</a>: <a href="#Supplemental-Functions">Supplemental Functions</a></li>
|
|
<li><a href="#index-get_005frun_005ftime-84"><code>get_run_time</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-getcwd-85"><code>getcwd</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-getpagesize-86"><code>getpagesize</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-getpwd-87"><code>getpwd</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-gettimeofday-88"><code>gettimeofday</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-growing-objects-_0028in-obstacks_0029-28">growing objects (in obstacks)</a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-hex_005finit-89"><code>hex_init</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-hex_005fp-90"><code>hex_p</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-hex_005fvalue-91"><code>hex_value</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-HOST_005fCHARSET-55"><code>HOST_CHARSET</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-HOST_005fCHARSET_005fASCII-57"><code>HOST_CHARSET_ASCII</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-HOST_005fCHARSET_005fEBCDIC-58"><code>HOST_CHARSET_EBCDIC</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-HOST_005fCHARSET_005fUNKNOWN-56"><code>HOST_CHARSET_UNKNOWN</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-how-to-use-3">how to use</a>: <a href="#Using">Using</a></li>
|
|
<li><a href="#index-index-92"><code>index</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-initstate-152"><code>initstate</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-insque-93"><code>insque</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-IS_005fISOBASIC-112"><code>IS_ISOBASIC</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-IS_005fNVSPACE-110"><code>IS_NVSPACE</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-IS_005fSPACE_005fOR_005fNUL-111"><code>IS_SPACE_OR_NUL</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-IS_005fVSPACE-109"><code>IS_VSPACE</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISALNUM-96"><code>ISALNUM</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISALPHA-95"><code>ISALPHA</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISBLANK-97"><code>ISBLANK</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISCNTRL-98"><code>ISCNTRL</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISDIGIT-99"><code>ISDIGIT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISGRAPH-100"><code>ISGRAPH</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISIDNUM-107"><code>ISIDNUM</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISIDST-108"><code>ISIDST</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISLOWER-101"><code>ISLOWER</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISPRINT-102"><code>ISPRINT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISPUNCT-103"><code>ISPUNCT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISSPACE-104"><code>ISSPACE</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISUPPER-105"><code>ISUPPER</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-ISXDIGIT-106"><code>ISXDIGIT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-lbasename-113"><code>lbasename</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-LGPL_002c-Lesser-General-Public-License-206">LGPL, Lesser General Public License</a>: <a href="#Library-Copying">Library Copying</a></li>
|
|
<li><a href="#index-libiberty-usage-2">libiberty usage</a>: <a href="#Using">Using</a></li>
|
|
<li><a href="#index-lrealpath-114"><code>lrealpath</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-macros-27">macros</a>: <a href="#Obstack-Functions">Obstack Functions</a></li>
|
|
<li><a href="#index-make_005frelative_005fprefix-115"><code>make_relative_prefix</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-make_005ftemp_005ffile-116"><code>make_temp_file</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memchr-117"><code>memchr</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memcmp-118"><code>memcmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memcpy-119"><code>memcpy</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memmove-120"><code>memmove</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memory-allocation-9">memory allocation</a>: <a href="#Memory-Allocation">Memory Allocation</a></li>
|
|
<li><a href="#index-mempcpy-121"><code>mempcpy</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-memset-122"><code>memset</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-mkstemps-123"><code>mkstemps</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-obstack-status-45">obstack status</a>: <a href="#Status-of-an-Obstack">Status of an Obstack</a></li>
|
|
<li><a href="#index-obstack_002eh-15"><code>obstack.h</code></a>: <a href="#Creating-Obstacks">Creating Obstacks</a></li>
|
|
<li><a href="#index-obstack_005f1grow-33"><code>obstack_1grow</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005f1grow_005ffast-41"><code>obstack_1grow_fast</code></a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-obstack_005falignment_005fmask-51"><code>obstack_alignment_mask</code></a>: <a href="#Obstacks-Data-Alignment">Obstacks Data Alignment</a></li>
|
|
<li><a href="#index-obstack_005falloc-22"><code>obstack_alloc</code></a>: <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a></li>
|
|
<li><a href="#index-obstack_005falloc_005ffailed_005fhandler-20"><code>obstack_alloc_failed_handler</code></a>: <a href="#Preparing-for-Obstacks">Preparing for Obstacks</a></li>
|
|
<li><a href="#index-obstack_005fbase-47"><code>obstack_base</code></a>: <a href="#Status-of-an-Obstack">Status of an Obstack</a></li>
|
|
<li><a href="#index-obstack_005fblank-30"><code>obstack_blank</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005fblank_005ffast-44"><code>obstack_blank_fast</code></a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-obstack_005fchunk_005falloc-17"><code>obstack_chunk_alloc</code></a>: <a href="#Preparing-for-Obstacks">Preparing for Obstacks</a></li>
|
|
<li><a href="#index-obstack_005fchunk_005ffree-18"><code>obstack_chunk_free</code></a>: <a href="#Preparing-for-Obstacks">Preparing for Obstacks</a></li>
|
|
<li><a href="#index-obstack_005fchunk_005fsize-54"><code>obstack_chunk_size</code></a>: <a href="#Obstack-Chunks">Obstack Chunks</a></li>
|
|
<li><a href="#index-obstack_005fcopy-23"><code>obstack_copy</code></a>: <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a></li>
|
|
<li><a href="#index-obstack_005fcopy0-24"><code>obstack_copy0</code></a>: <a href="#Allocation-in-an-Obstack">Allocation in an Obstack</a></li>
|
|
<li><a href="#index-obstack_005ffinish-36"><code>obstack_finish</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005ffree-26"><code>obstack_free</code></a>: <a href="#Freeing-Obstack-Objects">Freeing Obstack Objects</a></li>
|
|
<li><a href="#index-obstack_005fgrow-31"><code>obstack_grow</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005fgrow0-32"><code>obstack_grow0</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005finit-19"><code>obstack_init</code></a>: <a href="#Preparing-for-Obstacks">Preparing for Obstacks</a></li>
|
|
<li><a href="#index-obstack_005fint_005fgrow-35"><code>obstack_int_grow</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005fint_005fgrow_005ffast-43"><code>obstack_int_grow_fast</code></a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-obstack_005fnext_005ffree-48"><code>obstack_next_free</code></a>: <a href="#Status-of-an-Obstack">Status of an Obstack</a></li>
|
|
<li><a href="#index-obstack_005fobject_005fsize-37"><code>obstack_object_size</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005fobject_005fsize-49"><code>obstack_object_size</code></a>: <a href="#Status-of-an-Obstack">Status of an Obstack</a></li>
|
|
<li><a href="#index-obstack_005fptr_005fgrow-34"><code>obstack_ptr_grow</code></a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-obstack_005fptr_005fgrow_005ffast-42"><code>obstack_ptr_grow_fast</code></a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-obstack_005froom-40"><code>obstack_room</code></a>: <a href="#Extra-Fast-Growing">Extra Fast Growing</a></li>
|
|
<li><a href="#index-obstacks-14">obstacks</a>: <a href="#Obstacks">Obstacks</a></li>
|
|
<li><a href="#index-PEX_005fBINARY_005fERROR-143"><code>PEX_BINARY_ERROR</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fBINARY_005fINPUT-141"><code>PEX_BINARY_INPUT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fBINARY_005fOUTPUT-142"><code>PEX_BINARY_OUTPUT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005ffree-124"><code>pex_free</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005fget_005fstatus-125"><code>pex_get_status</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005fget_005ftimes-126"><code>pex_get_times</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005finit-127"><code>pex_init</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005finput_005ffile-131"><code>pex_input_file</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005finput_005fpipe-132"><code>pex_input_pipe</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fLAST-137"><code>PEX_LAST</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005fone-133"><code>pex_one</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005fread_005ferr-134"><code>pex_read_err</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005fread_005foutput-135"><code>pex_read_output</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fRECORD_005fTIMES-128"><code>PEX_RECORD_TIMES</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005frun-136"><code>pex_run</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pex_005frun_005fin_005fenvironment-145"><code>pex_run_in_environment</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fSAVE_005fTEMPS-130"><code>PEX_SAVE_TEMPS</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fSEARCH-138"><code>PEX_SEARCH</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fSTDERR_005fTO_005fPIPE-144"><code>PEX_STDERR_TO_PIPE</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fSTDERR_005fTO_005fSTDOUT-140"><code>PEX_STDERR_TO_STDOUT</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fSUFFIX-139"><code>PEX_SUFFIX</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-PEX_005fUSE_005fPIPES-129"><code>PEX_USE_PIPES</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pexecute-146"><code>pexecute</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-psignal-147"><code>psignal</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-putenv-148"><code>putenv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-pwait-149"><code>pwait</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-random-150"><code>random</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-reconcat-154"><code>reconcat</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-remque-94"><code>remque</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-rename-155"><code>rename</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-replacement-functions-7">replacement functions</a>: <a href="#Replacement-Functions">Replacement Functions</a></li>
|
|
<li><a href="#index-rindex-156"><code>rindex</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-setenv-157"><code>setenv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-setstate-153"><code>setstate</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-shrinking-objects-38">shrinking objects</a>: <a href="#Growing-Objects">Growing Objects</a></li>
|
|
<li><a href="#index-signo_005fmax-159"><code>signo_max</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-sigsetmask-160"><code>sigsetmask</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-snprintf-161"><code>snprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-spaces-162"><code>spaces</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-srandom-151"><code>srandom</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-status-of-obstack-46">status of obstack</a>: <a href="#Status-of-an-Obstack">Status of an Obstack</a></li>
|
|
<li><a href="#index-stpcpy-163"><code>stpcpy</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-stpncpy-164"><code>stpncpy</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strcasecmp-165"><code>strcasecmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strchr-166"><code>strchr</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strdup-167"><code>strdup</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strerrno-168"><code>strerrno</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strerror-169"><code>strerror</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strncasecmp-170"><code>strncasecmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strncmp-171"><code>strncmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strndup-172"><code>strndup</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strrchr-173"><code>strrchr</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strsignal-174"><code>strsignal</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strsigno-175"><code>strsigno</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strstr-176"><code>strstr</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strtod-177"><code>strtod</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strtoerrno-178"><code>strtoerrno</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strtol-179"><code>strtol</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strtosigno-181"><code>strtosigno</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strtoul-180"><code>strtoul</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-strverscmp-182"><code>strverscmp</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-supplemental-functions-4">supplemental functions</a>: <a href="#Supplemental-Functions">Supplemental Functions</a></li>
|
|
<li><a href="#index-tmpnam-183"><code>tmpnam</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-unlink_005fif_005fordinary-184"><code>unlink_if_ordinary</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-unlock_005fstd_005fstreams-185"><code>unlock_std_streams</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-unlock_005fstream-186"><code>unlock_stream</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-unsetenv-158"><code>unsetenv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-using-libiberty-1">using libiberty</a>: <a href="#Using">Using</a></li>
|
|
<li><a href="#index-vasprintf-187"><code>vasprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-vfork-188"><code>vfork</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-vfprintf-190"><code>vfprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-vprintf-189"><code>vprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-vsnprintf-192"><code>vsnprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-vsprintf-191"><code>vsprintf</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-waitpid-193"><code>waitpid</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-writeargv-194"><code>writeargv</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xatexit-195"><code>xatexit</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xcalloc-196"><code>xcalloc</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xexit-197"><code>xexit</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xmalloc-198"><code>xmalloc</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xmalloc_005ffailed-199"><code>xmalloc_failed</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xmalloc_005fset_005fprogram_005fname-200"><code>xmalloc_set_program_name</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xmemdup-201"><code>xmemdup</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xrealloc-202"><code>xrealloc</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xstrdup-203"><code>xstrdup</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xstrerror-204"><code>xstrerror</code></a>: <a href="#Functions">Functions</a></li>
|
|
<li><a href="#index-xstrndup-205"><code>xstrndup</code></a>: <a href="#Functions">Functions</a></li>
|
|
</ul></body></html>
|
|
|