memalign(3malloc)

1malloc(3MALLOC)       Memory Allocation Library Functions      malloc(3MALLOC)
2
3
4

NAME

6       malloc,  free,  memalign,  realloc, valloc, calloc, mallopt, mallinfo -
7       memory allocator
8

SYNOPSIS

10       cc [ flag ... ] file ... -lmalloc [ library ... ]
11       #include <stdlib.h>
12
13       void *malloc(size_t size);
14
15
16       void free(void *ptr);
17
18
19       void *memalign(size_t alignment, size_t size);
20
21
22       void *realloc(void *ptr, size_t size);
23
24
25       void *valloc(size_t size);
26
27
28       void *calloc(size_t nelem, size_t elsize);
29
30
31       #include <malloc.h>
32
33       int mallopt(int cmd, int value);
34
35
36       struct mallinfo mallinfo(void);
37
38

DESCRIPTION

40       The malloc() and free() functions provide a simple general-purpose mem‐
41       ory allocation package.
42
43
44       The  malloc()  function  returns  a pointer to a block of at least size
45       bytes suitably aligned for any use.
46
47
48       The argument to free() is a pointer to a block previously allocated  by
49       malloc().  After  free() is performed, this space is made available for
50       further allocation, and its contents have been destroyed. See mallopt()
51       below  for  a way to change this behavior. If ptr is a null pointer, no
52       action occurs.
53
54
55       Undefined results occur if the space assigned by malloc() is overrun or
56       if some random number is handed to free().
57
58
59       The free() function does not set errno.
60
61
62       The  memalign()  function allocates size bytes on a specified alignment
63       boundary and returns a pointer to the allocated block. The value of the
64       returned address is guaranteed to be an even multiple of alignment. The
65       value of alignment must be a power of two and must be greater  than  or
66       equal to the size of a word.
67
68
69       The  realloc() function changes the size of the block pointed to by ptr
70       to size bytes and returns a pointer to the (possibly moved) block.  The
71       contents  will  be unchanged up to the lesser of the new and old sizes.
72       If the new size of the block requires movement of the block, the  space
73       for  the  previous instantiation of the block is freed. If the new size
74       is larger, the contents of the newly allocated portion of the block are
75       unspecified.  If  ptr  is NULL, realloc() behaves like malloc() for the
76       specified size. If size is 0 and ptr is not a null pointer,  the  space
77       pointed to is freed.
78
79
80       The  valloc() function has the same effect as malloc(), except that the
81       allocated memory will be aligned to a multiple of the value returned by
82       sysconf(_SC_PAGESIZE).
83
84
85       The calloc() function allocates space for an array of nelem elements of
86       size elsize. The space is initialized to zeros.
87
88
89       The mallopt() function provides for control over the  allocation  algo‐
90       rithm. The available values for cmd are:
91
92       M_MXFAST    Set  maxfast  to  value. The algorithm allocates all blocks
93                   below the size of maxfast in large groups  and  then  doles
94                   them out very quickly. The default value for maxfast is 24.
95
96
97       M_NLBLKS    Set numlblks to value. The above mentioned ``large groups''
98                   each contain numlblks blocks.   numlblks  must  be  greater
99                   than 0. The default value for numlblks is 100.
100
101
102       M_GRAIN     Set  grain  to  value. The sizes of all blocks smaller than
103                   maxfast are considered to be rounded up to the nearest mul‐
104                   tiple  of  grain. grain must be greater than 0. The default
105                   value of grain is the smallest number of  bytes  that  will
106                   allow  alignment of any data type. Value will be rounded up
107                   to a multiple of the default when grain is set.
108
109
110       M_KEEP      Preserve data in a freed block  until  the  next  malloc(),
111                   realloc(),  or  calloc().  This option is provided only for
112                   compatibility with the old version of malloc(), and  it  is
113                   not recommended.
114
115
116
117       These values are defined in the <malloc.h> header.
118
119
120       The  mallopt()  function can be called repeatedly, but cannot be called
121       after the first small block is allocated.
122
123
124       The  mallinfo()  function  provides  instrumentation  describing  space
125       usage. It returns the mallinfo structure with the following members:
126
127         unsigned long arena;      /* total space in arena */
128         unsigned long ordblks;    /* number of ordinary blocks */
129         unsigned long smblks;     /* number of small blocks */
130         unsigned long hblkhd;     /* space in holding block headers */
131         unsigned long hblks;      /* number of holding blocks */
132         unsigned long usmblks;    /* space in small blocks in use */
133         unsigned long fsmblks;    /* space in free small blocks */
134         unsigned long uordblks;   /* space in ordinary blocks in use */
135         unsigned long fordblks;   /* space in free ordinary blocks */
136         unsigned long keepcost;   /* space penalty if keep option */
137                                   /* is used */
138
139
140
141       The mallinfo structure is defined in the <malloc.h> header.
142
143
144       Each  of  the  allocation  routines returns a pointer to space suitably
145       aligned (after possible pointer coercion) for storage of  any  type  of
146       object.
147

RETURN VALUES

149       The  malloc(),  memalign(), realloc(), valloc(), and calloc() functions
150       return a null pointer if there is not  enough  available  memory.  When
151       realloc()  returns NULL, the block pointed to by ptr is left intact. If
152       size, nelem, or elsize is 0, either a null pointer or a unique  pointer
153       that  can be passed to free() is returned. If mallopt() is called after
154       any allocation or if cmd or value are  invalid,  a  non-zero  value  is
155       returned. Otherwise, it returns 0.
156

ERRORS

158       If  malloc(),  calloc(), or realloc() returns  unsuccessfully, errno is
159       set to indicate the error:
160
161       ENOMEM    size bytes of memory exceeds the physical limits of your sys‐
162                 tem, and cannot be allocated.
163
164
165       EAGAIN    There is not enough memory available at this point in time to
166                 allocate size bytes of memory; but the application could  try
167                 again later.
168
169

USAGE

171       Unlike  malloc(3C),  this  package  does not preserve the contents of a
172       block when it is freed, unless  the M_KEEP option of mallopt() is used.
173
174
175       Undocumented features of  malloc(3C) have not been duplicated.
176
177
178       Function prototypes for malloc(), realloc(), calloc(), and  free()  are
179       also defined in the <malloc.h> header for compatibility with old appli‐
180       cations. New applications  should include <stdlib.h> to access the pro‐
181       totypes for these functions.
182
183
184       Comparative  features  of the various allocation libraries can be found
185       in the umem_alloc(3MALLOC) manual page.
186

ATTRIBUTES

188       See attributes(5) for descriptions of the following attributes:
189
190
191
192
193       ┌─────────────────────────────┬─────────────────────────────┐
194       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
195       ├─────────────────────────────┼─────────────────────────────┤
196       │MT-Level                     │Safe                         │
197       └─────────────────────────────┴─────────────────────────────┘
198