[thirdparty/man-pages.git] / man3 / malloc_get_state.3

.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.TH MALLOC_GET_STATE 3 2017-09-15 "GNU" "Linux Programmer's Manual"
.SH NAME
malloc_get_state, malloc_set_state \- record and restore state of malloc implementation
.SH SYNOPSIS
.nf
.B #include <malloc.h>
.PP
.BI "void* malloc_get_state(void);"
.PP
.BI "int malloc_set_state(void *" state );
.fi
.SH DESCRIPTION
.IR Note :
these function are removed in glibc version 2.25.
.PP
The
.BR malloc_get_state ()
function records the current state of all
.BR malloc (3)
internal bookkeeping variables
(but not the actual contents of the heap
or the state of
.BR malloc_hook (3)
functions pointers).
The state is recorded in a system-dependent opaque data structure
dynamically allocated via
.BR malloc (3),
and a pointer to that data structure is returned as the function result.
(It is the caller's responsibility to
.BR free (3)
this memory.)
.PP
The
.BR malloc_set_state ()
function restores the state of all
.BR malloc (3)
internal bookkeeping variables to the values recorded in
the opaque data structure pointed to by
.IR state .
.SH RETURN VALUE
On success,
.BR malloc_get_state ()
returns a pointer to a newly allocated opaque data structure.
On error (for example, memory could not be allocated for the data structure),
.BR malloc_get_state ()
returns NULL.
.PP
On success,
.BR malloc_set_state ()
returns 0.
If the implementation detects that
.I state
does not point to a correctly formed data structure,
.\" if(ms->magic != MALLOC_STATE_MAGIC) return -1;
.BR malloc_set_state ()
returns \-1.
If the implementation detects that
the version of the data structure referred to by
.I state
is a more recent version than this implementation knows about,
.\" /* Must fail if the major version is too high. */
.\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2;
.BR malloc_set_state ()
returns \-2.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbw19 lb lb
l l l.
Interface	Attribute	Value
T{
.BR malloc_get_state (),
.BR malloc_set_state ()
T}	Thread safety	MT-Safe
.TE
.sp 1
.SH CONFORMING TO
These functions are GNU extensions.
.SH NOTES
These functions are useful when using this
.BR malloc (3)
implementation as part of a shared library,
and the heap contents are saved/restored via some other method.
This technique is used by GNU Emacs to implement its "dumping" function.
.PP
Hook function pointers are never saved or restored by these
functions, with two exceptions:
if malloc checking (see
.BR mallopt (3))
was in use when
.BR malloc_get_state ()
was called, then
.BR malloc_set_state ()
resets malloc checking hooks
.\" i.e., calls __malloc_check_init()
if possible;
.\" i.e., malloc checking is not already in use
.\" and the caller requested malloc checking
if malloc checking was not in use in the recorded state,
but the caller has requested malloc checking,
then the hooks are reset to 0.
.SH SEE ALSO
.BR malloc (3),
.BR mallopt (3)
Commit	Line	Data
0669cc5f MK	1	.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
0669cc5f MK	2	.\"
93015253	3	.\" %%%LICENSE_START(VERBATIM)
0669cc5f MK	4	.\" Permission is granted to make and distribute verbatim copies of this
	5	.\" manual provided the copyright notice and this permission notice are
	6	.\" preserved on all copies.
	7	.\"
	8	.\" Permission is granted to copy and distribute modified versions of this
	9	.\" manual under the conditions for verbatim copying, provided that the
	10	.\" entire resulting derived work is distributed under the terms of a
	11	.\" permission notice identical to this one.
	12	.\"
	13	.\" Since the Linux kernel and libraries are constantly changing, this
	14	.\" manual page may be incorrect or out-of-date. The author(s) assume no
	15	.\" responsibility for errors or omissions, or for damages resulting from
	16	.\" the use of the information contained herein. The author(s) may not
	17	.\" have taken the same level of care in the production of this manual,
	18	.\" which is licensed free of charge, as they might when working
	19	.\" professionally.
	20	.\"
	21	.\" Formatted or processed versions of this manual, if unaccompanied by
	22	.\" the source, must acknowledge the copyright and authors of this work.
