diff options
author | Bruno Haible <bruno@clisp.org> | 2009-02-22 01:51:42 +0100 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2009-02-22 01:51:42 +0100 |
commit | bdec3e410196c242757abb0a130dd929e6375615 (patch) | |
tree | ba8b129453dec6a43fa199b18c7fafce1179a3eb /doc/safe-alloc.texi | |
parent | df70a4bf4a1e84171918db09b639ae1a14c2a9b2 (diff) | |
download | gnulib-bdec3e410196c242757abb0a130dd929e6375615.tar.gz |
Cosmetic tweaks in the safe-alloc module.
Diffstat (limited to 'doc/safe-alloc.texi')
-rw-r--r-- | doc/safe-alloc.texi | 52 |
1 files changed, 26 insertions, 26 deletions
diff --git a/doc/safe-alloc.texi b/doc/safe-alloc.texi index bd398907ee..9b7de06a56 100644 --- a/doc/safe-alloc.texi +++ b/doc/safe-alloc.texi @@ -2,8 +2,8 @@ @section Safe Allocation Macros The standard C library malloc/realloc/calloc/free APIs are prone to a -number of common coding errors. The @code{safe-alloc} module provides -macros that make it easier to avoid many of them. It still uses the +number of common coding errors. The @code{safe-alloc} module provides +macros that make it easier to avoid many of them. It still uses the standard C allocation functions behind the scenes. Some of the memory allocation mistakes that are commonly made are @@ -11,72 +11,72 @@ Some of the memory allocation mistakes that are commonly made are @itemize @bullet @item passing the incorrect number of bytes to @code{malloc}, especially -when allocationg an array +when allocating an array, @item fail to check the return value of @code{malloc} and @code{realloc} for -errors +errors, @item -forget to fully initialize memory just allocated with @code{malloc} +forget to fully initialize memory just allocated with @code{malloc}, @item duplicate calls to @code{free} by forgetting to set the pointer -variable to @code{NULL} +variable to @code{NULL}, @item -leaking memory in calls to @code{realloc} when that call fails +leaking memory in calls to @code{realloc} when that call fails. @end itemize The @code{safe-alloc} module addresses these problems in the following way: @itemize @bullet @item -Define macros that wrap around the standard C allocation -functions. That makes it possible to use the compiler's knowledge of +It defines macros that wrap around the standard C allocation +functions. That makes it possible to use the compiler's knowledge of the size of objects for allocation; it also allows setting pointers -passed in as arguments when appropriate +passed in as arguments when appropriate. @item -Use return values only for a success/fail error condition flag, -and annotate them with GCC's @code{__warn_unused_result__} +It uses return values only for a success/failure error condition flag, +and annotates them with GCC's @code{__warn_unused_result__} attribute. @item -Use @code{calloc} in favor of @code{malloc} +It uses @code{calloc} instead of @code{malloc}. @end itemize @defmac {int} ALLOC (ptr) @findex ALLOC Allocate @code{sizeof(*ptr)} bytes of memory and store the address of -allocated memory in @code{ptr}. Fill the newly allocated memory with +allocated memory in @code{ptr}. Fill the newly allocated memory with zeros. Returns -1 on failure, 0 on success. @end defmac -@defmac {int} ALLOC_N(ptr, count) +@defmac {int} ALLOC_N (ptr, count) @findex ALLOC_N Allocate an array of @code{count} elements, each @code{sizeof(*ptr)} -bytes long and store the address of allocated memory in -@code{ptr}. Fill the newly allocated memory with zeros. +bytes long, and store the address of allocated memory in +@code{ptr}. Fill the newly allocated memory with zeros. Returns -1 on failure, 0 on success. @end defmac -@defmac {int} ALLOC_N_UNINITIALIZED(ptr, count) +@defmac {int} ALLOC_N_UNINITIALIZED (ptr, count) @findex ALLOC_N_UNINITIALIZED Allocate an array of @code{count} elements, each @code{sizeof(*ptr)} -bytes long and store the address of allocated memory in -@code{ptr}. The allocated memory is not initialized. +bytes long, and store the address of allocated memory in +@code{ptr}. The allocated memory is not initialized. Returns -1 on failure, 0 on success. @end defmac -@defmac {int} REALLOC_N(ptr, count) +@defmac {int} REALLOC_N (ptr, count) @findex REALLOC_N -Reallocate the memory pointedto by @code{ptr} to be big enough to hold -at least @code{count} elements, each @code{sizeof(*ptr)} bytes long -and store the address of allocated memory in @code{ptr}. If -reallocation fails, the @code{ptr} is not modified. +Reallocate the memory pointed to by @code{ptr} to be big enough to hold +at least @code{count} elements, each @code{sizeof(*ptr)} bytes long, +and store the address of allocated memory in @code{ptr}. If +reallocation fails, the @code{ptr} variable is not modified. Returns -1 on failure, 0 on success. @end defmac -@defmac {void} FREE(ptr) +@defmac {void} FREE (ptr) @findex FREE Free the memory stored in @code{ptr} and set @code{ptr} to @code{NULL}. |