1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
| 1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
|
38.\"
39.Dd August 27, 1996
40.Dt MALLOC 3
41.Os
42.Sh NAME
43.Nm malloc , calloc , realloc , free , reallocf
44.Nd general purpose memory allocation functions
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.Fd #include <stdlib.h>
49.Ft void *
50.Fn malloc "size_t size"
51.Ft void *
52.Fn calloc "size_t number" "size_t size"
53.Ft void *
54.Fn realloc "void *ptr" "size_t size"
55.Ft void *
56.Fn reallocf "void *ptr" "size_t size"
57.Ft void
58.Fn free "void *ptr"
59.Ft char *
60.Va _malloc_options
61.Ft void
62.Fn \*(lp*_malloc_message\*(rp "char *p1" "char *p2" "char *p3" "char *p4"
63.Sh DESCRIPTION
64The
65.Fn malloc
66function allocates
67.Fa size
68bytes of memory.
69The allocated space is suitably aligned (after possible pointer coercion)
70for storage of any type of object.
71If the space is at least
72.Em pagesize
73bytes in length (see
74.Xr getpagesize 3 ) ,
75the returned memory will be page boundary aligned as well.
76If
77.Fn malloc
78fails, a
79.Dv NULL
80pointer is returned.
81.Pp
82Note that
83.Fn malloc
84does
85.Em NOT
86normally initialize the returned memory to zero bytes.
87.Pp
88The
89.Fn calloc
90function allocates space for
91.Fa number
92objects,
93each
94.Fa size
95bytes in length.
96The result is identical to calling
97.Fn malloc
98with an argument of
99.Dq "number * size" ,
100with the exception that the allocated memory is explicitly initialized
101to zero bytes.
102.Pp
103The
104.Fn realloc
105function changes the size of the previously allocated memory referenced by
106.Fa ptr
107to
108.Fa size
109bytes.
110The contents of the memory are unchanged up to the lesser of the new and
111old sizes.
112If the new size is larger,
113the value of the newly allocated portion of the memory is undefined.
114If the requested memory cannot be allocated,
115.Dv NULL
116is returned and
117the memory referenced by
118.Fa ptr
119is valid and unchanged.
120If
121.Fa ptr
122is
123.Dv NULL ,
124the
125.Fn realloc
126function behaves identically to
127.Fn malloc
128for the specified size.
129.Pp
130The
131.Fn reallocf
132function call is identical to the realloc function call, except that it
133will free the passed pointer when the requested memory cannot be allocated.
134This is a
135.Fx
136specific API designed to ease the problems with traditional coding styles
137for realloc causing memory leaks in libraries.
138.Pp
139The
140.Fn free
141function causes the allocated memory referenced by
142.Fa ptr
143to be made available for future allocations.
144If
145.Fa ptr
146is
147.Dv NULL ,
148no action occurs.
149.Sh TUNING
150Once, when the first call is made to one of these memory allocation
151routines, various flags will be set or reset, which affect the
152workings of this allocation implementation.
153.Pp
154The ``name'' of the file referenced by the symbolic link named
155.Pa /etc/malloc.conf ,
156the value of the environment variable
157.Ev MALLOC_OPTIONS ,
158and the string pointed to by the global variable
159.Va _malloc_options
160will be interpreted, in that order, character by character as flags.
161.Pp
162Most flags are single letters,
163where uppercase indicates that the behavior is set, or on,
164and lowercase means that the behavior is not set, or off.
165.Bl -tag -width indent
166.It A
167All warnings (except for the warning about unknown
168flags being set) become fatal.
169The process will call
170.Xr abort 3
171in these cases.
172.It J
173Each byte of new memory allocated by
174.Fn malloc ,
175.Fn realloc
176or
177.Fn reallocf
178as well as all memory returned by
179.Fn free ,
180.Fn realloc
181or
182.Fn reallocf
183will be initialized to 0xd0.
184This options also sets the
185.Dq R
186option.
187This is intended for debugging and will impact performance negatively.
188.It H
189Pass a hint to the kernel about pages unused by the allocation functions.
190This will help performance if the system is paging excessively. This
191option is off by default.
192.It R
193Causes the
194.Fn realloc
195and
196.Fn reallocf
197functions to always reallocate memory even if the initial allocation was
198sufficiently large.
199This can substantially aid in compacting memory.
200.It U
201Generate
202.Dq utrace
203entries for
204.Xr ktrace 1 ,
205for all operations.
206Consult the source for details on this option.
207.It V
208Attempting to allocate zero bytes will return a
209.Dv NULL
210pointer instead of
211a valid pointer.
212(The default behavior is to make a minimal allocation and return a
213pointer to it.)
214This option is provided for System V compatibility.
215This option is incompatible with the
216.Dq X
217option.
218.It X
219Rather than return failure for any allocation function,
220display a diagnostic message on stderr and cause the program to drop
221core (using
222.Xr abort 3 ) .
223This option should be set at compile time by including the following in
224the source code:
225.Bd -literal -offset indent
226_malloc_options = "X";
227.Ed
228.It Z
229This option implicitly sets the
230.Dq J
231and
232.Dq R
233options, and then zeros out the bytes that were requested.
234This is intended for debugging and will impact performance negatively.
235.It <
236Reduce the size of the cache by a factor of two.
237The default cache size is 16 pages.
238This option can be specified multiple times.
239.It >
240Double the size of the cache by a factor of two.
241The default cache size is 16 pages.
242This option can be specified multiple times.
243.El
244.Pp
245The
246.Dq J
247and
248.Dq Z
249options are intended for testing and debugging.
250An application which changes its behavior when these options are used
251is flawed.
252.Sh EXAMPLES
253To set a systemwide reduction of cache size, and to dump core whenever
254a problem occurs:
255.Pp
256.Bd -literal -offset indent
257ln -s 'A<' /etc/malloc.conf
258.Ed
259.Pp
260To specify in the source that a program does no return value checking
261on calls to these functions:
262.Bd -literal -offset indent
263_malloc_options = "X";
264.Ed
265.Sh ENVIRONMENT
266The following environment variables affect the execution of the allocation
267functions:
268.Bl -tag -width MMM
269.It Ev MALLOC_OPTIONS
270If the environment variable
271.Ev MALLOC_OPTIONS
272is set, the characters it contains will be interpreted as flags to the
273allocation functions.
274.El
275.Sh RETURN VALUES
276The
277.Fn malloc
278and
279.Fn calloc
280functions return a pointer to the allocated memory if successful; otherwise
281a
282.Dv NULL
283pointer is returned and
284.Va errno
285is set to
286.Er ENOMEM .
287.Pp
288The
289.Fn realloc
290and
291.Fn reallocf
292functions return a pointer, possibly identical to
293.Fa ptr ,
294to the allocated memory
295if successful; otherwise a
296.Dv NULL
297pointer is returned, in which case the
298memory referenced by
299.Fa ptr
300is still available and intact.
301In the case of memory allocation failure,
302.Va errno
303is set to
304.Er ENOMEM .
305.Pp
306The
307.Fn free
308function returns no value.
309.Sh DEBUGGING MALLOC PROBLEMS
310The major difference between this implementation and other allocation
311implementations is that the free pages are not accessed unless allocated,
312and are aggressively returned to the kernel for reuse.
313.Bd -ragged -offset indent
314Most allocation implementations will store a data structure containing a
315linked list in the free chunks of memory,
316used to tie all the free memory together.
317That can be suboptimal,
318as every time the free-list is traversed,
319the otherwise unused, and likely paged out,
320pages are faulted into primary memory.
321On systems which are paging,
322this can result in a factor of five increase in the number of page-faults
323done by a process.
324.Ed
325.Pp
326A side effect of this architecture is that many minor transgressions on
327the interface which would traditionally not be detected are in fact
328detected. As a result, programs that have been running happily for
329years may suddenly start to complain loudly, when linked with this
330allocation implementation.
331.Pp
332The first and most important thing to do is to set the
333.Dq A
334option.
335This option forces a coredump (if possible) at the first sign of trouble,
336rather than the normal policy of trying to continue if at all possible.
337.Pp
338It is probably also a good idea to recompile the program with suitable
339options and symbols for debugger support.
340.Pp
341If the program starts to give unusual results, coredump or generally behave
342differently without emitting any of the messages listed in the next
343section, it is likely because it depends on the storage being filled with
344zero bytes. Try running it with
345.Dq Z
346option set;
347if that improves the situation, this diagnosis has been confirmed.
348If the program still misbehaves,
349the likely problem is accessing memory outside the allocated area,
350more likely after than before the allocated area.
351.Pp
352Alternatively, if the symptoms are not easy to reproduce, setting the
353.Dq J
354option may help provoke the problem.
355.Pp
356In truly difficult cases, the
357.Dq U
358option, if supported by the kernel, can provide a detailed trace of
359all calls made to these functions.
360.Pp
361Unfortunately this implementation does not provide much detail about
362the problems it detects, the performance impact for storing such information
363would be prohibitive.
364There are a number of allocation implementations available on the 'Net
365which focus on detecting and pinpointing problems by trading performance
366for extra sanity checks and detailed diagnostics.
367.Sh DIAGNOSTIC MESSAGES
368If
369.Fn malloc ,
370.Fn calloc ,
371.Fn realloc
372or
373.Fn free
374detect an error or warning condition,
375a message will be printed to file descriptor STDERR_FILENO.
376Errors will result in the process dumping core.
377If the
378.Dq A
379option is set, all warnings are treated as errors.
380.Pp
381The
382.Va _malloc_message
383variable allows the programmer to override the function which emits
384the text strings forming the errors and warnings if for some reason
385the stderr filedescriptor is not suitable for this.
386Please note that doing anything which tries to allocate memory in
387this function will assure death of the process.
388.Pp
389The following is a brief description of possible error messages and
390their meanings:
391.Pp
392.Bl -tag -width indent
393.It "(ES): mumble mumble mumble
394The allocation functions were compiled with
395.Dq EXTRA_SANITY
396defined, and an error was found during the additional error checking.
397Consult the source code for further information.
| 38.\"
39.Dd August 27, 1996
40.Dt MALLOC 3
41.Os
42.Sh NAME
43.Nm malloc , calloc , realloc , free , reallocf
44.Nd general purpose memory allocation functions
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.Fd #include <stdlib.h>
49.Ft void *
50.Fn malloc "size_t size"
51.Ft void *
52.Fn calloc "size_t number" "size_t size"
53.Ft void *
54.Fn realloc "void *ptr" "size_t size"
55.Ft void *
56.Fn reallocf "void *ptr" "size_t size"
57.Ft void
58.Fn free "void *ptr"
59.Ft char *
60.Va _malloc_options
61.Ft void
62.Fn \*(lp*_malloc_message\*(rp "char *p1" "char *p2" "char *p3" "char *p4"
63.Sh DESCRIPTION
64The
65.Fn malloc
66function allocates
67.Fa size
68bytes of memory.
69The allocated space is suitably aligned (after possible pointer coercion)
70for storage of any type of object.
71If the space is at least
72.Em pagesize
73bytes in length (see
74.Xr getpagesize 3 ) ,
75the returned memory will be page boundary aligned as well.
76If
77.Fn malloc
78fails, a
79.Dv NULL
80pointer is returned.
81.Pp
82Note that
83.Fn malloc
84does
85.Em NOT
86normally initialize the returned memory to zero bytes.
87.Pp
88The
89.Fn calloc
90function allocates space for
91.Fa number
92objects,
93each
94.Fa size
95bytes in length.
96The result is identical to calling
97.Fn malloc
98with an argument of
99.Dq "number * size" ,
100with the exception that the allocated memory is explicitly initialized
101to zero bytes.
102.Pp
103The
104.Fn realloc
105function changes the size of the previously allocated memory referenced by
106.Fa ptr
107to
108.Fa size
109bytes.
110The contents of the memory are unchanged up to the lesser of the new and
111old sizes.
112If the new size is larger,
113the value of the newly allocated portion of the memory is undefined.
114If the requested memory cannot be allocated,
115.Dv NULL
116is returned and
117the memory referenced by
118.Fa ptr
119is valid and unchanged.
120If
121.Fa ptr
122is
123.Dv NULL ,
124the
125.Fn realloc
126function behaves identically to
127.Fn malloc
128for the specified size.
129.Pp
130The
131.Fn reallocf
132function call is identical to the realloc function call, except that it
133will free the passed pointer when the requested memory cannot be allocated.
134This is a
135.Fx
136specific API designed to ease the problems with traditional coding styles
137for realloc causing memory leaks in libraries.
138.Pp
139The
140.Fn free
141function causes the allocated memory referenced by
142.Fa ptr
143to be made available for future allocations.
144If
145.Fa ptr
146is
147.Dv NULL ,
148no action occurs.
149.Sh TUNING
150Once, when the first call is made to one of these memory allocation
151routines, various flags will be set or reset, which affect the
152workings of this allocation implementation.
153.Pp
154The ``name'' of the file referenced by the symbolic link named
155.Pa /etc/malloc.conf ,
156the value of the environment variable
157.Ev MALLOC_OPTIONS ,
158and the string pointed to by the global variable
159.Va _malloc_options
160will be interpreted, in that order, character by character as flags.
161.Pp
162Most flags are single letters,
163where uppercase indicates that the behavior is set, or on,
164and lowercase means that the behavior is not set, or off.
165.Bl -tag -width indent
166.It A
167All warnings (except for the warning about unknown
168flags being set) become fatal.
169The process will call
170.Xr abort 3
171in these cases.
172.It J
173Each byte of new memory allocated by
174.Fn malloc ,
175.Fn realloc
176or
177.Fn reallocf
178as well as all memory returned by
179.Fn free ,
180.Fn realloc
181or
182.Fn reallocf
183will be initialized to 0xd0.
184This options also sets the
185.Dq R
186option.
187This is intended for debugging and will impact performance negatively.
188.It H
189Pass a hint to the kernel about pages unused by the allocation functions.
190This will help performance if the system is paging excessively. This
191option is off by default.
192.It R
193Causes the
194.Fn realloc
195and
196.Fn reallocf
197functions to always reallocate memory even if the initial allocation was
198sufficiently large.
199This can substantially aid in compacting memory.
200.It U
201Generate
202.Dq utrace
203entries for
204.Xr ktrace 1 ,
205for all operations.
206Consult the source for details on this option.
207.It V
208Attempting to allocate zero bytes will return a
209.Dv NULL
210pointer instead of
211a valid pointer.
212(The default behavior is to make a minimal allocation and return a
213pointer to it.)
214This option is provided for System V compatibility.
215This option is incompatible with the
216.Dq X
217option.
218.It X
219Rather than return failure for any allocation function,
220display a diagnostic message on stderr and cause the program to drop
221core (using
222.Xr abort 3 ) .
223This option should be set at compile time by including the following in
224the source code:
225.Bd -literal -offset indent
226_malloc_options = "X";
227.Ed
228.It Z
229This option implicitly sets the
230.Dq J
231and
232.Dq R
233options, and then zeros out the bytes that were requested.
234This is intended for debugging and will impact performance negatively.
235.It <
236Reduce the size of the cache by a factor of two.
237The default cache size is 16 pages.
238This option can be specified multiple times.
239.It >
240Double the size of the cache by a factor of two.
241The default cache size is 16 pages.
242This option can be specified multiple times.
243.El
244.Pp
245The
246.Dq J
247and
248.Dq Z
249options are intended for testing and debugging.
250An application which changes its behavior when these options are used
251is flawed.
252.Sh EXAMPLES
253To set a systemwide reduction of cache size, and to dump core whenever
254a problem occurs:
255.Pp
256.Bd -literal -offset indent
257ln -s 'A<' /etc/malloc.conf
258.Ed
259.Pp
260To specify in the source that a program does no return value checking
261on calls to these functions:
262.Bd -literal -offset indent
263_malloc_options = "X";
264.Ed
265.Sh ENVIRONMENT
266The following environment variables affect the execution of the allocation
267functions:
268.Bl -tag -width MMM
269.It Ev MALLOC_OPTIONS
270If the environment variable
271.Ev MALLOC_OPTIONS
272is set, the characters it contains will be interpreted as flags to the
273allocation functions.
274.El
275.Sh RETURN VALUES
276The
277.Fn malloc
278and
279.Fn calloc
280functions return a pointer to the allocated memory if successful; otherwise
281a
282.Dv NULL
283pointer is returned and
284.Va errno
285is set to
286.Er ENOMEM .
287.Pp
288The
289.Fn realloc
290and
291.Fn reallocf
292functions return a pointer, possibly identical to
293.Fa ptr ,
294to the allocated memory
295if successful; otherwise a
296.Dv NULL
297pointer is returned, in which case the
298memory referenced by
299.Fa ptr
300is still available and intact.
301In the case of memory allocation failure,
302.Va errno
303is set to
304.Er ENOMEM .
305.Pp
306The
307.Fn free
308function returns no value.
309.Sh DEBUGGING MALLOC PROBLEMS
310The major difference between this implementation and other allocation
311implementations is that the free pages are not accessed unless allocated,
312and are aggressively returned to the kernel for reuse.
313.Bd -ragged -offset indent
314Most allocation implementations will store a data structure containing a
315linked list in the free chunks of memory,
316used to tie all the free memory together.
317That can be suboptimal,
318as every time the free-list is traversed,
319the otherwise unused, and likely paged out,
320pages are faulted into primary memory.
321On systems which are paging,
322this can result in a factor of five increase in the number of page-faults
323done by a process.
324.Ed
325.Pp
326A side effect of this architecture is that many minor transgressions on
327the interface which would traditionally not be detected are in fact
328detected. As a result, programs that have been running happily for
329years may suddenly start to complain loudly, when linked with this
330allocation implementation.
331.Pp
332The first and most important thing to do is to set the
333.Dq A
334option.
335This option forces a coredump (if possible) at the first sign of trouble,
336rather than the normal policy of trying to continue if at all possible.
337.Pp
338It is probably also a good idea to recompile the program with suitable
339options and symbols for debugger support.
340.Pp
341If the program starts to give unusual results, coredump or generally behave
342differently without emitting any of the messages listed in the next
343section, it is likely because it depends on the storage being filled with
344zero bytes. Try running it with
345.Dq Z
346option set;
347if that improves the situation, this diagnosis has been confirmed.
348If the program still misbehaves,
349the likely problem is accessing memory outside the allocated area,
350more likely after than before the allocated area.
351.Pp
352Alternatively, if the symptoms are not easy to reproduce, setting the
353.Dq J
354option may help provoke the problem.
355.Pp
356In truly difficult cases, the
357.Dq U
358option, if supported by the kernel, can provide a detailed trace of
359all calls made to these functions.
360.Pp
361Unfortunately this implementation does not provide much detail about
362the problems it detects, the performance impact for storing such information
363would be prohibitive.
364There are a number of allocation implementations available on the 'Net
365which focus on detecting and pinpointing problems by trading performance
366for extra sanity checks and detailed diagnostics.
367.Sh DIAGNOSTIC MESSAGES
368If
369.Fn malloc ,
370.Fn calloc ,
371.Fn realloc
372or
373.Fn free
374detect an error or warning condition,
375a message will be printed to file descriptor STDERR_FILENO.
376Errors will result in the process dumping core.
377If the
378.Dq A
379option is set, all warnings are treated as errors.
380.Pp
381The
382.Va _malloc_message
383variable allows the programmer to override the function which emits
384the text strings forming the errors and warnings if for some reason
385the stderr filedescriptor is not suitable for this.
386Please note that doing anything which tries to allocate memory in
387this function will assure death of the process.
388.Pp
389The following is a brief description of possible error messages and
390their meanings:
391.Pp
392.Bl -tag -width indent
393.It "(ES): mumble mumble mumble
394The allocation functions were compiled with
395.Dq EXTRA_SANITY
396defined, and an error was found during the additional error checking.
397Consult the source code for further information.
|
399This most likely means that the system is dangerously overloaded or that
400the process' limits are incorrectly specified.
401.It "freelist is destroyed
402The internal free-list has been corrupted.
403.El
404.Pp
405.Bl -tag -width indent
406The following is a brief description of possible warning messages and
407their meanings:
408.Pp
409.It "chunk/page is already free
410The process attempted to
411.Fn free
412memory which had already been freed.
413.It "junk pointer ...
414A pointer specified to one of the allocation functions points outside the
415bounds of the memory of which they are aware.
416.It "malloc() has never been called
417No memory has been allocated,
418yet something is being freed or
419realloc'ed.
420.It "modified (chunk-/page-) pointer
421The pointer passed to
422.Fn free
423or
424.Fn realloc
425has been modified.
426.It "pointer to wrong page
427The pointer that
428.Fn malloc
429or
430.Fn calloc
431is trying to free does not reference a possible page.
432.It "recursive call
433A process has attempted to call an allocation function recursively.
434This is not permitted. In particular, signal handlers should not
435attempt to allocate memory.
436.It "out of memory
437The
438.Dq X
439option was specified and an allocation of memory failed.
440.It "unknown char in MALLOC_OPTIONS
441An unknown option was specified.
442Even with the
443.Dq A
444option set, this warning is still only a warning.
445.El
446.Sh SEE ALSO
447.Xr brk 2 ,
448.Xr mmap 2 ,
449.Xr alloca 3 ,
450.Xr getpagesize 3 ,
451.Xr memory 3
452.Pa /usr/share/doc/papers/malloc.ascii.gz
453.Sh STANDARDS
454The
455.Fn malloc ,
456.Fn calloc ,
457.Fn realloc
458and
459.Fn free
460functions conform to
461.St -isoC .
462.Sh HISTORY
463The present allocation implementation started out as a filesystem for a
464drum attached to a 20bit binary challenged computer which was built
465with discrete germanium transistors. It has since graduated to
466handle primary storage rather than secondary.
467It first appeared in its new shape and ability in
468.Fx 2.2 .
469.Pp
470The
471.Xr reallocf 3
472function first appeared in
473.Fx 3.0 .
474.Sh AUTHORS
475.An Poul-Henning Kamp Aq phk@FreeBSD.org
476.Sh BUGS
477The messages printed in case of problems provide no detail about the
478actual values.
479.Pp
480It can be argued that returning a
481.Dv NULL
482pointer when asked to
483allocate zero bytes is a silly response to a silly question.
| 402This most likely means that the system is dangerously overloaded or that
403the process' limits are incorrectly specified.
404.It "freelist is destroyed
405The internal free-list has been corrupted.
406.El
407.Pp
408.Bl -tag -width indent
409The following is a brief description of possible warning messages and
410their meanings:
411.Pp
412.It "chunk/page is already free
413The process attempted to
414.Fn free
415memory which had already been freed.
416.It "junk pointer ...
417A pointer specified to one of the allocation functions points outside the
418bounds of the memory of which they are aware.
419.It "malloc() has never been called
420No memory has been allocated,
421yet something is being freed or
422realloc'ed.
423.It "modified (chunk-/page-) pointer
424The pointer passed to
425.Fn free
426or
427.Fn realloc
428has been modified.
429.It "pointer to wrong page
430The pointer that
431.Fn malloc
432or
433.Fn calloc
434is trying to free does not reference a possible page.
435.It "recursive call
436A process has attempted to call an allocation function recursively.
437This is not permitted. In particular, signal handlers should not
438attempt to allocate memory.
439.It "out of memory
440The
441.Dq X
442option was specified and an allocation of memory failed.
443.It "unknown char in MALLOC_OPTIONS
444An unknown option was specified.
445Even with the
446.Dq A
447option set, this warning is still only a warning.
448.El
449.Sh SEE ALSO
450.Xr brk 2 ,
451.Xr mmap 2 ,
452.Xr alloca 3 ,
453.Xr getpagesize 3 ,
454.Xr memory 3
455.Pa /usr/share/doc/papers/malloc.ascii.gz
456.Sh STANDARDS
457The
458.Fn malloc ,
459.Fn calloc ,
460.Fn realloc
461and
462.Fn free
463functions conform to
464.St -isoC .
465.Sh HISTORY
466The present allocation implementation started out as a filesystem for a
467drum attached to a 20bit binary challenged computer which was built
468with discrete germanium transistors. It has since graduated to
469handle primary storage rather than secondary.
470It first appeared in its new shape and ability in
471.Fx 2.2 .
472.Pp
473The
474.Xr reallocf 3
475function first appeared in
476.Fx 3.0 .
477.Sh AUTHORS
478.An Poul-Henning Kamp Aq phk@FreeBSD.org
479.Sh BUGS
480The messages printed in case of problems provide no detail about the
481actual values.
482.Pp
483It can be argued that returning a
484.Dv NULL
485pointer when asked to
486allocate zero bytes is a silly response to a silly question.
|