4b72fb64	23	.\" %%%LICENSE_END
0669cc5f	24	.\"
4b8c67d9	25	.TH MALLOC_GET_STATE 3 2017-09-15 "GNU" "Linux Programmer's Manual"
0669cc5f	26	.SH NAME
092af13a	27	malloc_get_state, malloc_set_state \- record and restore state of malloc implementation
0669cc5f MK	28	.SH SYNOPSIS
0669cc5f MK	29	.nf
ebae2ae3	30	.B #include <malloc.h>
68e4db0a	31	.PP
0669cc5f	32	.BI "void* malloc_get_state(void);"
dbfe9c70	33	.PP
0669cc5f MK	34	.BI "int malloc_set_state(void *" state );
	35	.fi
	36	.SH DESCRIPTION
30ed4712 MK	37	.IR Note :
30ed4712 MK	38	these function are removed in glibc version 2.25.
847e0d88	39	.PP
0669cc5f MK	40	The
	41	.BR malloc_get_state ()
	42	function records the current state of all
	43	.BR malloc (3)
	44	internal bookkeeping variables
	45	(but not the actual contents of the heap
	46	or the state of
	47	.BR malloc_hook (3)
	48	functions pointers).
	49	The state is recorded in a system-dependent opaque data structure
	50	dynamically allocated via
	51	.BR malloc (3),
	52	and a pointer to that data structure is returned as the function result.
	53	(It is the caller's responsibility to
	54	.BR free (3)
	55	this memory.)
847e0d88	56	.PP
0669cc5f MK	57	The
	58	.BR malloc_set_state ()
	59	function restores the state of all
	60	.BR malloc (3)
	61	internal bookkeeping variables to the values recorded in
	62	the opaque data structure pointed to by
	63	.IR state .
	64	.SH RETURN VALUE
	65	On success,
	66	.BR malloc_get_state ()
	67	returns a pointer to a newly allocated opaque data structure.
	68	On error (for example, memory could not be allocated for the data structure),
	69	.BR malloc_get_state ()
	70	returns NULL.
847e0d88	71	.PP
0669cc5f MK	72	On success,
	73	.BR malloc_set_state ()
	74	returns 0.
	75	If the implementation detects that
	76	.I state
	77	does not point to a correctly formed data structure,
	78	.\" if(ms->magic != MALLOC_STATE_MAGIC) return -1;
	79	.BR malloc_set_state ()
	80	returns \-1.
	81	If the implementation detects that
	82	the version of the data structure referred to by
	83	.I state
	84	is a more recent version than this implementation knows about,
	85	.\" /* Must fail if the major version is too high. */
	86	.\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2;
	87	.BR malloc_set_state ()
	88	returns \-2.
99f8b666 ZL	89	.SH ATTRIBUTES
	90	For an explanation of the terms used in this section, see
	91	.BR attributes (7).
	92	.TS
	93	allbox;
	94	lbw19 lb lb
	95	l l l.
	96	Interface Attribute Value
	97	T{
	98	.BR malloc_get_state (),
	99	.BR malloc_set_state ()
	100	T} Thread safety MT-Safe
	101	.TE
847e0d88	102	.sp 1
0669cc5f MK	103	.SH CONFORMING TO
	104	These functions are GNU extensions.
	105	.SH NOTES
98a9b1ab	106	These functions are useful when using this
0669cc5f MK	107	.BR malloc (3)
	108	implementation as part of a shared library,
	109	and the heap contents are saved/restored via some other method.
98a9b1ab	110	This technique is used by GNU Emacs to implement its "dumping" function.
847e0d88	111	.PP
0669cc5f MK	112	Hook function pointers are never saved or restored by these
	113	functions, with two exceptions:
	114	if malloc checking (see
	115	.BR mallopt (3))
	116	was in use when
	117	.BR malloc_get_state ()
	118	was called, then
	119	.BR malloc_set_state ()
	120	resets malloc checking hooks
	121	.\" i.e., calls __malloc_check_init()
	122	if possible;
	123	.\" i.e., malloc checking is not already in use
	124	.\" and the caller requested malloc checking
	125	if malloc checking was not in use in the recorded state,
	126	but the caller has requested malloc checking,
	127	then the hooks are reset to 0.
	128	.SH SEE ALSO
	129	.BR malloc (3),
	130	.BR mallopt (3)