Struct FileBuffer 

pub struct FileBuffer { /* private fields */ }

A memory-mapped file buffer for efficient file access

This struct provides safe access to file contents through memory mapping, which avoids loading the entire file into memory while providing fast random access to file data.

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;
let data = buffer.as_slice();
println!("File size: {} bytes", data.len());

Implementations

impl FileBuffer

pub const MAX_FILE_SIZE: u64

Maximum file size that can be processed (1 GB)

This limit prevents memory exhaustion attacks and ensures reasonable processing times. Files larger than this are likely not suitable for magic rule evaluation and may indicate malicious input.

pub fn new(path: &Path) -> Result<Self, IoError>

Creates a new memory-mapped file buffer

Arguments

• path - Path to the file to be mapped

Returns

Returns a FileBuffer on success, or an IoError if the file cannot be opened or mapped.

Errors

This function will return an error if:

• The file does not exist or cannot be opened
• The file cannot be memory-mapped
• The file is empty
• The file is larger than the maximum allowed size
• File metadata cannot be read

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;

pub fn from_path_and_metadata( path: &Path, metadata: &Metadata, ) -> Result<Self, IoError>

Creates a new FileBuffer using caller-supplied metadata.

This is a performance-focused alternative to FileBuffer::new for callers that have already called std::fs::metadata on path (for example, to check the empty-file case before constructing the buffer). It skips the internal std::fs::canonicalize + second metadata round-trip that FileBuffer::new performs, eliminating two redundant syscalls on the hot path of MagicDatabase::evaluate_file.

Security

This constructor deliberately skips std::fs::canonicalize for performance. Symlink resolution and path canonicalization are the caller’s responsibility. In adversarial environments (untrusted file paths), prefer FileBuffer::new or [MagicDatabase::evaluate_buffer] instead.

The caller is responsible for having read metadata via a path that makes sense for their security model. The same structural checks (regular file, non-empty, under MAX_FILE_SIZE) are still applied against the supplied metadata.

Errors

Returns the same IoError variants as FileBuffer::new for validation failures, file open failures, and mmap failures.

pub fn as_slice(&self) -> &[u8]

Returns the file contents as a byte slice

This provides safe access to the memory-mapped file data without copying the contents.

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;
let data = buffer.as_slice();
println!("First byte: 0x{:02x}", data[0]);

pub fn path(&self) -> &Path

Returns the path of the file

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;
println!("File path: {}", buffer.path().display());

pub fn len(&self) -> usize

Returns the size of the file in bytes

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;
println!("File size: {} bytes", buffer.len());

pub fn is_empty(&self) -> bool

Returns true if the file is empty

Note: This should never return true for a successfully created FileBuffer, as empty files are rejected during construction.

Examples

use libmagic_rs::io::FileBuffer;
use std::path::Path;

let buffer = FileBuffer::new(Path::new("example.bin"))?;
assert!(!buffer.is_empty()); // Should always be false for valid buffers

Trait Implementations

impl Debug for FileBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.