From 499620538c3144d75654c851606fa8c7f9b579fa Mon Sep 17 00:00:00 2001
From: Ralf Jung <post@ralfj.de>
Date: Fri, 6 Sep 2024 10:22:32 +0200
Subject: [PATCH] Add links to safety docs in map methods (#121)

---
 src/lib.rs | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 6ff9e366..94dba241 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -338,6 +338,10 @@ impl MmapOptions {
 
     /// Creates a read-only memory map backed by a file.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapOptions] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -373,6 +377,10 @@ impl MmapOptions {
 
     /// Creates a readable and executable memory map backed by a file.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapOptions] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -386,6 +394,10 @@ impl MmapOptions {
 
     /// Creates a writeable memory map backed by a file.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapOptions] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -429,6 +441,10 @@ impl MmapOptions {
     /// Data written to the memory map will not be visible by other processes,
     /// and will not be carried through to the underlying file.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapOptions] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -457,6 +473,10 @@ impl MmapOptions {
 
     /// Creates a copy-on-write read-only memory map backed by a file.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapOptions] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -596,6 +616,10 @@ impl Mmap {
     ///
     /// This is equivalent to calling `MmapOptions::new().map(file)`.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][Mmap] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a
@@ -789,6 +813,9 @@ impl fmt::Debug for Mmap {
 ///
 /// This struct never hands out references to its interior, only raw pointers.
 /// This can be helpful when creating shared memory maps between untrusted processes.
+///
+/// For the safety concerns that arise when converting these raw pointers to references,
+/// see the [`Mmap`] safety documentation.
 pub struct MmapRaw {
     inner: MmapInner,
 }
@@ -1058,6 +1085,10 @@ impl MmapMut {
     ///
     /// This is equivalent to calling `MmapOptions::new().map_mut(file)`.
     ///
+    /// # Safety
+    ///
+    /// See the [type-level][MmapMut] docs for why this function is unsafe.
+    ///
     /// # Errors
     ///
     /// This method returns an error when the underlying system call fails, which can happen for a