free man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

MALLOC(2)							     MALLOC(2)

NAME
       malloc,	mallocalign, mallocz, free, realloc, calloc, msize, setmalloc‐
       tag, setrealloctag, getmalloctag,  getrealloctag,  malloctopoolblock  -
       memory allocator

SYNOPSIS
       #include <u.h>
       #include <libc.h>

       void* malloc(ulong size)

       void* mallocalign(ulong size, ulong align, long offset, ulong span)

       void* mallocz(ulong size, int clr)

       void  free(void *ptr)

       void* realloc(void *ptr, ulong size)

       void* calloc(ulong nelem, ulong elsize)

       ulong msize(void *ptr)

       void  setmalloctag(void *ptr, ulong tag)

       ulong getmalloctag(void *ptr)

       void  setrealloctag(void *ptr, ulong tag)

       ulong getrealloctag(void *ptr)

       void* malloctopoolblock(void*)

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.

       Mallocalign allocates a block of at least size bytes of memory respect‐
       ing alignment contraints.  If align is non-zero, the  returned  pointer
       is  aligned  to	be equal to offset modulo align.  If span is non-zero,
       the size-byte block allocated will not span a span-byte boundary.

       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, sz)
	      means returns a pointer to the newly-allocated memory

       realloc(ptr, 0)
	      means 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.

       When a block is allocated, sometimes there is some extra	 unused	 space
       at  the	end.  Msize grows the block to encompass this unused space and
       returns the new number of bytes that may be used.

       The memory allocator 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 allo‐
       cator wrapper can set the tags itself (usually by passing the result of
       getcallerpc(2) to setmalloctag)	to  provide  more  useful  information
       about the source of allocation.

       Malloctopoolblock  takes	 the address of a block returned by malloc and
       returns the address of the corresponding block allocated by the pool(2)
       routines.

SOURCE
       /sys/src/libc/port/malloc.c

SEE ALSO
       leak(1), trump (in acid(1)), brk(2), getcallerpc(2), pool(2)

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.

       After including pool.h, the call poolcheck(mainmem) can be used to scan
       the storage arena for inconsistencies such as data written  beyond  the
       bounds  of  allocated  blocks.  It is often useful to combine this with
       with setting
	   mainmem->flags |= POOL_NOREUSE;
       at the beginning of your program.  This will cause malloc not to	 real‐
       locate  blocks  even  once they are freed; poolcheck(mainmem) will then
       detect writes to freed blocks.

       The trump library for acid can be used to obtain traces of malloc  exe‐
       cution; 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.

								     MALLOC(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net