library_3.html

linux_c函数,linux下编程必备的

<DT><CODE>size_t bytes_total</CODE>
<DD>This is the total size of memory managed by malloc, in bytes.
<P>
<DT><CODE>size_t chunks_used</CODE>
<DD>This is the number of chunks in use.  (The storage allocator internally
gets chunks of memory from the operating system, and then carves them up
to satisfy individual <CODE>malloc</CODE> requests; see section <A HREF="library_3.html#SEC27" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC27">Efficiency Considerations for <CODE>malloc</CODE></A>.)
<P>
<DT><CODE>size_t bytes_used</CODE>
<DD>This is the number of bytes in use.
<P>
<DT><CODE>size_t chunks_free</CODE>
<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: