GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TYPED_MEM (3)

NAME

typed_mem - heap memory accounting system

CONTENTS

Library
Synopsis
Description
See Also
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In stdio.h
.In stdarg.h
.In pdel/structs/structs.h
.In pdel/structs/type/array.h
.In pdel/util/typed_mem.h void * MALLOC const char *mtype size_t size void * CALLOC const char *mtype size_t number size_t size void * REALLOC const char *mtype void *mem size_t size void * REALLOCF const char *mtype void *mem size_t size void FREE const char *mtype void *mem char * STRDUP const char *mtype const char *str int ASPRINTF const char *mtype char **ret const char *format ... int VASPRINTF const char *mtype char **ret const char *format va_list ap int typed_mem_enable void char * typed_mem_type const void *mem char *typebuf int typed_mem_usage struct typed_mem_stats *stats void typed_mem_dump FILE *fp
.Vt extern const struct structs_type typed_mem_stats_type ;

DESCRIPTION

The typed_mem library provides accounting and sanity checking for heap-allocated memory, configurable at run time.

If you’re reading this man page because you need to pass a variable named mtype to a function where a "typed_mem(3) memory type" is required, but you don’t want to use or deal with typed memory in any way, then just pass NULL for mtype and stop reading here. Otherwise, read on...

In this system, the user code uses the MALLOC, CALLOC, REALLOC, REALLOCF, FREE, STRDUP, ASPRINTF, and VASPRINTF macros as replacements for their lowercase standard C library equivalents. These macros take an additional first argument, which is the memory type for the block of memory. A memory type is simply an ASCII string (of which only the first TYPED_MEM_TYPELEN - 1 characters are significant) containing a short, human-readable description of what the memory is being used for. Note it is the contents of the string, not the string pointer itself, which defines the type.

Once typed memory is enabled (see below), any memory allocated with a memory type must be reallocated and/or freed with that same type, otherwise the library will immediately abort with an assertion failure. Similarly, invoking REALLOC, REALLOCF or FREE with a pointer that was not returned by one of the allocation macros will also cause an abort. In addition, FREE never modifies the value of errno.

To accomodate code that is not participating in the typed memory system, a NULL type may always be used to indicate a block that should not be accounted for. That is, the NULL memory type just falls through to the existing malloc(3), free(3), etc. For example, scandir(3) returns a heap-allocated array namelist which the caller must free. Instead of calling free namelist the caller may call FREE NULL namelist. Calling FREE in this case with any type other than NULL would result in an assertion failure. Similarly, memory allocated with NULL memory type may be freed via the normal free(3).

Memory allocated by the typed_mem macros is bracketed by guard bytes before and after the returned region. The REALLOC, REALLOCF and FREE routines detect if the program has modified these bytes, and they generate an assertion failure if so.

If a source file consistently uses the typed memory macros for all heap memory operations, then it may define TYPED_MEM_UNDEFINE_ORIGINALS before including <pdel/util/typed_mem.h>. This will cause the lowercase names to be redefined in such a way that their use will prevent the source file from compiling. This helps avoid inadvertently mixing the libc routines with typed memory routines.

Participation in the typed memory system is optional and configurable at run time. To enable typed memory accounting, typed_mem_enable must be called once at program start before any heap allocations are performed. This function returns zero if successful, or else -1 with errno set to EALREADY if a typed memory allocation has already been performed.

If typed_mem_enable is never called, then all of the above macros ignore their type argument and simply fall through to the underlying libc routines, therefore having no effect. The program will behave exactly as if the original functions had been used, except that there is one function call of overhead for each macro.

typed_mem_usage may be called to get the current statistics on memory types and usage. An array of statistics structures is returned, one for each type, containing the number of blocks and total bytes allocated under that type:

/* Statistics for a single memory type */
struct typed_mem_typestats {
    char      type[TYPED_MEM_TYPELEN];    /* type string + ’\0’ */
    u_int     allocs;                     /* # blocks alloc’d */
    u_int     bytes;                      /* # bytes alloc’d */
};

/* Variable length array of ’struct typed_mem_typestats’ */ DEFINE_STRUCTS_ARRAY(typed_mem_stats, struct typed_mem_typestats);

The array is sorted lexicographically by type name. The array itself must be eventually freed by the caller, by invoking:

structs_free(&typed_mem_stats_type, NULL, stats);

typed_mem_usage returns zero if successful, or else -1 and sets errno if there was an error; in particular, ENXIO if typed memory is not enabled.

A structs(3) type typed_mem_stats_type describing a struct typed_mem_stats is pre-defined.

typed_mem_type retrieves the type for the memory block pointed to by mem and writes it (including terminating ’\0’) into the buffer pointed to by typebuf, which must have size at least TYPED_MEM_TYPELEN. If successful, typed_mem_type returns typebuf; otherwise typed_mem_type returns NULL. This will happen if typed_mem_enable has not been called, if mem was allocated with type NULL, or if mem was never returned by any of these allocation routines.

typed_mem_dump prints out the current statistics on memory types and usage to the supplied output stream.

The typed_mem routines may safely be called from multiple threads simultaneously.

SEE ALSO

assert(3), libpdel(3), malloc(3), printf(3), structs(3), structs_type_array(3)

HISTORY

The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/

AUTHORS


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.