man3/malloc_get_state.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH malloc_get_state 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 malloc_get_state, malloc_set_state \-
   9 record and restore state of malloc implementation
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <malloc.h>
  16 .PP
  17 .B void *malloc_get_state(void);
  18 .BI "int malloc_set_state(void *" state );
  19 .fi
  20 .SH DESCRIPTION
  21 .IR Note :
  22 these function are removed in glibc 2.25.
  23 .PP
  24 The
  25 .BR malloc_get_state ()
  26 function records the current state of all
  27 .BR malloc (3)
  28 internal bookkeeping variables
  29 (but not the actual contents of the heap
  30 or the state of
  31 .BR malloc_hook (3)
  32 functions pointers).
  33 The state is recorded in a system-dependent opaque data structure
  34 dynamically allocated via
  35 .BR malloc (3),
  36 and a pointer to that data structure is returned as the function result.
  37 (It is the caller's responsibility to
  38 .BR free (3)
  39 this memory.)
  40 .PP
  41 The
  42 .BR malloc_set_state ()
  43 function restores the state of all
  44 .BR malloc (3)
  45 internal bookkeeping variables to the values recorded in
  46 the opaque data structure pointed to by
  47 .IR state .
  48 .SH RETURN VALUE
  49 On success,
  50 .BR malloc_get_state ()
  51 returns a pointer to a newly allocated opaque data structure.
  52 On error (for example, memory could not be allocated for the data structure),
  53 .BR malloc_get_state ()
  54 returns NULL.
  55 .PP
  56 On success,
  57 .BR malloc_set_state ()
  58 returns 0.
  59 If the implementation detects that
  60 .I state
  61 does not point to a correctly formed data structure,
  62 .\" if(ms->magic != MALLOC_STATE_MAGIC) return -1;
  63 .BR malloc_set_state ()
  64 returns \-1.
  65 If the implementation detects that
  66 the version of the data structure referred to by
  67 .I state
  68 is a more recent version than this implementation knows about,
  69 .\" /* Must fail if the major version is too high. */
  70 .\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2;
  71 .BR malloc_set_state ()
  72 returns \-2.
  73 .SH ATTRIBUTES
  74 For an explanation of the terms used in this section, see
  75 .BR attributes (7).
  76 .ad l
  77 .nh
  78 .TS
  79 allbox;
  80 lbx lb lb
  81 l l l.
  82 Interface       Attribute       Value
  83 T{
  84 .BR malloc_get_state (),
  85 .BR malloc_set_state ()
  86 T}      Thread safety   MT-Safe
  87 .TE
  88 .hy
  89 .ad
  90 .sp 1
  91 .SH STANDARDS
  92 GNU.
  93 .SH NOTES
  94 These functions are useful when using this
  95 .BR malloc (3)
  96 implementation as part of a shared library,
  97 and the heap contents are saved/restored via some other method.
  98 This technique is used by GNU Emacs to implement its "dumping" function.
  99 .PP
 100 Hook function pointers are never saved or restored by these
 101 functions, with two exceptions:
 102 if malloc checking (see
 103 .BR mallopt (3))
 104 was in use when
 105 .BR malloc_get_state ()
 106 was called, then
 107 .BR malloc_set_state ()
 108 resets malloc checking hooks
 109 .\" i.e., calls __malloc_check_init()
 110 if possible;
 111 .\" i.e., malloc checking is not already in use
 112 .\" and the caller requested malloc checking
 113 if malloc checking was not in use in the recorded state,
 114 but the caller has requested malloc checking,
 115 then the hooks are reset to 0.
 116 .SH SEE ALSO
 117 .BR malloc (3),
 118 .BR mallopt (3)