1# Memory
2
3
4## Overview
5
6Provides APIs for memory management.
7
8@Syscap SystemCapability.CommonLibrary.PurgeableMemory
9
10**Since**
11
1210
13
14
15## Summary
16
17
18### Files
19
20| Name| Description|
21| -------- | -------- |
22| [purgeable_memory.h](purgeable__memory_8h.md) | Declares the APIs for managing purgeable memory at the native layer.<br>**File to include**: <purgeable_memory/purgeable_memory.h><br>**Library**: libpurgeable_memory_ndk.z.so|
23
24
25### Types
26
27| Name| Description|
28| -------- | -------- |
29| [OH_PurgeableMemory](#oh_purgeablememory) | Defines the type name of the **OH_PurgeableMemory** data.|
30| (\*[OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc)) (void \*, size_t, void \*) | Defines the function for rebuilding purgeable memory data.|
31
32
33### Functions
34
35| Name| Description|
36| -------- | -------- |
37| \*[OH_PurgeableMemory_Create](#oh_purgeablememory_create) (size_t size, [OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Creates a **PurgeableMemory** object.|
38| [OH_PurgeableMemory_Destroy](#oh_purgeablememory_destroy) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Destroys a **PurgeableMemory** object.|
39| [OH_PurgeableMemory_BeginRead](#oh_purgeablememory_beginread) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Starts a read operation on a **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
40| [OH_PurgeableMemory_EndRead](#oh_purgeablememory_endread) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Ends a read operation on a **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
41| [OH_PurgeableMemory_BeginWrite](#oh_purgeablememory_beginwrite) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Begins a write operation on the **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
42| [OH_PurgeableMemory_EndWrite](#oh_purgeablememory_endwrite) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Ends a write operation on the **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
43| [OH_PurgeableMemory_GetContent](#oh_purgeablememory_getcontent) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Obtains the memory data of a **PurgeableMemory** object.|
44| [OH_PurgeableMemory_ContentSize](#oh_purgeablememory_contentsize) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Obtains the memory data size of a **PurgeableMemory** object.|
45| [OH_PurgeableMemory_AppendModify](#oh_purgeablememory_appendmodify) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj, [OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Adds a function for modifying a **PurgeableMemory** object.|
46
47
48## Type Description
49
50
51### OH_PurgeableMemory
52
53
54```
55typedef struct PurgMem OH_PurgeableMemory
56```
57
58**Description**
59
60Defines the type name of the **OH_PurgeableMemory** data.
61
62**Since**
63
6410
65
66
67### OH_PurgeableMemory_ModifyFunc
68
69
70```
71typedef bool(* OH_PurgeableMemory_ModifyFunc) (void *, size_t, void *)
72```
73
74**Description**
75
76Defines the function for rebuilding purgeable memory data.
77
78**Parameters**
79
80| Name| Description|
81| -------- | -------- |
82| void \* | Pointer to the address of purgeable memory.|
83| size_t | Size of the memory data to rebuild.|
84| void \* | Pointer to the parameters used for rebuilding.|
85
86**Returns**
87
88Returns a success message if the operation is successful; returns a failure message otherwise.
89
90**Since**
91
9210
93
94
95## Function Description
96
97
98### OH_PurgeableMemory_AppendModify()
99
100
101```
102bool OH_PurgeableMemory_AppendModify (OH_PurgeableMemory * purgObj, OH_PurgeableMemory_ModifyFunc func, void * funcPara )
103```
104
105**Description**
106
107Adds a function for modifying a **PurgeableMemory** object.
108
109**Parameters**
110
111| Name| Description|
112| -------- | -------- |
113| purgObj | Pointer to the **PurgeableMemory** object.|
114| func | Function pointer to the modify function, which is used for further modification after the purgeable memory data is rebuilt.|
115| funcPara | Pointer to the parameters of the modify function.|
116
117**Returns**
118
119Returns a success message if the operation is successful; returns a failure message otherwise.
120
121**Since**
122
12310
124
125
126### OH_PurgeableMemory_BeginRead()
127
128
129```
130bool OH_PurgeableMemory_BeginRead (OH_PurgeableMemory * purgObj)
131```
132
133**Description**
134
135Starts a read operation on a **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.
136
137**Parameters**
138
139| Name| Description|
140| -------- | -------- |
141| purgObj | Pointer to the **PurgeableMemory** object.|
142
143**Returns**
144
145Returns a success message if the purgeable memory data is ready; returns a failure message if purgeable memory has been reclaimed and fails to be rebuilt.
146
147**Since**
148
14910
150
151
152### OH_PurgeableMemory_BeginWrite()
153
154
155```
156bool OH_PurgeableMemory_BeginWrite (OH_PurgeableMemory * purgObj)
157```
158
159**Description**
160
161Begins a write operation on the **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.
162
163**Parameters**
164
165| Name| Description|
166| -------- | -------- |
167| purgObj | Pointer to the **PurgeableMemory** object.|
168
169**Returns**
170
171Returns a success message if the purgeable memory data is ready; returns a failure message if purgeable memory has been reclaimed and fails to be rebuilt.
172
173**Since**
174
17510
176
177
178### OH_PurgeableMemory_ContentSize()
179
180
181```
182size_t OH_PurgeableMemory_ContentSize (OH_PurgeableMemory * purgObj)
183```
184
185**Description**
186
187Obtains the memory data size of a **PurgeableMemory** object.
188
189**Parameters**
190
191| Name| Description|
192| -------- | -------- |
193| purgObj | Pointer to the **PurgeableMemory** object.|
194
195**Returns**
196
197Returns the memory data size.
198
199**Since**
200
20110
202
203
204### OH_PurgeableMemory_Create()
205
206
207```
208OH_PurgeableMemory* OH_PurgeableMemory_Create (size_t size, OH_PurgeableMemory_ModifyFunc func, void * funcPara )
209```
210
211**Description**
212
213Creates a **PurgeableMemory** object.
214
215**Parameters**
216
217| Name| Description|
218| -------- | -------- |
219| size | Size of the **PurgeableMemory** object.|
220| func | Function pointer to the rebuilding function, which is used to restore the reclaimed purgeable memory data.|
221| funcPara | Pointer to the parameters of the rebuilding function.|
222
223**Returns**
224
225Returns the **PurgeableMemory** object.
226
227**Since**
228
22910
230
231
232### OH_PurgeableMemory_Destroy()
233
234
235```
236bool OH_PurgeableMemory_Destroy (OH_PurgeableMemory * purgObj)
237```
238
239**Description**
240
241Destroys a **PurgeableMemory** object.
242
243**Parameters**
244
245| Name| Description|
246| -------- | -------- |
247| purgObj | Pointer to the **PurgeableMemory** object.|
248
249**Returns**
250
251Returns a success message if the operation is successful; returns a failure message otherwise. If no value is passed, a failure message is returned. If a success message is returned, the value of **purgObj** will be cleared to avoid Use-After-Free (UAF).
252
253**Since**
254
25510
256
257
258### OH_PurgeableMemory_EndRead()
259
260
261```
262void OH_PurgeableMemory_EndRead (OH_PurgeableMemory * purgObj)
263```
264
265**Description**
266
267Ends a read operation on a **PurgeableMemory** object. Now the system can reclaim purgeable memory.
268
269**Parameters**
270
271| Name| Description|
272| -------- | -------- |
273| purgObj | Pointer to the **PurgeableMemory** object.|
274
275**Since**
276
27710
278
279
280### OH_PurgeableMemory_EndWrite()
281
282
283```
284void OH_PurgeableMemory_EndWrite (OH_PurgeableMemory * purgObj)
285```
286
287**Description**
288
289Ends a write operation on the **PurgeableMemory** object. Now the system can reclaim purgeable memory.
290
291**Parameters**
292
293| Name| Description|
294| -------- | -------- |
295| purgObj | Pointer to the **PurgeableMemory** object.|
296
297**Since**
298
29910
300
301
302### OH_PurgeableMemory_GetContent()
303
304
305```
306void* OH_PurgeableMemory_GetContent (OH_PurgeableMemory * purgObj)
307```
308
309**Description**
310
311Obtains the memory data of a **PurgeableMemory** object.
312
313**Parameters**
314
315| Name| Description|
316| -------- | -------- |
317| purgObj | Pointer to the **PurgeableMemory** object.|
318
319**Returns**
320
321Returns the pointer to the purgeable memory address.
322
323**Since**
324
32510
326