From 6218acae140f2ae425d6de582d6ebb67554f8d98 Mon Sep 17 00:00:00 2001
From: "Adam C. Foltzer" <acfoltzer@acfoltzer.net>
Date: Wed, 19 Dec 2018 13:13:00 -0800
Subject: [PATCH] add doctest for `sys::mman::mprotect`

---
 src/sys/mman.rs | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/sys/mman.rs b/src/sys/mman.rs
index f1377d901e..cd1b43edc3 100644
--- a/src/sys/mman.rs
+++ b/src/sys/mman.rs
@@ -258,6 +258,29 @@ pub unsafe fn madvise(addr: *mut c_void, length: size_t, advise: MmapAdvise) ->
     Errno::result(libc::madvise(addr, length, advise as i32)).map(drop)
 }
 
+/// Set protection of memory mapping.
+///
+/// See [`mprotect(3)`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/mprotect.html) for
+/// details.
+///
+/// # Safety Calls to `mprotect` are inherently unsafe, as changes to memory protections can lead to
+/// SIGSEGVs.
+///
+/// ```
+/// # use nix::libc::size_t;
+/// # use nix::sys::mman::{mmap, mprotect, MapFlags, ProtFlags};
+/// # use std::ptr;
+/// const ONE_K: size_t = 1024;
+/// let mut slice: &mut [u8] = unsafe {
+///     let mem = mmap(ptr::null_mut(), ONE_K, ProtFlags::PROT_NONE,
+///                    MapFlags::MAP_ANONYMOUS | MapFlags::MAP_PRIVATE, -1, 0).unwrap();
+///     mprotect(mem, ONE_K, ProtFlags::PROT_READ | ProtFlags::PROT_WRITE).unwrap();
+///     std::slice::from_raw_parts_mut(mem as *mut u8, ONE_K)
+/// };
+/// assert_eq!(slice[0], 0x00);
+/// slice[0] = 0xFF;
+/// assert_eq!(slice[0], 0xFF);
+/// ```
 pub unsafe fn mprotect(addr: *mut c_void, length: size_t, prot: ProtFlags) -> Result<()> {
     Errno::result(libc::mprotect(addr, length, prot.bits())).map(drop)
 }