Previous | Table of Contents | Next |
The header <stdlib.h> defines several basic functions for allocating memory, converting strings to numbers, manipulating multibyte characters, and so on.
3.10.4.1. Memory Allocation
malloc, calloc
void *malloc(size_t n) void *calloc(size_t n, size_t elsize)
malloc attempts to allocate n bytes of dynamically allocated memory. If successful, it returns a pointer to this memory; if unsuccessful, it returns a null pointer. The pointer (and hence the allocated block of memory) is suitably aligned so that it may be used for storing any kind of data. Because the return type is void *, no cast is required when assigning the return value to a pointer variable of object pointer type:
double *dp = malloc(10 * sizeof(double));
calloc(n, elsize) is equivalent to malloc(n * elsize) followed by a call to memset(p, 0, n * elsize), where p is the pointer returned by malloc (if non-null). That is, calloc initializes the newly allocated memory to all-bits-zero. (Notice that this initialization guarantees a 0 data value only for integers and characters, not necessarily for pointer or floating-point types.)
free
void free(void *p)
free accepts a pointer p, previously allocated by malloc, calloc, or realloc, and returns the formerly allocated block of memory to the free pool, where it will be available to future allocation requests by the calling program. (Note that the memory is typically not returned to the operating system immediately or otherwise made available to other programs.)
realloc
void *realloc(void *oldptr, size_t newsize)
realloc accepts a pointer oldptr to a block of memory previously allocated by malloc, calloc, or realloc, and attempts to reallocate the block to have the size newsize. If realloc is able to adjust the allocation of the existing block in place (for example, if memory following the block, out to newsize, is unused), the new allocation is simply recorded and realloc returns the original pointer, oldptr. If the block cannot be reallocated in place, realloc attempts to allocate a new block of size newsize elsewhere. If it succeeds, it copies the contents of the old block to the new (as if with memcpy), frees the old block, and returns a pointer to the new block. Otherwise, the reallocation is impossible, and realloc indicates this by returning a null pointer (in which case oldptr remains valid, albeit pointing to the old block).
As special cases, realloc(p, 0) is equivalent to free(p), and realloc(0, n) (that is, an attempt to reallocate the null pointer) is equivalent to malloc(n).
Because realloc may relocate the block, it is important that the caller update any and all pointers that point anywhere within the block. Since a null return from realloc may leave oldptr valid, it is important not to assign reallocs return value immediately back to the same pointer that was passed as oldptr. Here is a contrived example illustrating both of these points:
#include <stddef.h> /* for ptrdiff_t */ #include <stdio.h> /* for printf */ #include <stdlib.h> /* for malloc and realloc */ #include <string.h> /* for strstr */ ptrdiff_t p2off; char *p = malloc(14), *p2, *newp; if(p != NULL) { strcpy(p, Hello, world!); p2 = strstr(p, world); p2off = p2 - p; newp = realloc(p, 20); if(newp != NULL) { p = newp; p2 = p + p2off; } printf(%.5s, %s\n, p, p2); }
Notice the use of the variable p2off, which enables recomputation of p2 if the base pointer p is relocated. (The type ptrdiff_t is defined in <stddef.h>; see section 3.10.11.)
3.10.4.2. Converting Strings to Numbers
atoi, atol, strtol, strtoul
int atoi(const char *s) long int atol(const char *s) long int strtol(const char *s, char **endp, int base) unsigned long int strtoul(const char *s, char **endp, int base)
These functions convert numeric strings to the corresponding integers.
The most general function is strtol. It skips over any leading whitespace, honors a leading sign character (- or +), and then converts a string of digits representing a number in the requested base. If base is less than 10, only digits from 0 to base-1 are accepted. If base is greater than 10, appropriate letters in the sets az or AZ are also accepted. If base is 0, strtol infers a base by following the rule for C integer constants: base 16 if the string (sans whitespace and sign) begins with 0x or 0X; otherwise base 8 if it begins with 0; otherwise base 10. If base is exactly 16, a leading 0x or 0X is also accepted. If endp is non-null, strtol stores into *endp (that is, into the pointed-to pointer) a pointer to the first character in s that it did not consume. The caller can use the returned pointer as follows: If it equals s, no input was consumed and no part of the string s represented a valid number; otherwise, if it points to the character \0, the string was perfectly valid; otherwise, the string began with a valid number, followed by some non-numeric characters (which *endp now points to). The return value is either the converted number, or 0 if no conversion could be performed, or the constants LONG_MAX or LONG_MIN if the number could not be represented in a long int. In the overflow cases, the global errno is set to ERANGE.
strtoul is similar to strtol except that the return value is of type unsigned long int, and the value ULONG_MAX is returned on overflow.
Previous | Table of Contents | Next |