malloc(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

malloc(3c)

Standard C Library Functions                                        malloc(3C)



NAME
       malloc,  calloc,  memalign,  realloc,  reallocarray,  reallocf, valloc,
       free, freezero, freezeroall, malloc_usable_size - memory allocator

SYNOPSIS
       #include <stdlib.h>

       void *malloc(size_t size);


       void *calloc(size_t nelem, size_t elsize);


       void *memalign(size_t alignment, size_t size);


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


       void *reallocarray(void *ptr, size_t nelem, size_t elsize);


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


       void *valloc(size_t size);


       size_t malloc_usable_size(void *ptr);


       void free(void *ptr);


       void freezero(void *ptr, size_t size);


       void freezeroall(void *ptr);

DESCRIPTION
       These functions provide a  simple,  general-purpose  memory  allocation
       package.  If  the  space assigned by any of the memory allocation func‐
       tions is overrun, the results are undefined, except as noted in the ADI
       INTERACTION section.


       The  malloc() function allocates and returns a pointer to a block of at
       least size bytes suitably aligned for any use. The initial contents  of
       the memory in this block are unspecified.


       The calloc() function allocates space for an array of nelem elements of
       size elsize and returns a pointer to the allocated block. The space  is
       initialized to zeros.


       The  memalign()  function allocates size bytes on a specified alignment
       boundary and returns a pointer to the allocated block. The value of the
       returned address is guaranteed to be an even multiple of alignment. The
       value of alignment must be a power of two and must be greater  than  or
       equal to the size of a word.


       The  realloc() function changes the size of the block pointed to by ptr
       to size bytes and returns a pointer to the (possibly moved) block.  The
       contents  will  be unchanged up to the lesser of the new and old sizes.
       If the new size of the block requires movement of the block, the  space
       for  the  previous instantiation of the block is freed. If the new size
       is larger, the contents of the newly allocated portion of the block are
       unspecified.  If  size is 0, the space pointed to by ptr is freed and a
       newly allocated block is returned, as if by a call to malloc(0). If ptr
       is NULL, realloc() behaves like malloc() for the specified size.


       The  reallocarray() function behaves like realloc() except that the new
       size of the allocation will be large enough for an array of nelem  ele‐
       ments  of  size elsize. If padding is necessary to ensure proper align‐
       ment of entries in the array, the caller is responsible  for  including
       that in the elsize parameter.


       The  reallocf()  function behaves like realloc() except that if alloca‐
       tion fails, the block pointed to by ptr will be freed.


       The valloc() function has the same effect as malloc(), except that  the
       allocated memory will be aligned to a multiple of the value returned by
       sysconf(_SC_PAGESIZE).


       The argument to free() is a pointer to a block previously allocated  by
       one  of  these  memory  allocation functions. After free() is executed,
       this space is made available for further allocation by the application.
       Memory  might  not  be  returned to the system until termination of the
       application. If ptr is a null pointer, no action occurs. If ptr is  not
       a  null  pointer,  and  not a value previously returned by one of these
       memory allocation functions, or if the same non-null  value  is  passed
       more than once per allocation, the results are undefined.


       The  malloc_usable_size() function returns the number of bytes of allo‐
       cated memory in a block at ptr that was allocated by one of these  mem‐
       ory  allocation  functions  and  which has not yet been freed. The size
       returned may be larger than the original size  requested,  though  pro‐
       grams  should  not rely on being able to use more bytes than originally
       requested. This will not include the size of any  internal  bookkeeping
       data, red zones, or other memory that the program cannot safely read or
       write as part of this block. If ptr is a null pointer, 0  is  returned.
       If  ptr  is  not a null pointer, and not a value previously returned by
       one of these memory allocation functions that has not yet  been  freed,
       the  results are undefined - the function may return 0 and set errno to
       EINVAL if it successfully detects an invalid pointer,  but  it  is  not
       guaranteed  to  detect  all possible invalid pointers and may return an
       incorrect size or cause a program fault.


       The freezero() and freezeroall() functions overwrite  the  contents  of
       the memory buffer with zeros before passing it to free(), if ptr is not
       NULL. freezero() writes zeros up to  the  provided  size  or  the  size
       returned  by  malloc_usable_size(), whichever is smaller. freezeroall()
       writes zeros for the entire size returned by malloc_usable_size().

ADI INTERACTION
       On Oracle SPARC systems with support for the Application Data Integrity
       (ADI) feature the default set of malloc() functions support the ADIHEAP
       security extension. When the ADIHEAP security extension is enabled  for
       the  calling program, malloc() and related functions will use the SPARC
       Application Data Integrity APIs to provide detection  of  buffer  over‐
       runs,  out of bounds pointers, use after free errors, use after reallo‐
       cation errors, and stale pointer errors. For more information, see  the
       adi(7) and sxadm(8) manual pages.


       By  default,  when  ADIHEAP is enabled, ADI version mismatches on store
       instructions produce a disrupting trap, which means that the associated
       SIGSEGV  signal  may be delivered some number of instructions after the
       offending store, and that may make it more difficult to debug some pro‐
       grams.  To  force  a  precise  trap for ADI version mismatches on store
       instructions, set the environment variable _LIBC_ADI_PRECISE. The value
       to  which it is set is irrelevant; what matters is the existence of the
       environment variable. Setting _LIBC_ADI_PRECISE might  have  a  perfor‐
       mance impact; the magnitude of the impact depends on the percentage and
       pattern of the store instructions in the program. Because of  that,  it
       is  recommended  that  _LIBC_ADI_PRECISE be set only for debugging pur‐
       poses.


       ADI version mismatches on load instructions always  produce  a  precise
       trap, with no additional impact on performance.

RETURN VALUES
       Upon  successful completion, each of the allocation functions returns a
       pointer to space suitably aligned (after possible pointer coercion) for
       storage of any type of object.


       If  size,  nelem,  or elsize is 0, the allocation functions, except for
       memalign() and valloc(), return a unique non-null pointer that  can  be
       passed  to free(). These pointers should not be dereferenced. The mema‐
       lign() and valloc() functions return null pointers when the size param‐
       eter is 0.


       If  there  is  not  enough  memory  available, the allocation functions
       return a null pointer and set errno.


       When realloc() or reallocarray() return NULL, the block pointed  to  by
       ptr  is  left intact. If size, nelem, or elsize is 0, the block pointed
       to by ptr is freed, and a unique pointer that can be passed  to  free()
       is returned.


       If  one  of the allocation functions returns unsuccessfully, errno will
       be set to indicate the error. The free() function does not set errno.


       The malloc_usable_size() function returns a size (which may  be  0)  on
       success,  and 0 on failure. In the event of failure, errno will also be
       set.

ERRORS
       The memory allocation functions will fail if:

       ENOMEM    The limits of the system are exceeded by the requested amount
                 of memory, which cannot be allocated.


       EAGAIN    There is not enough memory available at this point in time to
                 allocate the requested amount of memory; but the  application
                 could try again later.



       The calloc() and reallocarray() functions will also fail if:

       ENOMEM    The  multiplication  of the nelem and elsize parameters would
                 lead to an integer overflow.



       The memalign() function may also fail if:

       EINVAL    The value of the alignment parameter is not a  power  of  two
                 multiple of sizeof(void *), or the size parameter is zero, or
                 the combination of the two would lead to an integer overflow.



       The valloc() function may also fail if:

       EINVAL    The size parameter, when aligned to the pagesize, would  lead
                 to an integer overflow.



       The malloc_usable_size() function may fail if:

       EINVAL    The  pointer  provided is not a valid pointer returned by one
                 of the memory allocation functions described on this page.


USAGE
       Portable applications should avoid using valloc()  but  should  instead
       use  posix_memalign(3C)  or mmap(2). On systems with a large page size,
       the number of successful valloc() operations might be 0.


       Memory allocated by these functions may be on pages with the  PROT_EXEC
       access protections disabled to block execution of machine instructions,
       depending on the system settings for NXHEAP  in  sxadm(8)  and  any  -z
       sx=nxheap  options  that were passed to ld(1) when linking the applica‐
       tion. These settings may be overridden for individual pages by  calling
       mprotect(2).


       These  default  memory  allocation  routines are safe for use in multi‐
       threaded applications but are not scalable. Concurrent accesses by mul‐
       tiple  threads  are  single-threaded  through the use of a single lock.
       Multithreaded applications that make heavy use of dynamic memory  allo‐
       cation  should be linked with allocation libraries designed for concur‐
       rent access, such as libumem(3LIB) or  libmtmalloc(3LIB).  Applications
       that  want  to  avoid using heap allocations (with brk(2)) can do so by
       using  either  libumem(3LIB)  or  libmapmalloc(3LIB).  The   allocation
       libraries libmalloc(3LIB) and libbsdmalloc(3LIB) are available for spe‐
       cial needs. Further comparative  features  of  the  various  allocation
       libraries  can  be  found  in  the  ALTERNATIVE IMPLEMENTATIONS section
       below.


       Mixing multiple memory allocation libraries in a single program is  not
       expected  to  work  well. Passing a pointer allocated by one library to
       the free(), realloc(), or malloc_usable_size() functions  from  another
       library  is  undefined,  and  may  cause  memory  corruption or program
       faults.

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE  TYPEAT‐
       TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe _ Standard‐
       See below.



       See standards(7) for descriptions of the following standards:


       tab() box; cw(2.2i) |cw(3.3i) lw(2.2i)  |lw(3.3i)  INTERFACESAPPLICABLE
       STANDARDS _ T{
         malloc()
         calloc()
         realloc()
         free()

       T}T{
         C89 through C11,
         POSIX.1-1990 through 2008,
         SUS through SUSv4,
         XPG1 through XPG7

       T} _
         valloc()
       T{
         SUS through SUSv2,
         XPG4v2 through XPG5

       T} _ T{
         freezero()
         freezeroall()
         malloc_usable_size()
         memalign()
         reallocarray()
         reallocf()

       T} None


SEE ALSO
       brk(2),  getrlimit(2),  mprotect(2),  adi(3C),  alloca(3C), posix_mema‐
       lign(3C),  libadimalloc(3LIB),   libbsdmalloc(3LIB),   libmalloc(3LIB),
       libmapmalloc(3LIB),  libmtmalloc(3LIB), libumem(3LIB), umem_alloc(3MAL‐
       LOC),  watchmalloc(3MALLOC),   adi(7),   attributes(7),   standards(7),
       sxadm(8)

WARNINGS
       Undefined  results will occur if the size requested for a block of mem‐
       ory exceeds the maximum size of a process's heap, which can be obtained
       with getrlimit(2).

ALTERNATIVE IMPLEMENTATIONS
       The  functions  described  in this page are all exported from libc.so.1
       with the NODIRECT flag to prevent direct bindings and allow easy inter‐
       position  of  alternative implementations, either by linking to another
       library or by using the LD_PRELOAD functionality of the runtime linker,
       ld.so.1(1).  Alternative  implementations  cannot be dynamically loaded
       with dlopen(3C) during runtime because there must be only  one  manager
       of the process heap.


       Oracle  Solaris  includes  a number of alternative implementations with
       different characteristics that make them suitable for usage in  various
       scenarios.  The following list compares the features of the malloc(3C),
       bsdmalloc(3MALLOC),   libadimalloc(3LIB),   malloc(3MALLOC),    mapmal‐
       loc(3MALLOC),  mtmalloc(3MALLOC),  libumem(3LIB), and watchmalloc(3MAL‐
       LOC), libraries.

           o      The default malloc(3C) and malloc(3MALLOC) functions  use  a
                  single  global lock to ensure that only one thread at a time
                  can allocate memory. The libumem(3LIB),  libadimalloc(3LIB),
                  and  mtmalloc(3MALLOC)  functions support concurrent alloca‐
                  tions. The bsdmalloc(3MALLOC) functions have no support  for
                  concurrency.


           o      The  bsdmalloc(3MALLOC)  functions afford better performance
                  but are space-inefficient and  not  thread-safe.  They  also
                  maintain  compatibility  with  historical semantics from the
                  BSD environment of SunOS 4 releases.


           o      The malloc(3MALLOC) functions are space-efficient  but  have
                  slower performance.


           o      The  default  malloc(3C)  functions  are a trade-off between
                  performance and space-efficiency.


           o      The mtmalloc(3MALLOC)  functions  provide  fast,  concurrent
                  malloc() implementations that are not space-efficient.


           o      The libumem(3LIB) functions provide a fast, concurrent allo‐
                  cation implementation that in most cases is more space-effi‐
                  cient than mtmalloc(3MALLOC).


           o      The  libumem(3LIB),  libadimalloc(3LIB),  mtmalloc(3MALLOC),
                  and watchmalloc(3MALLOC) libraries provide  additional  sup‐
                  port for debugging memory allocation problems.


           o      The  default  malloc(3C)  functions, the libumem(3LIB) func‐
                  tions, and the libadimalloc(3LIB) functions offer the option
                  to  provide  detection  of  buffer  overruns,  out of bounds
                  pointers, stale pointers, and use after  free  errors  using
                  the  SPARC  Application  Data Integrity (ADI) feature. These
                  are enabled by default in  libadimalloc,  while  the  others
                  only use these features if the ADIHEAP security extension is
                  enabled as described above. Using these features reduces the
                  space  efficiency  of  allocations with these libraries, and
                  may affect application performance.


           o      Most of these implementations use heap  allocations  managed
                  with  the  brk(2)  system call. The libmapmalloc(3LIB) func‐
                  tions instead use mmap(2)  to  reserve  memory  to  allocate
                  blocks  from,  allowing applications to use brk(2) for their
                  own  purposes.  libumem(3LIB)  allocates  heap   memory   by
                  default,  but  offers  an  option to use mmap(2) instead, as
                  described in the umem_alloc(3MALLOC) manual page.



       When implementing an alternative implementation of these functions  for
       general  use  by other software, a library must provide at least all of
       the following:
         calloc()
         free()
         malloc()
         malloc_usable_size()
         memalign()
         realloc()


       Replacements for the following may be optionally provided:
         freezero()
         freezeroall()
         reallocarray()
         reallocf()
         valloc()


       If replacements  are  not  provided,  the  default  implementations  of
       freezero(),  freezeroall(),  reallocarray(),  reallocf(),  and valloc()
       will call the free(), malloc_usable_size(), realloc(),  and  memalign()
       functions provided by the active allocation library.


       Replacements for the functions aligned_alloc(3C) and posix_memalign(3C)
       should not be provided by alternative implementations. These  functions
       are  provided by libc(3LIB), and call the memalign() and malloc() func‐
       tions provided by the active allocation  library.  They  are  therefore
       compatible  with all alternative malloc implementations that fully sup‐
       port those functions.


       Additional functions may be required in the future as APIs evolve.

HISTORY
       The malloc(), calloc(), memalign(),  realloc(),  valloc(),  and  free()
       functions have been included in all releases of SunOS and Solaris.


       The  malloc_usable_size() function was defined in GNU libc 2.0, and was
       added to Oracle Solaris in the Oracle Solaris 11.4.10 release.


       The reallocarray() function was defined in OpenBSD 5.6, and  was  added
       to Oracle Solaris in the Oracle Solaris 11.4.10 release.


       The  reallocf()  function  was defined in FreeBSD 3.0, and was added to
       Oracle Solaris in the Oracle Solaris 11.4.12 release.


       The freezero() function was defined in OpenBSD 6.2, and  was  added  to
       Oracle Solaris in the Oracle Solaris 11.4.42 release.


       The freezeroall() function was introduced in the Oracle Solaris 11.4.42
       release.



Oracle Solaris 11.4               21 Oct 2021                       malloc(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3