Add option to filter files by inode number

Add the option on Unix systems to filter files by their inode number.

The Windows equivalent FileIndex is not yet stabilized, see
rust-lang/rust#63010.

This is especially useful to debug audit records, e.g.:

    Jan 30 17:48:55 laptop audit: PATH item=0 name="pulse" inode=7340042 dev=fe:03 mode=040700 ouid=1001 ogid=1001 rdev=00:00 obj=system_u:object_r:unlabeled_t:s0 nametype=NORMAL cap_fp=0 cap_fi=0 cap_fe=0 cap_fver=0 cap_frootid=0

Closes: sharkdp#880

Author: cgzones

README.md

@@ -320,6 +320,7 @@ Options:
                                    executable (x), empty (e), socket (s), pipe (p), char-device
                                    (c), block-device (b)
   -e, --extension <ext>            Filter by file extension
+      --inum <num>                 Filter by inode number
   -S, --size <size>                Limit results based on the size of files
       --changed-within <date|dur>  Filter by file modification time (newer than)
       --changed-before <date|dur>  Filter by file modification time (older than)

doc/fd.1

@@ -297,6 +297,9 @@ Always output hyperlink escapes, regardless of color settings.
 .BI "\-j, \-\-threads " num
 Set number of threads to use for searching & executing (default: number of available CPU cores).
 .TP
+.BI "\-\-inum " num
+Filter files by their inode number.
+.TP
 .BI "\-S, \-\-size " size
 Limit results based on the size of files using the format
 .I <+-><NUM><UNIT>

src/cli.rs

@@ -374,6 +374,20 @@ pub struct Opts {
     )]
     pub extensions: Option<Vec<String>>,
 
+    /// Filter files by their inode number.
+    /// Format: [inum].
+    ///
+    /// Examples:
+    /// {n}    --inum 4242
+    #[cfg(unix)]
+    #[arg(
+        long,
+        value_name = "inode-number",
+        help = "Filter by inode number",
+        long_help
+    )]
+    pub inum: Option<u64>,
+
     /// Limit results based on the size of files using the format <+-><NUM><UNIT>.
     ///    '+': file size must be greater than or equal to this
     ///    '-': file size must be less than or equal to this

src/config.rs

@@ -48,6 +48,10 @@ pub struct Config {
     /// Whether elements of output should be separated by a null character
     pub null_separator: bool,
 
+    #[cfg(unix)]
+    /// The inode number to search for.
+    pub inode_number: Option<u64>,
+
     /// The maximum search depth, or `None` if no maximum search depth should be set.
     ///
     /// A depth of `1` includes all files under the current directory, a depth of `2` also includes

src/main.rs

@@ -208,6 +208,8 @@ fn construct_config(mut opts: Opts, pattern_regexps: &[String]) -> Result<Config
         .unwrap_or_else(|| std::path::MAIN_SEPARATOR.to_string());
     check_path_separator_length(path_separator.as_deref())?;
 
+    #[cfg(unix)]
+    let inode_number = std::mem::take(&mut opts.inum);
     let size_limits = std::mem::take(&mut opts.size);
     let time_constraints = extract_time_constraints(&opts)?;
     #[cfg(unix)]
@@ -315,6 +317,8 @@ fn construct_config(mut opts: Opts, pattern_regexps: &[String]) -> Result<Config
         batch_size: opts.batch_size,
         exclude_patterns: opts.exclude.iter().map(|p| String::from("!") + p).collect(),
         ignore_files: std::mem::take(&mut opts.ignore_file),
+        #[cfg(unix)]
+        inode_number,
         size_constraints: size_limits,
         time_constraints,
         #[cfg(unix)]

src/walk.rs

@@ -2,6 +2,8 @@ use std::borrow::Cow;
 use std::ffi::OsStr;
 use std::io::{self, Write};
 use std::mem;
+#[cfg(unix)]
+use std::os::unix::fs::MetadataExt;
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, MutexGuard};
@@ -551,6 +553,18 @@ impl WorkerState {
                     }
                 }
 
+                // Filter out unwanted inode numbers.
+                #[cfg(unix)]
+                if let Some(inode_number) = config.inode_number {
+                    if let Some(metadata) = entry.metadata() {
+                        if inode_number != metadata.ino() {
+                            return ignore::WalkState::Continue;
+                        }
+                    } else {
+                        return ignore::WalkState::Continue;
+                    }
+                }
+
                 #[cfg(unix)]
                 {
                     if let Some(ref owner_constraint) = config.owner_constraint {