summaryrefslogtreecommitdiffstats
path: root/lpsm_malloc.3.in
blob: 9bb63cf9b9a03a0f1b2b6ec76b5dbec2e219a936 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
.\" -*- nroff -*- ---------------------------------------------------------
.\"   
.\"   Copyright 2001-2008 H. Peter Anvin - All Rights Reserved
.\"
.\"   This program is free software; you can redistribute it and/or modify
.\"   it under the terms of the GNU Lesser General Public License as
.\"   published by the Free Software Foundation, Inc.,
.\"   59 Temple Place Ste 330, Bostom MA 02111-1307, USA; version 2.1,
.\"   incorporated herein by reference.
.\"
.\" -----------------------------------------------------------------------
.TH LPSM_MALLOC 3  "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
.SH NAME
lpsm_malloc, lpsm_free, lpsm_realloc, lpsm_zalloc, lpsm_calloc \- Allocate and free persistent memory
.SH SYNOPSIS
.nf
.B #include <lpsm.h>
.sp
.BI "void *lpsm_malloc(size_t " "size" ");"
.nl
.BI "void lpsm_free(void " "*ptr" ");"
.nl
.BI "void *lpsm_realloc(void " "*ptr" ", size_t "  "size" ");"
.nl
.BI "void *lpsm_zalloc(size_t " "size" ");"
.nl
.BI "void *lpsm_calloc(size_t " "nmemb" ", size_t " "size" ");"
.nl
.fi
.SH DESCRIPTION
These functions allocate persistent memory.  A persistent memory arena
needs to be initialized with
.B lpsm_init()
before these functions can be called; it is subsequently managed via
.B lpsm_checkpoint()
and
.BR lpsm_shutdown() .
.PP
.B lpsm_malloc()
allocates
.I size
bytes and returns a pointer to the allocated memory. 
The memory is not cleared.
.PP
.B lpsm_free()
frees the memory space pointed to by
.IR ptr ,
which must have been returned by a previous call to
.BR lpsm_malloc() ,
.BR lpsm_zalloc() ,
.BR lpsm_calloc()
or
.BR lpsm_realloc() .
Otherwise, or if
.BI "lpsm_free(" "ptr" )
has already been called before, undefined behaviour occurs.
If
.I ptr
is
.BR NULL ,
no operation is performed.
.PP
.B lpsm_realloc()
changes the size of the memory block pointed to by
.I ptr
to
.I size
bytes.
The contents will be unchanged to the minimum of the old and new sizes;
newly allocated memory will be uninitialized.
If
.I ptr
is
.BR NULL ,
the call is equivalent to
\fBlpsm_malloc(\fP\fIsize\fP\fB)\fP;
if size is equal to zero,
the call is equivalent to
\fBlpsm_free(\fP\fIptr\fP\fB)\fP.
Unless
.I ptr
is
.BR NULL ,
it must have been returned by an earlier call to
.BR lpsm_malloc() ,
.BR lpsm_calloc()
or
.BR lpsm_realloc() .
.PP
.B lpsm_zalloc()
allocates
.I size
bytes and returns a pointer to the allocated memory. 
The memory is set to zero.
.PP
.B lpsm_calloc()
allocates memory for an array of 
.I nmemb
elements of 
.I size
bytes each and returns a pointer to the allocated memory. 
The memory is set to zero.  This is functionally equivalent to
\fBlpsm_zalloc(\fP\fInmemb\fP\fB*\fP\fIsize\fP\fB)\fP.
.SH "RETURN VALUES"
For
.BR lpsm_malloc() ,
.BR lpsm_zalloc() ,
and
.BR lpsm_calloc() ,
the value returned is a pointer to the allocated memory, which is suitably
aligned for any kind of variable that can fit into the allocation size, or
.B NULL
if the request fails.
.PP
.B lpsm_free()
returns no value.
.PP
.B lpsm_realloc()
returns a pointer to the newly allocated memory, which is suitably
aligned for any kind of variable that can fit into the new allocation size
and which may be different from
.IR ptr ,
or
.B NULL
if the request fails or if size was equal to 0 and
.I ptr
was not
.BR NULL .
If
.B lpsm_realloc()
fails the original block is left untouched - it is not freed or moved.
.SH "ERRORS"
.TP
ENOMEM
.BR lpsm_malloc() ,
.BR lpsm_zalloc() ,
.BR lpsm_calloc()
or
.BR lpsm_realloc()
were unable to allocate the memory requested.
.SH "CONFORMING TO"
These functions mimic in as much as possible the ISO C and POSIX
behaviour of the equivalent transient memory allocation functions.
.SH "SEE ALSO"
.BR lpsm_alloc_size (3),
.BR lpsm_alloc_stats (3),
.BR lpsm_init (3),
.BR malloc (3),
.BR lpsm (7).
.SH NOTES
The allocator used can handle allocations down to single byte size
with high efficiency.  Large allocations are rounded to the nearest
higher power of two.
.SH BUGS
The allocator used is very sensitive to invalid pointers passed to
.B lpsm_free()
or
.BR lpsm_realloc() .
Passing a bad pointer to one of these functions is very likely to
result in data loss.
.PP
.B lpsm_calloc()
does not check for multiplication overflow.
.PP
The persistent memory system is not currently thread-safe.