Debian Codegraph @

upstream/debian-unstable/man3/malloc_get_state.3

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