Return to malloc.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / stdlib

Annotation of 43BSDReno/lib/libc/stdlib/malloc.3, revision 1.1.1.1

1.1       root        1: .\" Copyright (c) 1980 Regents of the University of California.
                      2: .\" All rights reserved.  The Berkeley software License Agreement
                      3: .\" specifies the terms and conditions for redistribution.
                      4: .\"
                      5: .\"    @(#)malloc.3    6.4 (Berkeley) 6/9/89
                      6: .\"
                      7: .TH MALLOC 3  "June 9, 1989"
                      8: .UC 4
                      9: .SH NAME
                     10: malloc, free, realloc, calloc, alloca \- memory allocator
                     11: .SH SYNOPSIS
                     12: .nf
                     13: .B char *malloc(size)
                     14: .B unsigned size;
                     15: .PP
                     16: .B free(ptr)
                     17: .B char *ptr;
                     18: .PP
                     19: .B char *realloc(ptr, size)
                     20: .B char *ptr;
                     21: .B unsigned size;
                     22: .PP
                     23: .B char *calloc(nelem, elsize)
                     24: .B unsigned nelem, elsize;
                     25: .PP
                     26: .B char *alloca(size)
                     27: .B int size;
                     28: .fi
                     29: .SH DESCRIPTION
                     30: .I Malloc
                     31: and
                     32: .I free
                     33: provide a general-purpose memory allocation package.
                     34: .I Malloc
                     35: returns a pointer to a block of at least
                     36: .I size
                     37: bytes beginning on a word boundary.
                     38: .PP
                     39: The argument to
                     40: .I free
                     41: is a pointer to a block previously allocated by
                     42: .IR malloc ;
                     43: this space is made available for further allocation,
                     44: but its contents are left undisturbed.
                     45: .PP
                     46: Needless to say, grave disorder will result if the space assigned by
                     47: .I malloc
                     48: is overrun or if some random number is handed to
                     49: .IR free .
                     50: .PP
                     51: .I Malloc
                     52: maintains multiple lists of free blocks according to size,
                     53: allocating space from the appropriate list.
                     54: It calls
                     55: .I sbrk
                     56: (see
                     57: .IR brk (2))
                     58: to get more memory from the system when there is no
                     59: suitable space already free.
                     60: .PP
                     61: .I Realloc
                     62: changes the size of the block pointed to by
                     63: .I ptr
                     64: to
                     65: .I size
                     66: bytes and returns a pointer to the (possibly moved) block.
                     67: The contents will be unchanged up to the lesser of the new and old sizes.
                     68: If
                     69: .I ptr
                     70: is null,
                     71: .I realloc
                     72: simply returns the value of
                     73: .I malloc
                     74: called with an argument of
                     75: .IR size .
                     76: .PP
                     77: In order to be compatible with older versions,
                     78: .I realloc
                     79: also works if
                     80: .I ptr
                     81: points to a block freed since the last call of
                     82: .I malloc, realloc
                     83: or
                     84: .IR calloc ;
                     85: sequences of
                     86: .I free, malloc
                     87: and
                     88: .I realloc
                     89: were previously used to attempt storage compaction.
                     90: This procedure is no longer recommended.
                     91: .PP
                     92: .I Calloc
                     93: allocates space for an array of
                     94: .I nelem
                     95: elements of size
                     96: .I elsize.
                     97: The space is initialized to zeros.
                     98: .PP
                     99: .I Alloca
                    100: allocates 
                    101: .I size
                    102: bytes of space in the stack frame of the caller.
                    103: This temporary space is automatically freed on
                    104: return.
                    105: .PP
                    106: Each of the allocation routines returns a pointer
                    107: to space suitably aligned (after possible pointer coercion)
                    108: for storage of any type of object.
                    109: If the space is of
                    110: .I pagesize
                    111: or larger, the memory returned will be page-aligned.
                    112: .SH SEE ALSO
                    113: brk(2),
                    114: pagesize(2)
                    115: .SH DIAGNOSTICS
                    116: .I Malloc, realloc
                    117: and
                    118: .I calloc
                    119: return a null pointer (0) if there is no available memory or if the arena
                    120: has been detectably corrupted by storing outside the bounds of a block.
                    121: .I Malloc
                    122: may be recompiled to check the arena very stringently on every transaction;
                    123: those sites with a source code license may check the source code to see
                    124: how this can be done.
                    125: .SH BUGS
                    126: When
                    127: .I realloc
                    128: returns 0, the block pointed to by
                    129: .I ptr
                    130: may be destroyed.
                    131: .PP
                    132: The current implementation of
                    133: .I malloc
                    134: does not always fail gracefully when system
                    135: memory limits are approached.
                    136: It may fail to allocate memory when larger free blocks could be broken
                    137: up, or when limits are exceeded because the size is rounded up.
                    138: It is optimized for sizes that are powers of two.
                    139: .PP
                    140: .I Alloca
                    141: is machine dependent; its use is discouraged.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.