diff options
author | Mattias Andrée <maandree@operamail.com> | 2015-10-18 01:22:43 +0200 |
---|---|---|
committer | Mattias Andrée <maandree@operamail.com> | 2015-10-18 01:22:43 +0200 |
commit | 2c0185df759cf77052f5a0374d680046bcb5db5c (patch) | |
tree | 5f78fd9c87750f5594c315f6f6966e581d3d4ec2 /doc | |
parent | malloc.h should be included via stdlib.h (diff) | |
download | slibc-2c0185df759cf77052f5a0374d680046bcb5db5c.tar.gz slibc-2c0185df759cf77052f5a0374d680046bcb5db5c.tar.bz2 slibc-2c0185df759cf77052f5a0374d680046bcb5db5c.tar.xz |
info: malloc
Signed-off-by: Mattias Andrée <maandree@operamail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/info/chap/memory-allocation.texinfo | 140 |
1 files changed, 139 insertions, 1 deletions
diff --git a/doc/info/chap/memory-allocation.texinfo b/doc/info/chap/memory-allocation.texinfo index 768c823..74af0d5 100644 --- a/doc/info/chap/memory-allocation.texinfo +++ b/doc/info/chap/memory-allocation.texinfo @@ -340,7 +340,145 @@ Uses a faster memory allocation mechanism. @node Basic memory allocation @section Basic memory allocation -TODO +@cpindex Dynamic allocation +@fnindex malloc +@hfindex malloc.h +@hfindex stdlib.h +@code{malloc} is the most general, and most commonly +used memory allocation facility. It is also the most +portable, and is available on all environments. There +are three important function that were introduced in +@sc{ANSI}@tie{}C. These are defined in @file{<malloc.h>}, +however, they should be included via @file{<stdlib.h>} +whihc includes @file{<malloc.h>}. + +@table @code +@item void* malloc(size_t size) +@fnindex malloc +@cpindex Memory allocation without initialisation +@cpindex Initialised memory allocation +Allocates a contiguous memory block of @code{size} +bytes of usuable memory, and returns a pointer +to the beginning of the usable part of the allocation. +The function allocates some extra memory for internal +bookkeeping, this part of the allocation is located +before the address the returned pointer points. +Allocated memory is uninitialised. + +If the memory cannot be allocated (due to memory +exhaustion,) @code{NULL} is returned and @code{errno} +is set to @code{ENOMEM}. + +It is implementation defined whether this function +returns @code{NULL} or a unique pointer if +@code{size} is zero. In @code{slibc}, @code{NULL} +is returned. + +The allocation be grown or shrinked at any time. +See @ref{Resizing memory allocations}. + +In @sc{ISO}@tie{}C, @code{void*} can be implicitly +casted to any other pointer type. Therefore it +is sufficient (and preferable) to write +@example +int* ten_integers = malloc(10 * sizeof(int)); +@end example +You do not need to write +@example +int* ten_integers = (int*)malloc(10 * sizeof(int)); +@end example + +@item void* calloc(size_t count, size_t size) +@fnindex calloc +@cpindex Memory allocation without uninitialisation +@cpindex Uninitialised memory allocation +This function is similar to @code{malloc}, but +it initialises the memory to zeroes. The only +other difference is that it as two parameters +rather than one. + +If @code{count * size} would overflow, @code{NULL} +is returned and @code{errno} is set to @code{ENOMEM}. +Otherwise, @code{p = calloc(a, b)} is identical to +@example +p = malloc(a * b); +memset(p, 0, a * b); +@end example + +@item void free(void* ptr) +@fnindex free +@cpindex Deallocate memory +@cpindex Memory, deallocation +Memory that is dynamically allocated (without +automatic deallocation) can be deallocated with +this function. It is required that @code{ptr} +is the pointer returned by the function that +allocated it. It must not have been incremented. +Undefined behaviour is invoked otherwise. One +exception is @code{NULL}, if @code{ptr} is +@code{NULL} nothing happens. + +Do not try to free a pointer twice, undefined +behaviour. Neither should you try to pass +pointers to variables to this function, nor +pointers to functions, arrays, @code{main}'s +parameters, memory-mapped I/O, or memory allocate +with @code{alloca}. Function-like macros that allocate +memory with @code{alloca}@footnote{There functions +that will return pointers allocate with @code{alloca}, +because the memory would be deallocated at the +return. Thus, such facilities are implemented as +function-like macros.} specifies so, and their +name typically end with an `a', which is not too +common for other functions. + +Be also cautious of whether functions return +statically allocated arrays, which must not +be deallocated, or dynamically allocated +memory, which should be deallocated to avoid +memory leaks. +@end table + +@file{<malloc.h>} also includes three unportable +functions. +@table @code +@item void* zalloc(size_t size) +@fnindex zalloc +This function is similar to @code{calloc}, but it +only has one parameter. Assuming @code{a} and +@code{b} are two @code{size_t}:s, and @code{a * b} +does not overflow, @code{calloc(a, b)} is identical +to @code{zalloc(a * b)}. @code{zalloc} is a +@command{klibc} extension. + +@item void cfree(void* ptr, ...) +@fnindex cfree +This function is an obsolete function provided +by a number of C standard library implementations. +It has been replaced by @code{free}. @code{cfree} +is identical to @code{free}. + +Different implementions @command{libc}, defined +@code{cfree} with different numbers of parameters, +therefore @code{slibc} declares @code{cfree} as +a variadic function, and ignores all but the first +argument. + +@item size_t malloc_usable_size(void* ptr) +@fnindex malloc_usable_sizew +@cpindex Retrieve allocation size +@cpindex Allocation size, retrieve +This function returns the number of usable bytes +for a pointer. If @code{ptr} is @code{NULL}, zero +is returned. It has the same restrictions as the +function @code{free}. + +@code{malloc_usable_size(malloc(n))} returns +@code{n} (and allocates memory in the process.) + +This function is a GNU extension and requires +@code{_GNU_SOURCE}. +@end table |