]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
0669cc5f MK |
2 | .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
0669cc5f | 5 | .\" |
4c1c5274 | 6 | .TH malloc_get_state 3 (date) "Linux man-pages (unreleased)" |
0669cc5f | 7 | .SH NAME |
15f0b7af AC |
8 | malloc_get_state, malloc_set_state \- |
9 | record and restore state of malloc implementation | |
a00fca47 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
8fc3b2cf | 12 | .RI ( libc ", " \-lc ) |
0669cc5f MK |
13 | .SH SYNOPSIS |
14 | .nf | |
ebae2ae3 | 15 | .B #include <malloc.h> |
c6d039a3 | 16 | .P |
1ae6b2c7 | 17 | .B void *malloc_get_state(void); |
0669cc5f MK |
18 | .BI "int malloc_set_state(void *" state ); |
19 | .fi | |
20 | .SH DESCRIPTION | |
30ed4712 | 21 | .IR Note : |
aa606765 | 22 | these functions are removed in glibc 2.25. |
c6d039a3 | 23 | .P |
0669cc5f MK |
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.) | |
c6d039a3 | 40 | .P |
0669cc5f MK |
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. | |
c6d039a3 | 55 | .P |
0669cc5f MK |
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. | |
99f8b666 ZL |
73 | .SH ATTRIBUTES |
74 | For an explanation of the terms used in this section, see | |
75 | .BR attributes (7). | |
76 | .TS | |
77 | allbox; | |
c466875e | 78 | lbx lb lb |
99f8b666 ZL |
79 | l l l. |
80 | Interface Attribute Value | |
81 | T{ | |
9e54434e BR |
82 | .na |
83 | .nh | |
99f8b666 ZL |
84 | .BR malloc_get_state (), |
85 | .BR malloc_set_state () | |
86 | T} Thread safety MT-Safe | |
87 | .TE | |
3113c7f3 | 88 | .SH STANDARDS |
4131356c | 89 | GNU. |
0669cc5f | 90 | .SH NOTES |
98a9b1ab | 91 | These functions are useful when using this |
0669cc5f MK |
92 | .BR malloc (3) |
93 | implementation as part of a shared library, | |
94 | and the heap contents are saved/restored via some other method. | |
98a9b1ab | 95 | This technique is used by GNU Emacs to implement its "dumping" function. |
c6d039a3 | 96 | .P |
0669cc5f MK |
97 | Hook function pointers are never saved or restored by these |
98 | functions, with two exceptions: | |
99 | if malloc checking (see | |
100 | .BR mallopt (3)) | |
101 | was in use when | |
102 | .BR malloc_get_state () | |
103 | was called, then | |
104 | .BR malloc_set_state () | |
105 | resets malloc checking hooks | |
106 | .\" i.e., calls __malloc_check_init() | |
107 | if possible; | |
108 | .\" i.e., malloc checking is not already in use | |
109 | .\" and the caller requested malloc checking | |
110 | if malloc checking was not in use in the recorded state, | |
111 | but the caller has requested malloc checking, | |
112 | then the hooks are reset to 0. | |
113 | .SH SEE ALSO | |
114 | .BR malloc (3), | |
115 | .BR mallopt (3) |