library_3.html

Linux程序员的工作手册

<DD>This is the number of chunks which are free -- that is, that have been
allocated by the operating system to your program, but which are not
now being used.
<P>
<DT><CODE>size_t bytes_free</CODE>
<DD>This is the number of bytes which are free.
</DL>
<P>
<A NAME="IDX169"></A>
<U>Function:</U> struct mstats <B>mstats</B> <I>(void)</I><P>
This function returns information about the current dynamic memory usage
in a structure of type <CODE>struct mstats</CODE>.
<P>
<H3><A NAME="SEC32" HREF="library_toc.html#SEC32" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC32">Summary of <CODE>malloc</CODE>-Related Functions</A></H3>
<P>
Here is a summary of the functions that work with <CODE>malloc</CODE>:
<P>
<DL COMPACT>
<DT><CODE>void *malloc (size_t <VAR>size</VAR>)</CODE>
<DD>Allocate a block of <VAR>size</VAR> bytes.  See section <A HREF="library_3.html#SEC22" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC22">Basic Storage Allocation</A>.
<P>
<DT><CODE>void free (void *<VAR>addr</VAR>)</CODE>
<DD>Free a block previously allocated by <CODE>malloc</CODE>.  See section <A HREF="library_3.html#SEC24" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC24">Freeing Memory Allocated with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>void *realloc (void *<VAR>addr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Make a block previously allocated by <CODE>malloc</CODE> larger or smaller,
possibly by copying it to a new location.  See section <A HREF="library_3.html#SEC25" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC25">Changing the Size of a Block</A>.
<P>
<DT><CODE>void *calloc (size_t <VAR>count</VAR>, size_t <VAR>eltsize</VAR>)</CODE>
<DD>Allocate a block of <VAR>count</VAR> * <VAR>eltsize</VAR> bytes using
<CODE>malloc</CODE>, and set its contents to zero.  See section <A HREF="library_3.html#SEC26" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC26">Allocating Cleared Space</A>.
<P>
<DT><CODE>void *valloc (size_t <VAR>size</VAR>)</CODE>
<DD>Allocate a block <VAR>size</VAR> bytes, starting on a page boundary.
See section <A HREF="library_3.html#SEC28" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>void *memalign (size_t <VAR>size</VAR>, size_t <VAR>boundary</VAR>)</CODE>
<DD>Allocate a block <VAR>size</VAR> bytes, starting on an address that is a
multiple of <VAR>boundary</VAR>.  See section <A HREF="library_3.html#SEC28" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>void mcheck (void (*<VAR>abortfn</VAR>) (void))</CODE>
<DD>Tell <CODE>malloc</CODE> to perform occasional consistency checks on
dynamically allocated memory, and to call <VAR>abortfn</VAR> when an
inconsistency is found.  See section <A HREF="library_3.html#SEC29" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC29">Heap Consistency Checking</A>.
<P>
<DT><CODE>void *(*__malloc_hook) (size_t <VAR>size</VAR>)</CODE>
<DD>A pointer to a function that <CODE>malloc</CODE> uses whenever it is called.
<P>
<DT><CODE>void *(*__realloc_hook) (void *<VAR>ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>A pointer to a function that <CODE>realloc</CODE> uses whenever it is called.
<P>
<DT><CODE>void (*__free_hook) (void *<VAR>ptr</VAR>)</CODE>
<DD>A pointer to a function that <CODE>free</CODE> uses whenever it is called.
<P>
<DT><CODE>void struct mstats mstats (void)</CODE>
<DD>Read information about the current dynamic memory usage.
See section <A HREF="library_3.html#SEC31" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC31">Statistics for Storage Allocation with <CODE>malloc</CODE></A>.
</DL>
<P>
<A NAME="IDX170"></A>
<H2><A NAME="SEC33" HREF="library_toc.html#SEC33" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC33">Obstacks</A></H2>
<P>
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.
<P>
<H3><A NAME="SEC34" HREF="library_toc.html#SEC34" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC34">Creating Obstacks</A></H3>
<P>
The utilities for manipulating obstacks are declared in the header
file <TT>`obstack.h'</TT>.
<A NAME="IDX171"></A>
<P>
<A NAME="IDX172"></A>
<U>Data Type:</U> <B>struct obstack</B><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>
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.
<P>
<H3><A NAME="SEC35" HREF="library_toc.html#SEC35" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC35">Preparing for Using Obstacks</A></H3>
<P>
Each source file in which you plan to use the obstack functions
must include the header file <TT>`obstack.h'</TT>, like this:
<P>
<PRE>
#include &#60;obstack.h&#62;
</PRE>
<A NAME="IDX173"></A>
<A NAME="IDX174"></A>
<P>
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.
<P>
Usually these are defined to use <CODE>malloc</CODE> via the intermediary
<CODE>xmalloc</CODE> (see section <A HREF="library_3.html#SEC21" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC21">Unconstrained Allocation</A>).  This is done with
the following pair of macro definitions:
<P>
<PRE>
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
</PRE>
<P>
Though the storage 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 section <A HREF="library_3.html#SEC43" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC43">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>.
<P>
<A NAME="IDX175"></A>
<U>Function:</U> void <B>obstack_init</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
Initialize obstack <VAR>obstack_ptr</VAR> for allocation of objects.
<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:
<P>
<PRE>
struct obstack myobstack;
...
obstack_init (&#38;myobstack);
</PRE>
<P>
Second, an obstack that is itself dynamically allocated:
<P>
<PRE>
struct obstack *myobstack_ptr
  = (struct obstack *) xmalloc (sizeof (struct obstack));

obstack_init (myobstack_ptr);
</PRE>
<P>
<A NAME="IDX176"></A>
<H3><A NAME="SEC36" HREF="library_toc.html#SEC36" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC36">Allocation in an Obstack</A></H3>
<P>
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>.
<P>
<A NAME="IDX177"></A>
<U>Function:</U> void * <B>obstack_alloc</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</I><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>
For example, here is a function that allocates a copy of a string <VAR>str</VAR>
in a specific obstack, which is the variable <CODE>string_obstack</CODE>:
<P>
<PRE>
struct obstack string_obstack;

char *
copystring (char *string)
{
  char *s = (char *) obstack_alloc (&#38;string_obstack,
                                    strlen (string) + 1);
  memcpy (s, string, strlen (string));
  return s;
}
</PRE>
<P>
To allocate a block with specified contents, use the function
<CODE>obstack_copy</CODE>, declared like this:
<P>
<A NAME="IDX178"></A>
<U>Function:</U> void * <B>obstack_copy</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</I><P>
This allocates a block and initializes it by copying <VAR>size</VAR>
bytes of data starting at <VAR>address</VAR>.
<P>
<A NAME="IDX179"></A>
<U>Function:</U> void * <B>obstack_copy0</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</I><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>
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:
<P>
<PRE>
char *
obstack_savestring (char *addr, size_t size)
{
  return obstack_copy0 (&#38;myobstack, addr, size);
}
</PRE>
<P>
Contrast this with the previous example of <CODE>savestring</CODE> using
<CODE>malloc</CODE> (see section <A HREF="library_3.html#SEC22" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC22">Basic Storage Allocation</A>).
<P>
<A NAME="IDX180"></A>
<H3><A NAME="SEC37" HREF="library_toc.html#SEC37" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC37">Freeing Objects in an Obstack</A></H3>
<P>
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.
<P>
<A NAME="IDX181"></A>
<U>Function:</U> void <B>obstack_free</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>object</VAR>)</I><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>
Note that if <VAR>object</VAR> is a null pointer, the result is an
uninitialized obstack.  To free all storage 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:
<P>
<PRE>
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 section <A HREF="library_3.html#SEC35" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC35">Preparing for Using Obstacks</A>).  Then other
obstacks, or non-obstack allocation, can reuse the space of the chunk.
<P>
<A NAME="IDX182"></A>
<H3><A NAME="SEC38" HREF="library_toc.html#SEC38" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC38">Obstack Functions and Macros</A></H3>
<P>
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 ANSI C and traditional C, but there are
precautions you must take if you plan to use compilers other than GNU C.
<P>