diff options
| author | lukem <lukem@NetBSD.org> | 1999-08-02 03:18:46 +0000 |
|---|---|---|
| committer | lukem <lukem@NetBSD.org> | 1999-08-02 03:18:46 +0000 |
| commit | c2601fffeebc82a2f1ea844841a6f94f575da778 (patch) | |
| tree | da688dbaa82ffa5be878f56fefb037695aec2737 /lib/libc/stdlib | |
| parent | 95d53bad01cd3d352a7e3037bdd4b18ae8939e46 (diff) | |
replace malloc(3) with one from freebsd which documents our new malloc.c
(also from freebsd). comment out references to reallocf with .\"XXX"
for now. i also fixed some roff misuse as well.
replace calloc(3), free(3) and realloc(3) with links to malloc(3)
Diffstat (limited to 'lib/libc/stdlib')
| -rw-r--r-- | lib/libc/stdlib/Makefile.inc | 7 | ||||
| -rw-r--r-- | lib/libc/stdlib/calloc.3 | 74 | ||||
| -rw-r--r-- | lib/libc/stdlib/free.3 | 83 | ||||
| -rw-r--r-- | lib/libc/stdlib/malloc.3 | 429 | ||||
| -rw-r--r-- | lib/libc/stdlib/realloc.3 | 103 |
5 files changed, 403 insertions, 293 deletions
diff --git a/lib/libc/stdlib/Makefile.inc b/lib/libc/stdlib/Makefile.inc index 06db9f5b251..f82d5ac43d5 100644 --- a/lib/libc/stdlib/Makefile.inc +++ b/lib/libc/stdlib/Makefile.inc @@ -1,4 +1,4 @@ -# $NetBSD: Makefile.inc,v 1.43 1999/06/26 04:44:36 tls Exp $ +# $NetBSD: Makefile.inc,v 1.44 1999/08/02 03:18:46 lukem Exp $ # from: @(#)Makefile.inc 8.3 (Berkeley) 2/4/95 # stdlib sources @@ -20,14 +20,15 @@ SRCS+= _rand48.c _strtoq.c _strtouq.c a64l.c abort.c atexit.c atof.c \ .include "${ARCHDIR}/stdlib/Makefile.inc" MAN+= a64l.3 abort.3 abs.3 alloca.3 atexit.3 atof.3 atoi.3 atol.3 bsearch.3 \ - calloc.3 div.3 exit.3 free.3 getenv.3 getopt.3 getsubopt.3 \ + div.3 exit.3 getenv.3 getopt.3 getsubopt.3 \ labs.3 ldiv.3 malloc.3 memory.3 qabs.3 qdiv.3 qsort.3 \ - radixsort.3 rand48.3 rand.3 random.3 realloc.3 strtod.3 \ + radixsort.3 rand48.3 rand.3 random.3 strtod.3 \ strtol.3 strtoul.3 system.3 tsearch.3 MLINKS+=a64l.3 l64a.3 MLINKS+=a64l.3 l64a_r.3 MLINKS+=getenv.3 setenv.3 getenv.3 unsetenv.3 getenv.3 putenv.3 +MLINKS+=malloc.3 calloc.3 malloc.3 realloc.3 malloc.3 free.3 MLINKS+=qsort.3 heapsort.3 qsort.3 mergesort.3 MLINKS+=rand.3 rand_r.3 MLINKS+=rand.3 srand.3 diff --git a/lib/libc/stdlib/calloc.3 b/lib/libc/stdlib/calloc.3 deleted file mode 100644 index dbcdb01c7f0..00000000000 --- a/lib/libc/stdlib/calloc.3 +++ /dev/null @@ -1,74 +0,0 @@ -.\" $NetBSD: calloc.3,v 1.7 1998/02/05 18:49:51 perry Exp $ -.\" -.\" Copyright (c) 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" the American National Standards Committee X3, on Information -.\" Processing Systems. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" from: @(#)calloc.3 8.1 (Berkeley) 6/4/93 -.\" -.Dd June 4, 1993 -.Dt CALLOC 3 -.Os -.Sh NAME -.Nm calloc -.Nd allocate clean memory (zero initialized space) -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.Fd #include <stdlib.h> -.Ft void * -.Fn calloc "size_t nmemb" "size_t size" -.Sh DESCRIPTION -The -.Fn calloc -function allocates space for an array of -.Fa nmemb -objects, each of whose size is -.Fa size . -The space is initialized to all bits zero. -.Sh RETURN VALUES -The -.Fn calloc -function returns -a pointer to -the allocated space if successful; otherwise a null pointer is returned. -.Sh SEE ALSO -.Xr malloc 3 , -.Xr realloc 3 , -.Xr free 3 -.Sh STANDARDS -The -.Fn calloc -function conforms to -.St -ansiC . diff --git a/lib/libc/stdlib/free.3 b/lib/libc/stdlib/free.3 deleted file mode 100644 index 5c7db82da24..00000000000 --- a/lib/libc/stdlib/free.3 +++ /dev/null @@ -1,83 +0,0 @@ -.\" $NetBSD: free.3,v 1.6 1998/04/28 21:19:49 fair Exp $ -.\" -.\" Copyright (c) 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" the American National Standards Committee X3, on Information -.\" Processing Systems. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" from: @(#)free.3 8.1 (Berkeley) 6/4/93 -.\" -.Dd June 4, 1993 -.Dt FREE 3 -.Os -.Sh NAME -.Nm free -.Nd free up memory allocated with malloc, calloc or realloc -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.Fd #include <stdlib.h> -.Ft void -.Fn free "void *ptr" -.Sh DESCRIPTION -The -.Fn free -function causes the space pointed to by -.Fa ptr -to be deallocated, that is, made available for further allocation. -If -.Fa ptr -is a null pointer, no action occurs. -Otherwise, if the argument does not match a pointer earlier returned by the -.Fn calloc -.Fn malloc -or -.Fn realloc -function, or if the space has been deallocated by a call to -.Fn free -or -.Fn realloc , -general havoc may occur. -.Sh RETURN VALUES -The -.Fn free -function returns no value. -.Sh SEE ALSO -.Xr calloc 3 , -.Xr malloc 3 , -.Xr realloc 3 -.Sh STANDARDS -The -.Fn free -function conforms to -.St -ansiC . diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3 index 6ac3172b6d1..e5abb3679b7 100644 --- a/lib/libc/stdlib/malloc.3 +++ b/lib/libc/stdlib/malloc.3 @@ -1,4 +1,4 @@ -.\" $NetBSD: malloc.3,v 1.9 1999/03/22 19:44:57 garbled Exp $ +.\" $NetBSD: malloc.3,v 1.10 1999/08/02 03:18:47 lukem Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -35,60 +35,429 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" from: @(#)malloc.3 8.1 (Berkeley) 6/4/93 +.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 +.\" From FreeBSD: Id: malloc.3,v 1.18 1999/03/28 14:16:04 phk Exp .\" -.Dd June 4, 1993 +.Dd August 2, 1999 .Dt MALLOC 3 .Os .Sh NAME -.Nm malloc -.Nd general memory allocation function +.Nm malloc , +.Nm calloc , +.Nm realloc , +.Nm free +.\"XXX", +.\"XXX".Nm reallocf +.Nd general purpose memory allocation functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include <stdlib.h> .Ft void * .Fn malloc "size_t size" +.Ft void * +.Fn calloc "size_t number" "size_t size" +.Ft void * +.Fn realloc "void *ptr" "size_t size" +.\"XXX".Ft void * +.\"XXX".Fn reallocf "void *ptr" "size_t size" +.Ft void +.Fn free "void *ptr" +.Ft char * +.Va malloc_options ; .Sh DESCRIPTION The .Fn malloc -function allocates uninitialized space for an object whose -size is specified by -.Fa size . +function allocates +.Fa size +bytes of memory. +The allocated space is suitably aligned (after possible pointer coercion) +for storage of any type of object. +If the space is at least +.Em pagesize +bytes in length (see +.Xr getpagesize 3 ) , +the returned memory will be page boundary aligned as well. +If +.Fn malloc +fails, a NULL pointer is returned. +.Pp +The +.Fn calloc +function allocates space for +.Fa number +objects, +each +.Fa size +bytes in length. +The result is identical to calling +.Fn malloc +with an argument of +.Dq "number * size" , +with the exception that the allocated memory is initialized to all bits zero. +.Pp The +.Fn realloc +function changes the size of the previously allocated memory referenced by +.Fa ptr +to +.Fa size +bytes. +The contents of the memory are unchanged up to the lesser of the new and +old sizes. +If the new size is larger, +the value of the newly allocated portion of the memory is undefined. +If the requested memory cannot be allocated, NULL is returned and +the memory referenced by +.Fa ptr +is valid and unchanged. +If +.Fa ptr +is NULL, the +.Fn realloc +function behaves identically to .Fn malloc -function maintains multiple lists of free blocks according to size, allocating -space from the appropriate list. +for the specified size. +.\"XXX".Pp +.\"XXX"The +.\"XXX".Fn reallocf +.\"XXX"function call is identical to the realloc function call, except that it +.\"XXX"will free the passed pointer when the requested memory cannot be allocated. +.\"XXX"This is a FreeBSD +.\"XXX"specific API designed to ease the problems with traditional coding styles +.\"XXX"for realloc causing memory leaks in libraries. .Pp -The allocated space is -suitably aligned (after possible pointer -coercion) for storage of any type of object. If the space is of -.Em pagesize -or larger, the memory returned will be page-aligned. +The +.Fn free +function causes the allocated memory referenced by +.Fa ptr +to be made available for future allocations. +If +.Fa ptr +is NULL, no action occurs. +.Sh TUNING +Once, when the first call is made to one of these memory allocation +routines, various flags will be set or reset, which affect the +workings of this allocation implementation. +.Pp +The ``name'' of the file referenced by the symbolic link named +.Pa /etc/malloc.conf , +the value of the environment variable +.Ev MALLOC_OPTIONS , +and the string pointed to by the global variable +.Va malloc_options +will be interpreted, in that order, character by character as flags. +.Pp +Most flags are single letters, +where uppercase indicates that the behavior is set, or on, +and lowercase means that the behavior is not set, or off. +.Bl -tag -width indent +.It A +All warnings (except for the warning about unknown +flags being set), and failure to allocate memory become fatal. +The process will call +.Fn abort 3 +in these cases. +.It J +Each byte of new memory allocated by +.\"XXX".Fn malloc , +.\"XXX".Fn realloc +.\"XXX"or +.\"XXX".Fn reallocf +.Fn malloc +or +.Fn realloc +as well as all memory returned by +.\"XXX".Fn free , +.\"XXX".Fn realloc +.\"XXX"or +.\"XXX"Fn reallocf +.Fn free +or +.Fn realloc +will be initialized to 0xd0. +This options also sets the +.Dq R +option. +This is intended for debugging and will impact performance negatively. +.It H +Pass a hint to the kernel about pages unused by the allocation functions. +This will help performance if the system is paging excessively. This +option is off by default. +.It R +Causes the +.Fn realloc +.\"XXX"and +.\"XXX".Fn reallocf +.\"XXX"functions +function +to always reallocate memory even if the initial allocation was +sufficiently large. +This can substantially aid in compacting memory. +.It U +Generate +.Dq utrace +entries for +.Xr ktrace 1 , +for all operations. +Consult the source for details on this option. +.It V +Attempting to allocate zero bytes will return a NULL pointer instead of +a valid pointer. +(The default behavior is to make a minimal allocation and return a +pointer to it.) +This option is provided for System V compatibility. +This option is incompatible with the +.Dq X +option. +.It X +Rather than return failure for any allocation function, +display a diagnostic message on stderr and cause the program to drop +core (using +.Fn abort 3 ) . +This option should be set at compile time by including the following in +the source code: +.Bd -literal -offset indent +extern char *malloc_options; +malloc_options = "X"; +.Ed +.It Z +This option implicitly sets the +.Dq J +and +.Dq R +options, and then zeros out the bytes that were requested. +This is intended for debugging and will impact performance negatively. +.It < +Reduce the size of the cache by a factor of two. +The default cache size is 16 pages. +This option can be specified multiple times. +.It > +Double the size of the cache by a factor of two. +The default cache size is 16 pages. +This option can be specified multiple times. +.El +.Pp +The +.Dq J +and +.Dq Z +options are intended for testing and debugging. +An application which changes its behavior when these options are used +is flawed. +.Sh EXAMPLES +To set a systemwide reduction of cache size, and to dump core whenever +a problem occurs: +.Pp +.Bd -literal -offset indent +ln -s 'A<' /etc/malloc.conf +.Ed +.Pp +To specify in the source that a program does no return value checking +on calls to these functions: +.Bd -literal -offset indent +extern char *malloc_options; +malloc_options = "X"; +.Ed +.Sh ENVIRONMENT +The following environment variables affect the execution of the allocation +functions: +.Bl -tag -width MMM +.It Ev MALLOC_OPTIONS +If the environment variable +.Ev MALLOC_OPTIONS +is set, the characters it contains will be interpreted as flags to the +allocation functions. +.El .Sh RETURN VALUES The .Fn malloc +and +.Fn calloc +functions return a pointer to the allocated memory if successful; otherwise +a NULL pointer is returned. +.Pp +The +.Fn realloc +.\"XXX"and +.\"XXX".Fn reallocf +.\"XXX"functions return function returns -a pointer to the allocated space if successful; otherwise -a null pointer is returned. +a pointer, possibly identical to +.Fa ptr , +to the allocated memory +if successful; otherwise a NULL pointer is returned, in which case the +memory referenced by +.Fa ptr +is still available and intact. +.Pp +The +.Fn free +function returns no value. +.Sh "DEBUGGING MALLOC PROBLEMS" +.Pp +The major difference between this implementation and other allocation +implementations is that the free pages are not accessed unless allocated, +and are aggressively returned to the kernel for reuse. +.Bd -filled -offset indent +Most allocation implementations will store a data structure containing a +linked list in the free chunks of memory, +used to tie all the free memory together. +That can be suboptimal, +as every time the free-list is traversed, +the otherwise unused, and likely paged out, +pages are faulted into primary memory. +On systems which are paging, +this can result in a factor of five increase in the number of page-faults +done by a process. +.Ed +.Pp +A side effect of this architecture is that many minor transgressions on +the interface which would traditionally not be detected are in fact +detected. As a result, programs that have been running happily for +years may suddenly start to complain loudly, when linked with this +allocation implementation. +.Pp +The first and most important thing to do is to set the +.Dq A +option. +This option forces a coredump (if possible) at the first sign of trouble, +rather than the normal policy of trying to continue if at all possible. +.Pp +It is probably also a good idea to recompile the program with suitable +options and symbols for debugger support. +.Pp +If the program starts to give unusual results, coredump or generally behave +differently without emitting any of the messages listed in the next +section, it is likely because it depends on the storage being filled with +nul bytes. Try running it with +.Dq Z +option set; +if that improves the situation, this diagnosis has been confirmed. +If the program still misbehaves, +the likely problem is accessing memory outside the allocated area, +more likely after than before the allocated area. +.Pp +Alternatively, if the symptoms are not easy to reproduce, setting the +.Dq J +option may help provoke the problem. +.Pp +In truly difficult cases, the +.Dq U +option, if supported by the kernel, can provide a detailed trace of +all calls made to these functions. +.Pp +Unfortunately this implementation does not provide much detail about +the problems it detects, the performance impact for storing such information +would be prohibitive. +There are a number of allocation implementations available on the 'Net +which focus on detecting and pinpointing problems by trading performance +for extra sanity checks and detailed diagnostics. +.Sh "DIAGNOSTIC MESSAGES +If +.Fn malloc , +.Fn calloc , +.Fn realloc +or +.Fn free +detect an error or warning condition, +a message will be printed to file descriptor STDERR_FILENO. +Errors will result in the process dumping core. +If the +.Dq A +option is set, all warnings are treated as errors. +.Pp +The following is a brief description of possible error messages and +their meanings: +.Pp +.Bl -tag -width indent +.It "(ES): mumble mumble mumble +The allocation functions were compiled with +.Dq EXTRA_SANITY +defined, and an error was found during the additional error checking. +Consult the source code for further information. +.It "allocation failed +If the +.Dq A +option is specified it is a fatal error for an allocation function to fail. +.It "mmap(2) failed, check limits +This most likely means that the system is dangerously overloaded or that +the process' limits are incorrectly specified. +.It "freelist is destroyed +The internal free-list has been corrupted. +.El +.Pp +.Bl -tag -width indent +The following is a brief description of possible warning messages and +their meanings: +.Pp +.It "chunk/page is already free +The process attempted to +.Fn free +memory which had already been freed. +.It "junk pointer ... +A pointer specified to one of the allocation functions points outside the +bounds of the memory of which they are aware. +.It "malloc() has never been called +No memory has been allocated, +yet something is being freed or +realloc'ed. +.It "modified (chunk-/page-) pointer +The pointer passed to +.Fn free +or +.Fn realloc +has been modified. +.It "pointer to wrong page +The pointer that +.Fn malloc +or +.Fn calloc +is trying to free does not reference a possible page. +.It "recursive call +A process has attempted to call an allocation function recursively. +This is not permitted. In particular, signal handlers should not +attempt to allocate memory. +.It "out of memory +The +.Dq X +option was specified and an allocation of memory failed. +.It "unknown char in MALLOC_OPTIONS +An unknown option was specified. +Even with the +.Dq A +option set, this warning is still only a warning. +.El .Sh SEE ALSO .Xr brk 2 , .Xr alloca 3 , -.Xr calloc 3 , -.Xr free 3 , .Xr getpagesize 3 , -.Xr memory 3 , -.Xr realloc 3 +.Xr memory 3 +.\"XXX" .Pa /usr/share/doc/papers/malloc.ascii.gz .Sh STANDARDS The -.Fn malloc -function conforms to +.Fn malloc , +.Fn calloc , +.Fn realloc +and +.Fn free +functions conform to .St -ansiC . .Sh BUGS -The current implementation of -.Fn malloc -does not always fail gracefully when system -memory limits are approached. -It may fail to allocate memory when larger free blocks could be broken -up, or when limits are exceeded because the size is rounded up. -It is optimized for sizes that are powers of two. +The messages printed in case of problems provide no detail about the +actual values. +.Pp +It can be argued that returning a null pointer when asked to +allocate zero bytes is a silly response to a silly question. +.Pp +This implementation was authored by Poul-Henning Kamp. +Please report any problems to him at +.Li <phk@FreeBSD.org> . +.Sh HISTORY +The present allocation implementation started out as a filesystem for a +drum attached to a 20bit binary challenged computer which was built +with discrete germanium transistors. It has since graduated to +handle primary storage rather than secondary. +It first appeared in its new shape and ability in +.Fx 2.2 , and then in +.Nx 1.5 . diff --git a/lib/libc/stdlib/realloc.3 b/lib/libc/stdlib/realloc.3 deleted file mode 100644 index 59b0d3893b8..00000000000 --- a/lib/libc/stdlib/realloc.3 +++ /dev/null @@ -1,103 +0,0 @@ -.\" $NetBSD: realloc.3,v 1.9 1998/04/28 21:19:50 fair Exp $ -.\" -.\" Copyright (c) 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" from: @(#)realloc.3 8.2 (Berkeley) 4/19/94 -.\" -.Dd April 19, 1994 -.Dt REALLOC 3 -.Os -.Sh NAME -.Nm realloc -.Nd reallocation of memory function -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.Fd #include <stdlib.h> -.Ft void * -.Fn realloc "void *ptr" "size_t size" -.Sh DESCRIPTION -The -.Fn realloc -function changes the size of the object pointed to by -.Fa ptr -to the size specified by -.Fa size . -The contents of the object are unchanged up to the lesser -of the new and old sizes. -If the new size is larger, the value of the newly allocated portion -of the object is indeterminate. -If -.Fa ptr -is a null pointer, the -.Fn realloc -function behaves like the -.Xr malloc 3 -function for the specified size. -Otherwise, if -.Fa ptr -does not match a pointer earlier returned by the -.Xr calloc 3 , -.Xr malloc 3 , -or -.Fn realloc -function, or if the space has been deallocated -by a call to the -.Fn free -or -.Fn realloc -function, unpredictable and usually detrimental -behavior will occur. -If the space cannot be allocated, the object -pointed to by -.Fa ptr -is unchanged. -If -.Fa size -is zero and -.Fa ptr -is not a null pointer, the object it points to is freed. -.Sh RETURN VALUES -The -.Fn realloc -function returns either a null pointer or a pointer -to the possibly moved allocated space. -.Sh SEE ALSO -.Xr alloca 3 , -.Xr calloc 3 , -.Xr free 3 , -.Xr malloc 3 -.Sh STANDARDS -The -.Fn realloc -function conforms to -.St -ansiC . |
