malloc(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/malloc.html | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 man/man3/malloc.html (limited to 'man/man3/malloc.html') diff --git a/man/man3/malloc.html b/man/man3/malloc.html new file mode 100644 index 00000000..9c30c293 --- /dev/null +++ b/man/man3/malloc.html @@ -0,0 +1,181 @@ + +malloc(3) - Plan 9 from User Space + + + + +

MALLOC(3) MALLOC(3) +

+
+

NAME
+ +
+ + malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, + getmalloctag, getrealloctag – memory allocator
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> + #include <libc.h> + + + void* malloc(ulong size) + + + void* mallocz(ulong size, int clr) + + + void free(void *ptr) + + + void* realloc(void *ptr, ulong size) + + + void* calloc(ulong nelem, ulong elsize) + + + void setmalloctag(void *ptr, ulong tag) + + + ulong getmalloctag(void *ptr) + + + void setrealloctag(void *ptr, ulong tag) + + + ulong getrealloctag(void *ptr) + +
+

DESCRIPTION
+ +
+ + Malloc and free provide a simple memory allocation package. Malloc + returns a pointer to a new block of at least size bytes. The block + is suitably aligned for storage of any type of object. No two + active pointers from malloc will have the same value. The call + malloc(0) returns a valid pointer rather than null. +
+ + The argument to free is a pointer to a block previously allocated + by malloc; this space is made available for further allocation. + It is legal to free a null pointer; the effect is a no-op. The + contents of the space returned by malloc are undefined. Mallocz + behaves as malloc, except that if clr is non-zero, the memory + returned will be zeroed. +
+ + Realloc changes the size of the block pointed to by ptr to size + bytes and returns a pointer to the (possibly moved) block. The + contents will be unchanged up to the lesser of the new and old + sizes. Realloc takes on special meanings when one or both arguments + are zero:
+ realloc(0, size) + +
+ + means malloc(size); returns a pointer to the newly-allocated memory
+ +
+ realloc(ptr, 0) + +
+ + means free(ptr); returns null
+ +
+ realloc(0, 0) + +
+ + no-op; returns null +
+ + +
+ Calloc allocates space for an array of nelem elements of size + elsize. The space is initialized to zeros. Free frees such a block. + +
+ + The memory allocator on Plan 9 maintains two word-sized fields + associated with each block, the “malloc tag” and the “realloc + tag”. By convention, the malloc tag is the PC that allocated the + block, and the realloc tag the PC that last reallocated the block. + These may be set or examined with setmalloctag, getmalloctag, + setrealloctag, and getrealloctag. When allocating blocks directly + with malloc and realloc, these tags will be set properly. If a + custom allocator wrapper is used, the allocator wrapper can set + the tags itself (usually by passing the result of getcallerpc(3) + to setmalloctag) to provide more useful information about the + source + of allocation.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/malloc.c + /usr/local/plan9/src/lib9/malloctag.c + +
+

SEE ALSO
+ +
+ + trump (in acid(1)), getcallerpc(3)
+ +
+

DIAGNOSTICS
+ +
+ + Malloc, realloc and calloc return 0 if there is no available memory. + Errstr is likely to be set. If the allocated blocks have no malloc + or realloc tags, getmalloctag and getrealloctag return ~0. +
+ + The trump library for acid can be used to obtain traces of malloc + execution; see acid(1).
+ +
+

BUGS
+ +
+ + The different specification of calloc is bizarre. +
+ + User errors can corrupt the storage arena. The most common gaffes + are (1) freeing an already freed block, (2) storing beyond the + bounds of an allocated block, and (3) freeing data that was not + obtained from the allocator. When malloc and free detect such + corruption, they abort. +
+ + To avoid name conflicts with the system versions of these functions, + malloc, realloc, calloc, and free are preprocessor macros defined + as p9malloc, p9realloc, p9calloc, and p9free; see intro(3).
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3