* Memory Concepts:: An introduction to concepts and terminology.
* Memory Allocation:: Allocating storage for your program data
* Resizing the Data Segment:: @code{brk}, @code{sbrk}
+* Memory Protection:: Controlling access to memory regions.
* Locking Pages:: Preventing page faults
@end menu
@menu
* Memory Allocation and C:: How to get different kinds of allocation in C.
+* The GNU Allocator:: An overview of the GNU @code{malloc}
+ implementation.
* Unconstrained Allocation:: The @code{malloc} facility allows fully general
dynamic allocation.
* Allocation Debugging:: Finding memory leaks and not freed memory.
+* Replacing malloc:: Using your own @code{malloc}-style allocator.
* Obstacks:: Obstacks are less general than malloc
but more efficient and convenient.
* Variable Size Automatic:: Allocation of variable-sized blocks
@}
@end smallexample
+@node The GNU Allocator
+@subsection The GNU Allocator
+@cindex gnu allocator
+
+The @code{malloc} implementation in @theglibc{} is derived from ptmalloc
+(pthreads malloc), which in turn is derived from dlmalloc (Doug Lea malloc).
+This malloc may allocate memory in two different ways depending on their size
+and certain parameters that may be controlled by users. The most common way is
+to allocate portions of memory (called chunks) from a large contiguous area of
+memory and manage these areas to optimize their use and reduce wastage in the
+form of unusable chunks. Traditionally the system heap was set up to be the one
+large memory area but the @glibcadj{} @code{malloc} implementation maintains
+multiple such areas to optimize their use in multi-threaded applications. Each
+such area is internally referred to as an @dfn{arena}.
+
+As opposed to other versions, the @code{malloc} in @theglibc{} does not round
+up chunk sizes to powers of two, neither for large nor for small sizes.
+Neighboring chunks can be coalesced on a @code{free} no matter what their size
+is. This makes the implementation suitable for all kinds of allocation
+patterns without generally incurring high memory waste through fragmentation.
+The presence of multiple arenas allows multiple threads to allocate
+memory simultaneously in separate arenas, thus improving performance.
+
+The other way of memory allocation is for very large blocks, i.e. much larger
+than a page. These requests are allocated with @code{mmap} (anonymous or via
+@file{/dev/zero}; @pxref{Memory-mapped I/O})). This has the great advantage
+that these chunks are returned to the system immediately when they are freed.
+Therefore, it cannot happen that a large chunk becomes ``locked'' in between
+smaller ones and even after calling @code{free} wastes memory. The size
+threshold for @code{mmap} to be used is dynamic and gets adjusted according to
+allocation patterns of the program. @code{mallopt} can be used to statically
+adjust the threshold using @code{M_MMAP_THRESHOLD} and the use of @code{mmap}
+can be disabled completely with @code{M_MMAP_MAX};
+@pxref{Malloc Tunable Parameters}.
+
+A more detailed technical description of the GNU Allocator is maintained in
+the @glibcadj{} wiki. See
+@uref{https://sourceware.org/glibc/wiki/MallocInternals}.
+
+It is possible to use your own custom @code{malloc} instead of the
+built-in allocator provided by @theglibc{}. @xref{Replacing malloc}.
+
@node Unconstrained Allocation
@subsection Unconstrained Allocation
@cindex unconstrained memory allocation
bigger or smaller.
* Allocating Cleared Space:: Use @code{calloc} to allocate a
block and clear it.
-* Efficiency and Malloc:: Efficiency considerations in use of
- these functions.
* Aligned Memory Blocks:: Allocating specially aligned memory.
* Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation
parameters.
this function is in @file{stdlib.h}.
@pindex stdlib.h
-@comment malloc.h stdlib.h
-@comment ISO
@deftypefun {void *} malloc (size_t @var{size})
+@standards{ISO, malloc.h}
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c Malloc hooks and __morecore pointers, as well as such parameters as
@c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they
@c reads&writes next_to_use and iterates over arena next without guards
@c those are harmless as long as we don't drop arenas from the
@c NEXT list, and we never do; when a thread terminates,
-@c arena_thread_freeres prepends the arena to the free_list
+@c __malloc_arena_thread_freeres prepends the arena to the free_list
@c NEXT_FREE list, but NEXT is never modified, so it's safe!
@c mutex_trylock (arena lock) @asulock @aculock
@c mutex_lock (arena lock) dup @asulock @aculock
The prototype for this function is in @file{stdlib.h}.
@pindex stdlib.h
-@comment malloc.h stdlib.h
-@comment ISO
@deftypefun void free (void *@var{ptr})
+@standards{ISO, malloc.h}
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c __libc_free @asulock @aculock @acsfd @acsmem
@c releasing memory into fastbins modifies the arena without taking
by @var{ptr}.
@end deftypefun
-@comment stdlib.h
-@comment Sun
-@deftypefun void cfree (void *@var{ptr})
-@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
-@c alias to free
-This function does the same thing as @code{free}. It's provided for
-backward compatibility with SunOS; you should use @code{free} instead.
-@end deftypefun
-
Freeing a block alters the contents of the block. @strong{Do not expect to
find any data (such as a pointer to the next block in a chain of blocks) in
the block after freeing it.} Copy whatever you need out of the block before
how long you make the buffer initially, you may encounter a line that is
longer.
-You can make the block longer by calling @code{realloc}. This function
-is declared in @file{stdlib.h}.
+You can make the block longer by calling @code{realloc} or
+@code{reallocarray}. These functions are declared in @file{stdlib.h}.
@pindex stdlib.h
-@comment malloc.h stdlib.h
-@comment ISO
@deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
+@standards{ISO, malloc.h}
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c It may call the implementations of malloc and free, so all of their
@c issues arise, plus the realloc hook, also accessed without guards.
pointer.
@end deftypefun
-Like @code{malloc}, @code{realloc} may return a null pointer if no
-memory space is available to make the block bigger. When this happens,
-the original block is untouched; it has not been modified or relocated.
+@deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
+@standards{BSD, malloc.h}
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+
+The @code{reallocarray} function changes the size of the block whose address
+is @var{ptr} to be long enough to contain a vector of @var{nmemb} elements,
+each of size @var{size}. It is equivalent to @samp{realloc (@var{ptr},
+@var{nmemb} * @var{size})}, except that @code{reallocarray} fails safely if
+the multiplication overflows, by setting @code{errno} to @code{ENOMEM},
+returning a null pointer, and leaving the original block unchanged.
+
+@code{reallocarray} should be used instead of @code{realloc} when the new size
+of the allocated block is the result of a multiplication that might overflow.
+
+@strong{Portability Note:} This function is not part of any standard. It was
+first introduced in OpenBSD 5.6.
+@end deftypefun
+
+Like @code{malloc}, @code{realloc} and @code{reallocarray} may return a null
+pointer if no memory space is available to make the block bigger. When this
+happens, the original block is untouched; it has not been modified or
+relocated.
In most cases it makes no difference what happens to the original block
when @code{realloc} fails, because the application program cannot continue
@}
@end smallexample
-You can also use @code{realloc} to make a block smaller. The reason you
-would do this is to avoid tying up a lot of memory space when only a little
-is needed.
+You can also use @code{realloc} or @code{reallocarray} to make a block
+smaller. The reason you would do this is to avoid tying up a lot of memory
+space when only a little is needed.
@comment The following is no longer true with the new malloc.
@comment But it seems wise to keep the warning for other implementations.
In several allocation implementations, making a block smaller sometimes
necessitates copying it, so it can fail if no other space is available.
-If the new size you specify is the same as the old size, @code{realloc}
-is guaranteed to change nothing and return the same address that you gave.
+If the new size you specify is the same as the old size, @code{realloc} and
+@code{reallocarray} are guaranteed to change nothing and return the same
+address that you gave.
@node Allocating Cleared Space
@subsubsection Allocating Cleared Space
is declared in @file{stdlib.h}.
@pindex stdlib.h
-@comment malloc.h stdlib.h
-@comment ISO
@deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
+@standards{ISO, malloc.h}
+@standards{ISO, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c Same caveats as malloc.
@code{malloc}/@code{realloc}/@code{free} outside the C library, it
should always define @code{calloc}, too.
-@node Efficiency and Malloc
-@subsubsection Efficiency Considerations for @code{malloc}
-@cindex efficiency and @code{malloc}
-
-
-
-
-@ignore
-
-@c No longer true, see below instead.
-To make the best use of @code{malloc}, it helps to know that the GNU
-version of @code{malloc} always dispenses small amounts of memory in
-blocks whose sizes are powers of two. It keeps separate pools for each
-power of two. This holds for sizes up to a page size. Therefore, if
-you are free to choose the size of a small block in order to make
-@code{malloc} more efficient, make it a power of two.
-@c !!! xref getpagesize
-
-Once a page is split up for a particular block size, it can't be reused
-for another size unless all the blocks in it are freed. In many
-programs, this is unlikely to happen. Thus, you can sometimes make a
-program use memory more efficiently by using blocks of the same size for
-many different purposes.
-
-When you ask for memory blocks of a page or larger, @code{malloc} uses a
-different strategy; it rounds the size up to a multiple of a page, and
-it can coalesce and split blocks as needed.
-
-The reason for the two strategies is that it is important to allocate
-and free small blocks as fast as possible, but speed is less important
-for a large block since the program normally spends a fair amount of
-time using it. Also, large blocks are normally fewer in number.
-Therefore, for large blocks, it makes sense to use a method which takes
-more time to minimize the wasted space.
-
-@end ignore
-
-As opposed to other versions, the @code{malloc} in @theglibc{}
-does not round up block sizes to powers of two, neither for large nor
-for small sizes. Neighboring chunks can be coalesced on a @code{free}
-no matter what their size is. This makes the implementation suitable
-for all kinds of allocation patterns without generally incurring high
-memory waste through fragmentation.
-
-Very large blocks (much larger than a page) are allocated with
-@code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
-This has the great advantage that these chunks are returned to the
-system immediately when they are freed. Therefore, it cannot happen
-that a large chunk becomes ``locked'' in between smaller ones and even
-after calling @code{free} wastes memory. The size threshold for
-@code{mmap} to be used can be adjusted with @code{mallopt}. The use of
-@code{mmap} can also be disabled completely.
-
@node Aligned Memory Blocks
@subsubsection Allocating Aligned Memory Blocks
@code{aligned_alloc} and @code{posix_memalign} are declared in
@file{stdlib.h}.
-@comment stdlib.h
@deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
+@standards{???, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c Alias to memalign.
The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
@end deftypefun
-@comment malloc.h
-@comment BSD
@deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
+@standards{BSD, malloc.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c Same issues as malloc. The padding bytes are safely freed in
@c _int_memalign, with the arena still locked.
@code{posix_memalign} should be used instead.
@end deftypefun
-@comment stdlib.h
-@comment POSIX
@deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
+@standards{POSIX, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c Calls memalign unless the requirements are not met (powerof2 macro is
@c safe given an automatic variable as an argument) or there's a
systems that do not support @w{ISO C11}.
@end deftypefun
-@comment malloc.h stdlib.h
-@comment BSD
@deftypefun {void *} valloc (size_t @var{size})
+@standards{BSD, malloc.h}
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{} @acsfd{} @acsmem{}}}
@c __libc_valloc @mtuinit @asuinit @asulock @aculock @acsfd @acsmem
@c ptmalloc_init (once) @mtsenv @asulock @aculock @acsfd @acsmem
@c next_env_entry ok
@c strcspn dup ok
@c __libc_mallopt dup @mtasuconst:mallopt [setting mp_]
-@c __malloc_check_init @mtasuconst:malloc_hooks [setting hooks]
@c *__malloc_initialize_hook unguarded, ok
@c *__memalign_hook dup ok, unguarded
@c arena_get dup @asulock @aculock @acsfd @acsmem
parameter to be set, and @var{value} the new value to be set. Possible
choices for @var{param}, as defined in @file{malloc.h}, are:
-@table @code
-@comment TODO: @item M_ARENA_MAX
-@comment - Document ARENA_MAX env var.
-@comment TODO: @item M_ARENA_TEST
-@comment - Document ARENA_TEST env var.
-@comment TODO: @item M_CHECK_ACTION
+@vtable @code
@item M_MMAP_MAX
The maximum number of chunks to allocate with @code{mmap}. Setting this
to zero disables all use of @code{mmap}.
+
+The default value of this parameter is @code{65536}.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_MMAP_MAX_} to the desired value.
+
@item M_MMAP_THRESHOLD
All chunks larger than this value are allocated outside the normal
heap, using the @code{mmap} system call. This way it is guaranteed
that the memory for these chunks can be returned to the system on
@code{free}. Note that requests smaller than this threshold might still
be allocated via @code{mmap}.
+
+If this parameter is not set, the default value is set as 128 KiB and the
+threshold is adjusted dynamically to suit the allocation patterns of the
+program. If the parameter is set, the dynamic adjustment is disabled and the
+value is set statically to the input value.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_MMAP_THRESHOLD_} to the desired value.
@comment TODO: @item M_MXFAST
+
@item M_PERTURB
If non-zero, memory blocks are filled with values depending on some
low order bits of this parameter when they are allocated (except when
guarantee that the freed block will have any specific values. It only
guarantees that the content the block had before it was freed will be
overwritten.
+
+The default value of this parameter is @code{0}.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_MMAP_PERTURB_} to the desired value.
+
@item M_TOP_PAD
-This parameter determines the amount of extra memory to obtain from the
-system when a call to @code{sbrk} is required. It also specifies the
-number of bytes to retain when shrinking the heap by calling @code{sbrk}
-with a negative argument. This provides the necessary hysteresis in
-heap size such that excessive amounts of system calls can be avoided.
+This parameter determines the amount of extra memory to obtain from the system
+when an arena needs to be extended. It also specifies the number of bytes to
+retain when shrinking an arena. This provides the necessary hysteresis in heap
+size such that excessive amounts of system calls can be avoided.
+
+The default value of this parameter is @code{0}.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_TOP_PAD_} to the desired value.
+
@item M_TRIM_THRESHOLD
This is the minimum size (in bytes) of the top-most, releasable chunk
-that will cause @code{sbrk} to be called with a negative argument in
-order to return memory to the system.
-@end table
+that will trigger a system call in order to return memory to the system.
+
+If this parameter is not set, the default value is set as 128 KiB and the
+threshold is adjusted dynamically to suit the allocation patterns of the
+program. If the parameter is set, the dynamic adjustment is disabled and the
+value is set statically to the provided input.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_TRIM_THRESHOLD_} to the desired value.
+
+@item M_ARENA_TEST
+This parameter specifies the number of arenas that can be created before the
+test on the limit to the number of arenas is conducted. The value is ignored if
+@code{M_ARENA_MAX} is set.
+
+The default value of this parameter is 2 on 32-bit systems and 8 on 64-bit
+systems.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_ARENA_TEST} to the desired value.
+
+@item M_ARENA_MAX
+This parameter sets the number of arenas to use regardless of the number of
+cores in the system.
+
+The default value of this tunable is @code{0}, meaning that the limit on the
+number of arenas is determined by the number of CPU cores online. For 32-bit
+systems the limit is twice the number of cores online and on 64-bit systems, it
+is eight times the number of cores online. Note that the default value is not
+derived from the default value of M_ARENA_TEST and is computed independently.
+
+This parameter can also be set for the process at startup by setting the
+environment variable @env{MALLOC_ARENA_MAX} to the desired value.
+@end vtable
@end deftypefun
declared in @file{mcheck.h}.
@pindex mcheck.h
-@comment mcheck.h
-@comment GNU
@deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
+@standards{GNU, mcheck.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
@c The hooks must be set up before malloc is first used, which sort of
@c implies @mtuinit/@asuinit but since the function is a no-op if malloc
Another possibility to check for and guard against bugs in the use of
@code{malloc}, @code{realloc} and @code{free} is to set the environment
-variable @code{MALLOC_CHECK_}. When @code{MALLOC_CHECK_} is set, a
-special (less efficient) implementation is used which is designed to be
-tolerant against simple errors, such as double calls of @code{free} with
-the same argument, or overruns of a single byte (off-by-one bugs). Not
-all such errors can be protected against, however, and memory leaks can
-result. If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
-corruption is silently ignored; if set to @code{1}, a diagnostic is
-printed on @code{stderr}; if set to @code{2}, @code{abort} is called
-immediately. This can be useful because otherwise a crash may happen
-much later, and the true cause for the problem is then very hard to
-track down.
+variable @code{MALLOC_CHECK_}. When @code{MALLOC_CHECK_} is set to a
+non-zero value, a special (less efficient) implementation is used which
+is designed to be tolerant against simple errors, such as double calls
+of @code{free} with the same argument, or overruns of a single byte
+(off-by-one bugs). Not all such errors can be protected against,
+however, and memory leaks can result.
+
+Any detected heap corruption results in immediate termination of the
+process.
There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
it could possibly be exploited since diverging from the normal programs
The hook variables are declared in @file{malloc.h}.
@pindex malloc.h
-@comment malloc.h
-@comment GNU
@defvar __malloc_hook
+@standards{GNU, malloc.h}
The value of this variable is a pointer to the function that
@code{malloc} uses whenever it is called. You should define this
function to look like @code{malloc}; that is, like:
the memory consumption of the program.
@end defvar
-@comment malloc.h
-@comment GNU
@defvar __realloc_hook
+@standards{GNU, malloc.h}
The value of this variable is a pointer to function that @code{realloc}
uses whenever it is called. You should define this function to look
like @code{realloc}; that is, like:
memory consumption of the program.
@end defvar
-@comment malloc.h
-@comment GNU
@defvar __free_hook
+@standards{GNU, malloc.h}
The value of this variable is a pointer to function that @code{free}
uses whenever it is called. You should define this function to look
like @code{free}; that is, like:
memory consumption of the program.
@end defvar
-@comment malloc.h
-@comment GNU
@defvar __memalign_hook
+@standards{GNU, malloc.h}
The value of this variable is a pointer to function that @code{aligned_alloc},
@code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
are called. You should define this function to look like @code{aligned_alloc};
SVID/XPG version.
@pindex malloc.h
-@comment malloc.h
-@comment GNU
@deftp {Data Type} {struct mallinfo}
+@standards{GNU, malloc.h}
This structure type is used to return information about the dynamic
memory allocator. It contains the following members:
@item int ordblks
This is the number of chunks not in use. (The memory allocator
internally gets chunks of memory from the operating system, and then
-carves them up to satisfy individual @code{malloc} requests; see
-@ref{Efficiency and Malloc}.)
+carves them up to satisfy individual @code{malloc} requests;
+@pxref{The GNU Allocator}.)
@item int smblks
This field is unused.
@end table
@end deftp
-@comment malloc.h
-@comment SVID
@deftypefun {struct mallinfo} mallinfo (void)
+@standards{SVID, malloc.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
@c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics
@c but non-atomically elsewhere, may get us inconsistent results. We
Make a block previously allocated by @code{malloc} larger or smaller,
possibly by copying it to a new location. @xref{Changing Block Size}.
+@item void *reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
+Change the size of a block previously allocated by @code{malloc} to
+@code{@var{nmemb} * @var{size}} bytes as with @code{realloc}. @xref{Changing
+Block Size}.
+
@item void *calloc (size_t @var{count}, size_t @var{eltsize})
Allocate a block of @var{count} * @var{eltsize} bytes using
@code{malloc}, and set its contents to zero. @xref{Allocating Cleared
@node Tracing malloc
@subsubsection How to install the tracing functionality
-@comment mcheck.h
-@comment GNU
@deftypefun void mtrace (void)
+@standards{GNU, mcheck.h}
@safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c Like the mcheck hooks, these are not designed with thread safety in
@c mind, because the hook pointers are temporarily modified without
systems. The prototype can be found in @file{mcheck.h}.
@end deftypefun
-@comment mcheck.h
-@comment GNU
@deftypefun void muntrace (void)
+@standards{GNU, mcheck.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}}
@c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd
times without freeing this memory before the program terminates.
Whether this is a real problem remains to be investigated.
+@node Replacing malloc
+@subsection Replacing @code{malloc}
+
+@cindex @code{malloc} replacement
+@cindex @code{LD_PRELOAD} and @code{malloc}
+@cindex alternative @code{malloc} implementations
+@cindex customizing @code{malloc}
+@cindex interposing @code{malloc}
+@cindex preempting @code{malloc}
+@cindex replacing @code{malloc}
+@Theglibc{} supports replacing the built-in @code{malloc} implementation
+with a different allocator with the same interface. For dynamically
+linked programs, this happens through ELF symbol interposition, either
+using shared object dependencies or @code{LD_PRELOAD}. For static
+linking, the @code{malloc} replacement library must be linked in before
+linking against @code{libc.a} (explicitly or implicitly).
+
+@strong{Note:} Failure to provide a complete set of replacement
+functions (that is, all the functions used by the application,
+@theglibc{}, and other linked-in libraries) can lead to static linking
+failures, and, at run time, to heap corruption and application crashes.
+
+The minimum set of functions which has to be provided by a custom
+@code{malloc} is given in the table below.
+
+@table @code
+@item malloc
+@item free
+@item calloc
+@item realloc
+@end table
+
+These @code{malloc}-related functions are required for @theglibc{} to
+work.@footnote{Versions of @theglibc{} before 2.25 required that a
+custom @code{malloc} defines @code{__libc_memalign} (with the same
+interface as the @code{memalign} function).}
+
+The @code{malloc} implementation in @theglibc{} provides additional
+functionality not used by the library itself, but which is often used by
+other system libraries and applications. A general-purpose replacement
+@code{malloc} implementation should provide definitions of these
+functions, too. Their names are listed in the following table.
+
+@table @code
+@item aligned_alloc
+@item malloc_usable_size
+@item memalign
+@item posix_memalign
+@item pvalloc
+@item valloc
+@end table
+
+In addition, very old applications may use the obsolete @code{cfree}
+function.
+
+Further @code{malloc}-related functions such as @code{mallopt} or
+@code{mallinfo} will not have any effect or return incorrect statistics
+when a replacement @code{malloc} is in use. However, failure to replace
+these functions typically does not result in crashes or other incorrect
+application behavior, but may result in static linking failures.
+
@node Obstacks
@subsection Obstacks
@cindex obstacks
file @file{obstack.h}.
@pindex obstack.h
-@comment obstack.h
-@comment GNU
@deftp {Data Type} {struct obstack}
+@standards{GNU, obstack.h}
An obstack is represented by a data structure of type @code{struct
obstack}. This structure has a small fixed size; it records the status
of the obstack and how to find the space in which objects are allocated.
as an obstack, it must initialize the obstack by calling
@code{obstack_init}.
-@comment obstack.h
-@comment GNU
@deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}}
@c obstack_init @mtsrace:obstack-ptr @acsmem
@c _obstack_begin @acsmem
obstack_init (myobstack_ptr);
@end smallexample
-@comment obstack.h
-@comment GNU
@defvar obstack_alloc_failed_handler
+@standards{GNU, obstack.h}
The value of this variable is a pointer to a function that
@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
memory. The default action is to print a message and abort.
The most direct way to allocate an object in an obstack is with
@code{obstack_alloc}, which is invoked almost like @code{malloc}.
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem
@c obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem
To allocate a block with specified contents, use the function
@code{obstack_copy}, declared like this:
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem
@c obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem
@code{obstack_chunk_alloc} failed.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem
@c obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem
one object automatically frees all other objects allocated more recently
in the same obstack.
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
@c obstack_free @mtsrace:obstack-ptr @acucorrupt
@c (obstack_free) @mtsrace:obstack-ptr @acucorrupt
ordinary allocation of another object. If you try to do so, the space
already added to the growing object will become part of the other object.
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem
@c _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem
@code{obstack_blank}, which adds space without initializing it.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
@c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
@var{data}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem
@c (no sequence point between storing NUL and incrementing next_free)
character.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem
@c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
It adds a single byte containing @var{c} to the growing object.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
@c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
containing the value of @var{data}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
@c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
the growing object and initializes them with the value of @var{data}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
@c obstack_finish @mtsrace:obstack-ptr @acucorrupt
When you are finished growing the object, use the function
before finishing the object with the function @code{obstack_object_size},
declared as follows:
-@comment obstack.h
-@comment GNU
@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
This function returns the current size of the growing object, in bytes.
Remember to call this function @emph{before} finishing the object.
The function @code{obstack_room} returns the amount of room available
in the current chunk. It is declared as follows:
-@comment obstack.h
-@comment GNU
@deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
This returns the number of bytes that can be added safely to the current
growing object (or to an object about to be started) in obstack
While you know there is room, you can use these fast growth functions
for adding data to a growing object:
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
@c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem
@c (no sequence point between copying c and incrementing next_free)
character @var{c} to the growing object in obstack @var{obstack-ptr}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
@c obstack_ptr_grow_fast @mtsrace:obstack-ptr
The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
obstack @var{obstack-ptr}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
@c obstack_int_grow_fast @mtsrace:obstack-ptr
The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
@var{obstack-ptr}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
@c obstack_blank_fast @mtsrace:obstack-ptr
The function @code{obstack_blank_fast} adds @var{size} bytes to the
allocation in an obstack. You can use them to learn about an object while
still growing it.
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
This function returns the tentative address of the beginning of the
currently growing object in @var{obstack-ptr}. If you finish the object
chunk).
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
This function returns the address of the first free byte in the current
chunk of obstack @var{obstack-ptr}. This is the end of the currently
returns the same value as @code{obstack_base}.
@end deftypefun
-@comment obstack.h
-@comment GNU
@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@c dup
@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
This function returns the size in bytes of the currently growing object.
@code{obstack_alignment_mask}, whose function prototype looks like
this:
-@comment obstack.h
-@comment GNU
@deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The value is a bit mask; a bit that is 1 indicates that the corresponding
bit in the address of an object should be 0. The mask value should be one
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet used.
-@comment obstack.h
-@comment GNU
@deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
+@standards{GNU, obstack.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This returns the chunk size of the given obstack.
@end deftypefn
a BSD extension.
@pindex stdlib.h
-@comment stdlib.h
-@comment GNU, BSD
@deftypefun {void *} alloca (size_t @var{size})
+@standards{GNU, stdlib.h}
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The return value of @code{alloca} is the address of a block of @var{size}
bytes of memory, allocated in the stack frame of the calling function.
functions below itself. The functions below are simple interfaces to
system calls.
-@comment unistd.h
-@comment BSD
@deftypefun int brk (void *@var{addr})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{brk} sets the high end of the calling process' data segment to
@end deftypefun
-@comment unistd.h
-@comment BSD
@deftypefun void *sbrk (ptrdiff_t @var{delta})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is the same as @code{brk} except that you specify the new
@end deftypefun
+@node Memory Protection
+@section Memory Protection
+@cindex memory protection
+@cindex page protection
+@cindex protection flags
+
+When a page is mapped using @code{mmap}, page protection flags can be
+specified using the protection flags argument. @xref{Memory-mapped
+I/O}.
+
+The following flags are available:
+
+@vtable @code
+@item PROT_WRITE
+@standards{POSIX, sys/mman.h}
+The memory can be written to.
+
+@item PROT_READ
+@standards{POSIX, sys/mman.h}
+The memory can be read. On some architectures, this flag implies that
+the memory can be executed as well (as if @code{PROT_EXEC} had been
+specified at the same time).
+
+@item PROT_EXEC
+@standards{POSIX, sys/mman.h}
+The memory can be used to store instructions which can then be executed.
+On most architectures, this flag implies that the memory can be read (as
+if @code{PROT_READ} had been specified).
+
+@item PROT_NONE
+@standards{POSIX, sys/mman.h}
+This flag must be specified on its own.
+
+The memory is reserved, but cannot be read, written, or executed. If
+this flag is specified in a call to @code{mmap}, a virtual memory area
+will be set aside for future use in the process, and @code{mmap} calls
+without the @code{MAP_FIXED} flag will not use it for subsequent
+allocations. For anonymous mappings, the kernel will not reserve any
+physical memory for the allocation at the time the mapping is created.
+@end vtable
+
+The operating system may keep track of these flags separately even if
+the underlying hardware treats them the same for the purposes of access
+checking (as happens with @code{PROT_READ} and @code{PROT_EXEC} on some
+platforms). On GNU systems, @code{PROT_EXEC} always implies
+@code{PROT_READ}, so that users can view the machine code which is
+executing on their system.
+
+Inappropriate access will cause a segfault (@pxref{Program Error
+Signals}).
+
+After allocation, protection flags can be changed using the
+@code{mprotect} function.
+
+@deftypefun int mprotect (void *@var{address}, size_t @var{length}, int @var{protection})
+@standards{POSIX, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+A successful call to the @code{mprotect} function changes the protection
+flags of at least @var{length} bytes of memory, starting at
+@var{address}.
+
+@var{address} must be aligned to the page size for the mapping. The
+system page size can be obtained by calling @code{sysconf} with the
+@code{_SC_PAGESIZE} parameter (@pxref{Sysconf Definition}). The system
+page size is the granularity in which the page protection of anonymous
+memory mappings and most file mappings can be changed. Memory which is
+mapped from special files or devices may have larger page granularity
+than the system page size and may require larger alignment.
+
+@var{length} is the number of bytes whose protection flags must be
+changed. It is automatically rounded up to the next multiple of the
+system page size.
+
+@var{protection} is a combination of the @code{PROT_*} flags described
+above.
+
+The @code{mprotect} function returns @math{0} on success and @math{-1}
+on failure.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item ENOMEM
+The system was not able to allocate resources to fulfill the request.
+This can happen if there is not enough physical memory in the system for
+the allocation of backing storage. The error can also occur if the new
+protection flags would cause the memory region to be split from its
+neighbors, and the process limit for the number of such distinct memory
+regions would be exceeded.
+
+@item EINVAL
+@var{address} is not properly aligned to a page boundary for the
+mapping, or @var{length} (after rounding up to the system page size) is
+not a multiple of the applicable page size for the mapping, or the
+combination of flags in @var{protection} is not valid.
+
+@item EACCES
+The file for a file-based mapping was not opened with open flags which
+are compatible with @var{protection}.
+
+@item EPERM
+The system security policy does not allow a mapping with the specified
+flags. For example, mappings which are both @code{PROT_EXEC} and
+@code{PROT_WRITE} at the same time might not be allowed.
+@end table
+@end deftypefun
+
+If the @code{mprotect} function is used to make a region of memory
+inaccessible by specifying the @code{PROT_NONE} protection flag and
+access is later restored, the memory retains its previous contents.
+
+On some systems, it may not be possible to specify additional flags
+which were not present when the mapping was first created. For example,
+an attempt to make a region of memory executable could fail if the
+initial protection flags were @samp{PROT_READ | PROT_WRITE}.
+
+In general, the @code{mprotect} function can be used to change any
+process memory, no matter how it was allocated. However, portable use
+of the function requires that it is only used with memory regions
+returned by @code{mmap} or @code{mmap64}.
+
+@subsection Memory Protection Keys
+
+@cindex memory protection key
+@cindex protection key
+@cindex MPK
+On some systems, further restrictions can be added to specific pages
+using @dfn{memory protection keys}. These restrictions work as follows:
+
+@itemize @bullet
+@item
+All memory pages are associated with a protection key. The default
+protection key does not cause any additional protections to be applied
+during memory accesses. New keys can be allocated with the
+@code{pkey_alloc} function, and applied to pages using
+@code{pkey_mprotect}.
+
+@item
+Each thread has a set of separate access right restriction for each
+protection key. These access rights can be manipulated using the
+@code{pkey_set} and @code{pkey_get} functions.
+
+@item
+During a memory access, the system obtains the protection key for the
+accessed page and uses that to determine the applicable access rights,
+as configured for the current thread. If the access is restricted, a
+segmentation fault is the result ((@pxref{Program Error Signals}).
+These checks happen in addition to the @code{PROT_}* protection flags
+set by @code{mprotect} or @code{pkey_mprotect}.
+@end itemize
+
+New threads and subprocesses inherit the access rights of the current
+thread. If a protection key is allocated subsequently, existing threads
+(except the current) will use an unspecified system default for the
+access rights associated with newly allocated keys.
+
+Upon entering a signal handler, the system resets the access rights of
+the current thread so that pages with the default key can be accessed,
+but the access rights for other protection keys are unspecified.
+
+Applications are expected to allocate a key once using
+@code{pkey_alloc}, and apply the key to memory regions which need
+special protection with @code{pkey_mprotect}:
+
+@smallexample
+ int key = pkey_alloc (0, PKEY_DISABLE_ACCESS);
+ if (key < 0)
+ /* Perform error checking, including fallback for lack of support. */
+ ...;
+
+ /* Apply the key to a special memory region used to store critical
+ data. */
+ if (pkey_mprotect (region, region_length,
+ PROT_READ | PROT_WRITE, key) < 0)
+ ...; /* Perform error checking (generally fatal). */
+@end smallexample
+
+If the key allocation fails due to lack of support for memory protection
+keys, the @code{pkey_mprotect} call can usually be skipped. In this
+case, the region will not be protected by default. It is also possible
+to call @code{pkey_mprotect} with a key value of @math{-1}, in which
+case it will behave in the same way as @code{mprotect}.
+
+After key allocation assignment to memory pages, @code{pkey_set} can be
+used to temporarily acquire access to the memory region and relinquish
+it again:
+
+@smallexample
+ if (key >= 0 && pkey_set (key, 0) < 0)
+ ...; /* Perform error checking (generally fatal). */
+ /* At this point, the current thread has read-write access to the
+ memory region. */
+ ...
+ /* Revoke access again. */
+ if (key >= 0 && pkey_set (key, PKEY_DISABLE_ACCESS) < 0)
+ ...; /* Perform error checking (generally fatal). */
+@end smallexample
+
+In this example, a negative key value indicates that no key had been
+allocated, which means that the system lacks support for memory
+protection keys and it is not necessary to change the the access rights
+of the current thread (because it always has access).
+
+Compared to using @code{mprotect} to change the page protection flags,
+this approach has two advantages: It is thread-safe in the sense that
+the access rights are only changed for the current thread, so another
+thread which changes its own access rights concurrently to gain access
+to the mapping will not suddenly see its access rights revoked. And
+@code{pkey_set} typically does not involve a call into the kernel and a
+context switch, so it is more efficient.
+
+@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{restrictions})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+Allocate a new protection key. The @var{flags} argument is reserved and
+must be zero. The @var{restrictions} argument specifies access rights
+which are applied to the current thread (as if with @code{pkey_set}
+below). Access rights of other threads are not changed.
+
+The function returns the new protection key, a non-negative number, or
+@math{-1} on error.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item ENOSYS
+The system does not implement memory protection keys.
+
+@item EINVAL
+The @var{flags} argument is not zero.
+
+The @var{restrictions} argument is invalid.
+The system does not implement memory protection keys or runs in a mode
+in which memory protection keys are disabled.
+
+@item ENOSPC
+All available protection keys already have been allocated.
+@end table
+@end deftypefun
+
+@deftypefun int pkey_free (int @var{key})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Deallocate the protection key, so that it can be reused by
+@code{pkey_alloc}.
+
+Calling this function does not change the access rights of the freed
+protection key. The calling thread and other threads may retain access
+to it, even if it is subsequently allocated again. For this reason, it
+is not recommended to call the @code{pkey_free} function.
+
+@table @code
+@item ENOSYS
+The system does not implement memory protection keys.
+
+@item EINVAL
+The @var{key} argument is not a valid protection key.
+@end table
+@end deftypefun
+
+@deftypefun int pkey_mprotect (void *@var{address}, size_t @var{length}, int @var{protection}, int @var{key})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Similar to @code{mprotect}, but also set the memory protection key for
+the memory region to @code{key}.
+
+Some systems use memory protection keys to emulate certain combinations
+of @var{protection} flags. Under such circumstances, specifying an
+explicit protection key may behave as if additional flags have been
+specified in @var{protection}, even though this does not happen with the
+default protection key. For example, some systems can support
+@code{PROT_EXEC}-only mappings only with a default protection key, and
+memory with a key which was allocated using @code{pkey_alloc} will still
+be readable if @code{PROT_EXEC} is specified without @code{PROT_READ}.
+
+If @var{key} is @math{-1}, the default protection key is applied to the
+mapping, just as if @code{mprotect} had been called.
+
+The @code{pkey_mprotect} function returns @math{0} on success and
+@math{-1} on failure. The same @code{errno} error conditions as for
+@code{mprotect} are defined for this function, with the following
+addition:
+
+@table @code
+@item EINVAL
+The @var{key} argument is not @math{-1} or a valid memory protection
+key allocated using @code{pkey_alloc}.
+
+@item ENOSYS
+The system does not implement memory protection keys, and @var{key} is
+not @math{-1}.
+@end table
+@end deftypefun
+
+@deftypefun int pkey_set (int @var{key}, unsigned int @var{rights})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Change the access rights of the current thread for memory pages with the
+protection key @var{key} to @var{rights}. If @var{rights} is zero, no
+additional access restrictions on top of the page protection flags are
+applied. Otherwise, @var{rights} is a combination of the following
+flags:
+
+@vtable @code
+@item PKEY_DISABLE_WRITE
+@standards{Linux, sys/mman.h}
+Subsequent attempts to write to memory with the specified protection
+key will fault.
+
+@item PKEY_DISABLE_ACCESS
+@standards{Linux, sys/mman.h}
+Subsequent attempts to write to or read from memory with the specified
+protection key will fault.
+@end vtable
+
+Operations not specified as flags are not restricted. In particular,
+this means that the memory region will remain executable if it was
+mapped with the @code{PROT_EXEC} protection flag and
+@code{PKEY_DISABLE_ACCESS} has been specified.
+
+Calling the @code{pkey_set} function with a protection key which was not
+allocated by @code{pkey_alloc} results in undefined behavior. This
+means that calling this function on systems which do not support memory
+protection keys is undefined.
+
+The @code{pkey_set} function returns @math{0} on success and @math{-1}
+on failure.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EINVAL
+The system does not support the access rights restrictions expressed in
+the @var{rights} argument.
+@end table
+@end deftypefun
+
+@deftypefun int pkey_get (int @var{key})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Return the access rights of the current thread for memory pages with
+protection key @var{key}. The return value is zero or a combination of
+the @code{PKEY_DISABLE_}* flags; see the @code{pkey_set} function.
+
+Calling the @code{pkey_get} function with a protection key which was not
+allocated by @code{pkey_alloc} results in undefined behavior. This
+means that calling this function on systems which do not support memory
+protection keys is undefined.
+@end deftypefun
@node Locking Pages
@section Locking Pages
@item
Privacy. If you keep secrets in virtual memory and that virtual memory
gets paged out, that increases the chance that the secrets will get out.
-If a password gets written out to disk swap space, for example, it might
+If a passphrase gets written out to disk swap space, for example, it might
still be there long after virtual and real memory have been wiped clean.
@end itemize
define the macro @code{_POSIX_MEMLOCK}. @Theglibc{} conforms to
this requirement.
-@comment sys/mman.h
-@comment POSIX.1b
@deftypefun int mlock (const void *@var{addr}, size_t @var{len})
+@standards{POSIX.1b, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{mlock} locks a range of the calling process' virtual pages.
The kernel does not provide @code{mlock} capability.
@end table
+@end deftypefun
+
+@deftypefun int mlock2 (const void *@var{addr}, size_t @var{len}, unsigned int @var{flags})
+@standards{Linux, sys/mman.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is similar to @code{mlock}. If @var{flags} is zero, a
+call to @code{mlock2} behaves exactly as the equivalent call to @code{mlock}.
+
+The @var{flags} argument must be a combination of zero or more of the
+following flags:
+
+@vtable @code
+@item MLOCK_ONFAULT
+@standards{Linux, sys/mman.h}
+Only those pages in the specified address range which are already in
+memory are locked immediately. Additional pages in the range are
+automatically locked in case of a page fault and allocation of memory.
+@end vtable
+
+Like @code{mlock}, @code{mlock2} returns zero on success and @code{-1}
+on failure, setting @code{errno} accordingly. Additional @code{errno}
+values defined for @code{mlock2} are:
+
+@table @code
+@item EINVAL
+The specified (non-zero) @var{flags} argument is not supported by this
+system.
+@end table
+@end deftypefun
You can lock @emph{all} a process' memory with @code{mlockall}. You
unlock memory with @code{munlock} or @code{munlockall}.
from the C code, e.g. the stack and automatic variables, and you
wouldn't know what address to tell @code{mlock}.
-@end deftypefun
-
-@comment sys/mman.h
-@comment POSIX.1b
@deftypefun int munlock (const void *@var{addr}, size_t @var{len})
+@standards{POSIX.1b, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{munlock} unlocks a range of the calling process' virtual pages.
@end deftypefun
-@comment sys/mman.h
-@comment POSIX.1b
@deftypefun int mlockall (int @var{flags})
+@standards{POSIX.1b, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{mlockall} locks all the pages in a process' virtual memory address
macros. They tell @code{mlockall} which of its functions you want. All
other bits must be zero.
-@table @code
+@vtable @code
@item MCL_CURRENT
Lock all pages which currently exist in the calling process' virtual
replaces a process' address space, wipes out @code{MCL_FUTURE}.
@xref{Executing a File}.
-@end table
+@end vtable
When the function returns successfully, and you specified
@code{MCL_CURRENT}, all of the process' pages are backed by (connected
@end deftypefun
-@comment sys/mman.h
-@comment POSIX.1b
@deftypefun int munlockall (void)
+@standards{POSIX.1b, sys/mman.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{munlockall} unlocks every page in the calling process' virtual
projects / thirdparty / glibc.git / blobdiff