1//! The `madvise` function.
2//!
3//! # Safety
4//!
5//! `madvise` operates on a raw pointer. Some forms of `madvise` may
6//! mutate the memory or have other side effects.
7#![allow(unsafe_code)]
8
9use crate::{backend, io};
10use core::ffi::c_void;
11
12pub use backend::mm::types::Advice;
13
14/// `posix_madvise(addr, len, advice)`—Declares an expected access pattern
15/// for a memory-mapped file.
16///
17/// # Safety
18///
19/// `addr` must be a valid pointer to memory that is appropriate to call
20/// `posix_madvise` on. Some forms of `advice` may mutate the memory or evoke a
21/// variety of side-effects on the mapping and/or the file.
22///
23/// # References
24/// - [POSIX]
25/// - [Linux `madvise`]
26/// - [Linux `posix_madvise`]
27/// - [Apple]
28/// - [FreeBSD]
29/// - [NetBSD]
30/// - [OpenBSD]
31/// - [DragonFly BSD]
32/// - [illumos]
33/// - [glibc]
34///
35/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_madvise.html
36/// [Linux `madvise`]: https://man7.org/linux/man-pages/man2/madvise.2.html
37/// [Linux `posix_madvise`]: https://man7.org/linux/man-pages/man3/posix_madvise.3.html
38/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/madvise.2.html
39/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=madvise&sektion=2
40/// [NetBSD]: https://man.netbsd.org/madvise.2
41/// [OpenBSD]: https://man.openbsd.org/madvise.2
42/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=madvise&section=2
43/// [illumos]: https://illumos.org/man/3C/madvise
44/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Memory_002dmapped-I_002fO.html#index-madvise
45#[inline]
46#[doc(alias = "posix_madvise")]
47pub unsafe fn madvise(addr: *mut c_void, len: usize, advice: Advice) -> io::Result<()> {
48 backend::mm::syscalls::madvise(addr, len, advice)
49}
50