improve docs

diff --git a/src/shims/foreign_items/posix/linux.rs b/src/shims/foreign_items/posix/linux.rs
index 098d05663543e2cd4b4fbb50fd0bc551f47cfa90..9da54b6d4070259dad97781e9cf3d9e7c0fb2a76 100644 (file)
--- a/src/shims/foreign_items/posix/linux.rs
+++ b/src/shims/foreign_items/posix/linux.rs
@@ -19,6 +19,9 @@ fn emulate_foreign_item_by_name(
             }
 
             // File related shims
+
+            // The only reason this is not in the `posix` module is because the `macos` item has a
+            // different name.
             "close" => {
                 let result = this.close(args[0])?;
                 this.write_scalar(Scalar::from_int(result, dest.layout.size), dest)?;
@@ -56,6 +59,8 @@ fn emulate_foreign_item_by_name(
                         // so skip over it.
                         getrandom(this, &args[1..], dest)?;
                     }
+                    // `statx` is used by `libstd` to retrieve metadata information in `linux`
+                    // instead of using `stat`,`lstat` or `fstat` as in the `macos` platform.
                     id if id == sys_statx => {
                         // The first argument is the syscall id,
                         // so skip over it.

diff --git a/src/shims/foreign_items/posix/macos.rs b/src/shims/foreign_items/posix/macos.rs
index 3698df95bd199eba61a46f884dcf63a755d388bc..25ac7e93867f256e29cc06ad081ba2befeadf332 100644 (file)
--- a/src/shims/foreign_items/posix/macos.rs
+++ b/src/shims/foreign_items/posix/macos.rs
@@ -19,6 +19,9 @@ fn emulate_foreign_item_by_name(
             }
 
             // File related shims
+
+            // The only reason this is not in the `posix` module is because the `linux` item has a
+            // different name.
             "close$NOCANCEL" => {
                 let result = this.close(args[0])?;
                 this.write_scalar(Scalar::from_int(result, dest.layout.size), dest)?;

diff --git a/src/shims/fs.rs b/src/shims/fs.rs
index afa71f654075a66bf1ee1462375cb0d25a55e7de..b3d8d6a0ac7ffe645e2e4436ec6a6fbc48dc5606 100644 (file)
--- a/src/shims/fs.rs
+++ b/src/shims/fs.rs
@@ -383,6 +383,10 @@ fn macos_fstat(
         macos_stat_write_buf(this, metadata, buf_op)
     }
 
+    /// Emulate `stat` or `lstat` on the `macos` platform. This function is not intended to be
+    /// called directly from `emulate_foreign_item_by_name`, so it does not check if isolation is
+    /// disabled or if the target platform is the correct one. Please use `macos_stat` or
+    /// `macos_lstat` instead.
     fn macos_stat_or_lstat(
         &mut self,
         follow_symlink: bool,