malloc man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

MALLOC(3)		 BSD Library Functions Manual		     MALLOC(3)

NAME
     malloc, calloc, realloc, reallocf, free, — general purpose memory alloca‐
     tion functions

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <stdlib.h>

     void *
     malloc(size_t size);

     void *
     calloc(size_t number, size_t size);

     void *
     realloc(void *ptr, size_t size);

     void *
     reallocf(void *ptr, size_t size);

     void
     free(void *ptr);

DESCRIPTION
     The malloc() function allocates size bytes of uninitialized memory.  The
     allocated space is suitably aligned (after possible pointer coercion) for
     storage of any type of object.  If the space is at least pagesize bytes
     in length (see getpagesize(3)), the returned memory will be page boundary
     aligned as well.

     The calloc() function allocates space for number objects, each size bytes
     in length.	 The result is identical to calling malloc() with an argument
     of “number * size”, with the exception that the allocated memory is
     explicitly initialized to zero bytes.

     The realloc() function changes the size of the previously allocated mem‐
     ory referenced by ptr to 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 unde‐
     fined.  Upon success, the memory referenced by ptr is freed and a pointer
     to the newly allocated memory is returned.	 Note that realloc() may move
     the memory allocation, resulting in a different return value than ptr.
     If ptr is NULL, the realloc() function behaves identically to malloc()
     for the specified size.

     The reallocf() function call is identical to the realloc function call,
     except that it will free the passed pointer when the requested memory
     cannot be allocated.  This is a FreeBSD / DragonFly specific API designed
     to ease the problems with traditional coding styles for realloc causing
     memory leaks in libraries.

     The free() function causes the allocated memory referenced by ptr to be
     made available for future allocations.  If ptr is NULL, no action occurs.

IMPLEMENTATION NOTES
     DragonFly's malloc implementation is based on a port of the DragonFly
     kernel slab allocator, appropriately modified for a user process environ‐
     ment.

     The slab allocator breaks memory allocations up to 8KB into 80 zones.
     Each zone represents a fixed allocation size in multiples of some core
     chunking.	The chunking is a power-of-2 but the fixed allocation size is
     not.  For example, a 1025-byte request is allocated out of the zone with
     a chunking of 128, thus in multiples of 1152 bytes.  The minimum chunk‐
     ing, used for allocations in the 0-127 byte range, is 8 bytes (16 of the
     80 zones).	 Beyond that the power-of-2 chunking is between 1/8 and 1/16
     of the minimum allocation size for any given zone.

     As a special case any power-of-2-sized allocation within the zone limit
     (8K) will be aligned to the same power-of-2 rather than that zone's
     (smaller) chunking.  This is not something you can depend upon for
     malloc(), but it is used internally to optimize posix_memalign(3).

     Each zone reserves memory in 64KB blocks.	Actual memory use tends to be
     significantly less as only the pages actually needed are faulted in.
     Allocations larger than 8K are managed using mmap(2) and tracked with a
     hash table.

     The zone mechanism results in well-fitted allocations with little waste
     in a long-running environment which makes a lot of allocations.  Short-
     running environments which do not make many allocations will see a bit of
     extra bloat due to the large number of zones but it will be almost unno‐
     ticeable in the grand scheme of things.  To reduce bloat further the nor‐
     mal randomized start offset implemented in the kernel version of the
     allocator to improve L1 cache fill is disabled in the libc version.

     The zone mechanism also has the nice side effect of greatly reducing
     fragmentation over the original malloc.

     calloc() is directly supported by keeping track of newly-allocated zones
     which will be demand-zero'd by the system.	 If the allocation is known to
     be zero'd we do not bother bzero()ing it.	If it is a reused allocation
     we bzero().

     POSIX threading is supported by duplicating the primary structure.	 A
     thread entering malloc() which is unable to immediately acquire a mutex
     on the last primary structure it used will switch to a different primary
     structure.	 At the moment this is more of a quick hack than a solution,
     but it works.

RETURN VALUES
     The malloc() and calloc() functions return a pointer to the allocated
     memory if successful; otherwise a NULL pointer is returned and errno is
     set to ENOMEM.

     The realloc() and reallocf() functions return a pointer, possibly identi‐
     cal to ptr, to the allocated memory if successful; otherwise a NULL
     pointer is returned, and errno is set to ENOMEM if the error was the
     result of an allocation failure.  The realloc() function always leaves
     the original buffer intact when an error occurs, whereas reallocf() deal‐
     locates it in this case.

     The free() function returns no value.

EXAMPLES
     When using malloc(), be careful to avoid the following idiom:

	   if ((p = malloc(number * size)) == NULL)
		   err(EXIT_FAILURE, "malloc");

     The multiplication may lead to an integer overflow.  To avoid this,
     calloc() is recommended.

     If malloc() must be used, be sure to test for overflow:

	   if (size && number > SIZE_MAX / size) {
		   errno = EOVERFLOW;
		   err(EXIT_FAILURE, "allocation");
	   }

     When using realloc(), one must be careful to avoid the following idiom:

	   nsize += 50;

	   if ((p = realloc(p, nsize)) == NULL)
		   return NULL;

     Do not adjust the variable describing how much memory has been allocated
     until it is known that the allocation has been successful.	 This can
     cause aberrant program behavior if the incorrect size value is used.  In
     most cases, the above example will also leak memory.  As stated earlier,
     a return value of NULL indicates that the old object still remains allo‐
     cated.  Better code looks like this:

	   newsize = size + 50;

	   if ((p2 = realloc(p, newsize)) == NULL) {

		   if (p != NULL)
			   free(p);

		   p = NULL;
		   return NULL;
	   }

	   p = p2;
	   size = newsize;

DIAGNOSTICS
     If malloc(), calloc(), realloc() or free() detect an error, a message
     will be printed to file descriptor STDERR_FILENO and the process will
     dump core.

SEE ALSO
     madvise(2), mmap(2), sbrk(2), alloca(3), atexit(3), getpagesize(3),
     memory(3), posix_memalign(3)

STANDARDS
     The malloc(), calloc(), realloc() and free() functions conform to ISO/IEC
     9899:1990 (“ISO C90”).

HISTORY
     The reallocf() function first appeared in FreeBSD 3.0.

     DragonFly's malloc implementation is based on the kernel's slab allocator
     (see posix_memalign(3)'s IMPLEMENTATION NOTES).  It first appeared in
     DragonFly 2.3.

AUTHORS
     Matt Dillon

BSD				 May 21, 2010				   BSD
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net