@@ -260,20 +260,37 @@ libc_bitflags!{
260
260
}
261
261
}
262
262
263
- /// Locks all memory pages that contain part of the address range with `length` bytes starting at
264
- /// `addr`. Locked pages never move to the swap area.
263
+ /// Locks all memory pages that contain part of the address range with `length`
264
+ /// bytes starting at `addr`.
265
+ ///
266
+ /// Locked pages never move to the swap area.
267
+ ///
268
+ /// # Safety
269
+ ///
270
+ /// `addr` must meet all the requirements described in the `mlock(2)` man page.
265
271
pub unsafe fn mlock ( addr : * const c_void , length : size_t ) -> Result < ( ) > {
266
272
Errno :: result ( libc:: mlock ( addr, length) ) . map ( drop)
267
273
}
268
274
269
- /// Unlocks all memory pages that contain part of the address range with `length` bytes starting at
270
- /// `addr`.
275
+ /// Unlocks all memory pages that contain part of the address range with
276
+ /// `length` bytes starting at `addr`.
277
+ ///
278
+ /// # Safety
279
+ ///
280
+ /// `addr` must meet all the requirements described in the `munlock(2)` man
281
+ /// page.
271
282
pub unsafe fn munlock ( addr : * const c_void , length : size_t ) -> Result < ( ) > {
272
283
Errno :: result ( libc:: munlock ( addr, length) ) . map ( drop)
273
284
}
274
285
275
- /// Locks all memory pages mapped into this process' address space. Locked pages never move to the
276
- /// swap area.
286
+ /// Locks all memory pages mapped into this process' address space.
287
+ ///
288
+ /// Locked pages never move to the swap area.
289
+ ///
290
+ /// # Safety
291
+ ///
292
+ /// `addr` must meet all the requirements described in the `mlockall(2)` man
293
+ /// page.
277
294
pub fn mlockall ( flags : MlockAllFlags ) -> Result < ( ) > {
278
295
unsafe { Errno :: result ( libc:: mlockall ( flags. bits ( ) ) ) } . map ( drop)
279
296
}
@@ -283,8 +300,11 @@ pub fn munlockall() -> Result<()> {
283
300
unsafe { Errno :: result ( libc:: munlockall ( ) ) } . map ( drop)
284
301
}
285
302
286
- /// Calls to mmap are inherently unsafe, so they must be made in an unsafe block. Typically
287
- /// a higher-level abstraction will hide the unsafe interactions with the mmap'd region.
303
+ /// allocate memory, or map files or devices into memory
304
+ ///
305
+ /// # Safety
306
+ ///
307
+ /// See the `mmap(2)` man page for detailed requirements.
288
308
pub unsafe fn mmap ( addr : * mut c_void , length : size_t , prot : ProtFlags , flags : MapFlags , fd : RawFd , offset : off_t ) -> Result < * mut c_void > {
289
309
let ret = libc:: mmap ( addr, length, prot. bits ( ) , flags. bits ( ) , fd, offset) ;
290
310
@@ -295,10 +315,22 @@ pub unsafe fn mmap(addr: *mut c_void, length: size_t, prot: ProtFlags, flags: Ma
295
315
}
296
316
}
297
317
318
+ /// remove a mapping
319
+ ///
320
+ /// # Safety
321
+ ///
322
+ /// `addr` must meet all the requirements described in the `munmap(2)` man
323
+ /// page.
298
324
pub unsafe fn munmap ( addr : * mut c_void , len : size_t ) -> Result < ( ) > {
299
325
Errno :: result ( libc:: munmap ( addr, len) ) . map ( drop)
300
326
}
301
327
328
+ /// give advice about use of memory
329
+ ///
330
+ /// # Safety
331
+ ///
332
+ /// See the `madvise(2)` man page. Take special care when using
333
+ /// `MmapAdvise::MADV_FREE`.
302
334
pub unsafe fn madvise ( addr : * mut c_void , length : size_t , advise : MmapAdvise ) -> Result < ( ) > {
303
335
Errno :: result ( libc:: madvise ( addr, length, advise as i32 ) ) . map ( drop)
304
336
}
@@ -332,6 +364,12 @@ pub unsafe fn mprotect(addr: *mut c_void, length: size_t, prot: ProtFlags) -> Re
332
364
Errno :: result ( libc:: mprotect ( addr, length, prot. bits ( ) ) ) . map ( drop)
333
365
}
334
366
367
+ /// synchronize a mapped region
368
+ ///
369
+ /// # Safety
370
+ ///
371
+ /// `addr` must meet all the requirements described in the `msync(2)` man
372
+ /// page.
335
373
pub unsafe fn msync ( addr : * mut c_void , length : size_t , flags : MsFlags ) -> Result < ( ) > {
336
374
Errno :: result ( libc:: msync ( addr, length, flags. bits ( ) ) ) . map ( drop)
337
375
}
0 commit comments