Filelocksmith

https://docs.rs/filelocksmith
Admin
Filelocksmith is a Rust library that reliably finds and quits processes that are locking files or...
Tokens:11,746
Snippets:99
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Process Path by PID

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.pid_to_process_path.html

This example demonstrates how to use `pid_to_process_path` to retrieve the path of a process. It also shows how to handle cases where the process might not be found or accessible.

```rust
1fn main() {
    println!("{:?}", filelocksmith::is_process_elevated());
    println!("{:?}", filelocksmith::set_debug_privilege());
    println!("{:?}", filelocksmith::pid_to_process_path(12352));
    let pids = filelocksmith::find_processes_locking_path(r"C:\filelocksmith-test");
    println!("{:?}", pids);

    for pid in &pids {
        println!("[{}] {{:?}}", pid, filelocksmith::pid_to_process_path(*pid));
    }

    if filelocksmith::quit_processes(pids) {
        println!("Processes quit successfully");
    }
}
```

--------------------------------

### Documenting a Function with an Example

Source: https://docs.rs/filelocksmith/latest/scrape-examples-help.html

Illustrates how a documented public function in a library and a separate example calling that function are combined by Rustdoc.

```rust
// src/lib.rs
pub fn a_func() {}
```

```rust
// examples/ex.rs
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Find and Quit Processes Locking a File

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

This example demonstrates how to find processes locking a specific file path and then quit those processes. Ensure the program has necessary permissions to detect and terminate other processes.

```rust
use filelocksmith::{find_processes_locking_path, quit_processes, pid_to_process_path};

let path = "C:\\path\\to\\file.txt";
let pids = find_processes_locking_path(path);

// print paths of processes locking the file
for pid in &pids {
   println!("[{}] {:?}", pid, pid_to_process_path(*pid));
}

// quit the processes locking the file
if quit_processes(pids) {
 println!("Processes quit successfully");
}

```

--------------------------------

### Example Usage of set_debug_privilege

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.set_debug_privilege.html

This example demonstrates the usage of set_debug_privilege within a larger context of filelocksmith operations. It first checks if the process is elevated, then attempts to set the debug privilege, and subsequently uses other filelocksmith functions to find and quit processes locking a specific file.

```rust
fn main() {
    println!("{:?}", filelocksmith::is_process_elevated());
    println!("{:?}", filelocksmith::set_debug_privilege());
    println!("{:?}", filelocksmith::pid_to_process_path(12352));
    let pids = filelocksmith::find_processes_locking_path(r"C:\filelocksmith-test");
    println!("{:?}", pids);

    for pid in &pids {
        println!("[{}] {:?}", pid, filelocksmith::pid_to_process_path(*pid));
    }

    if filelocksmith::quit_processes(pids) {
        println!("Processes quit successfully");
    }
}
```

--------------------------------

### Get Process Modules in Rust

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Retrieves a list of module paths for a given process ID. It opens the process, enumerates its modules, and attempts to get the path for each module.

```rust
fn get_process_modules(pid: u32) -> Vec<Vec<u16>> {
    let process = unsafe { OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, 0, pid) };
    if process.is_null() {
        return Vec::new();
    }
    let _guard = SafeHandle::from_raw(process);

    let mut modules: Vec<HANDLE> = vec![ptr::null_mut(); 1024];
    let mut cb_needed = 0u32;
    let ok = unsafe {
        EnumProcessModules(
            process,
            modules.as_mut_ptr(),
            (modules.len() * std::mem::size_of::<HANDLE>()) as u32,
            &mut cb_needed,
        )
    };
    if ok == 0 {
        return Vec::new();
    }
    let count = cb_needed as usize / std::mem::size_of::<HANDLE>();
    modules.truncate(count);

    let mut paths = Vec::with_capacity(count);
    let mut buf = vec![0u16; 1024];
```

--------------------------------

### Get Process Path from PID on Windows

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Retrieves the full path of an executable for a given process ID. Returns None if the process is not found or access is denied. Requires `PROCESS_QUERY_INFORMATION` and `PROCESS_VM_READ` access rights.

```rust
pub fn pid_to_process_path(pid: usize) -> Option<String> {
    #[cfg(windows)]
    {
        use std::ptr;
        use windows_sys::Win32::System::ProcessStatus::GetModuleFileNameExW;
        use windows_sys::Win32::System::Threading::{
            OpenProcess, PROCESS_QUERY_INFORMATION, PROCESS_VM_READ,
        };

        let process = unsafe { OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, 0, pid as u32) };
        let process = ntapi::SafeHandle::from_raw(process)?;

        let mut buf = vec![0u16; 65536];
        let len = unsafe {
            GetModuleFileNameExW(process.raw(), ptr::null_mut(), buf.as_mut_ptr(), buf.len() as u32)
        };
        if len == 0 {
            return None;
        }
        buf.truncate(len as usize);
        Some(String::from_utf16_lossy(&buf))
    }
    #[cfg(not(windows))]
    {
        let _ = pid;
        None
    }
}
```

--------------------------------

### Convert Wide Path to Kernel Name

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Converts a wide character string path to a kernel-readable name. It opens the file to obtain a handle and then uses `file_handle_to_kernel_name` to get the kernel name. Returns `None` if the file is not a disk file.

```rust
fn wide_path_to_kernel_name(wide: &[u16], ntdll: &NtdllFunctions) -> Option<Vec<u16>> {
    let mut with_null: Vec<u16> = wide.to_vec();
    with_null.push(0);
    let handle = unsafe {
        CreateFileW(
            with_null.as_ptr(),
            0,
            FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
            ptr::null(),
            OPEN_EXISTING,
            FILE_FLAG_BACKUP_SEMANTICS,
            ptr::null_mut(),
        )
    };
    let handle = SafeHandle::from_raw_file(handle)?;
    unsafe {
        if GetFileType(handle.raw()) != FILE_TYPE_DISK {
            return None;
        }
    }
    file_handle_to_kernel_name(handle.raw(), ntdll, &mut vec![0u8; DEFAULT_BUFFER_SIZE])
}
```

--------------------------------

### Find Processes for Paths

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

The main entry point to find processes that have opened any of the specified paths. It first converts the input paths to kernel names and then iterates through process handles and loaded modules to identify matching processes.

```rust
pub fn find_processes_for_paths(paths: &[&Path]) -> Vec<usize> {
    let ntdll = match NtdllFunctions::load() {
        Some(n) => n,
        None => return Vec::new(),
    };

    let mut file_kernel_names: HashSet<Vec<u16>> = HashSet::new();
    let mut dir_kernel_names: Vec<Vec<u16>> = Vec::new();

    for &path in paths {
        if let Some(kn) = path_to_kernel_name(path, &ntdll) {
            if path.is_dir() {
                dir_kernel_names.push(kn);
            } else {
                file_kernel_names.insert(kn);
            }
        }
    }

    let mut matching_pids: HashSet<usize> = HashSet::new();

    for info in enumerate_handles(&ntdll) {
        if kernel_paths_match(&info.kernel_file_name, &file_kernel_names, &dir_kernel_names) {
            matching_pids.insert(info.pid);
        }
    }

    // Scan loaded modules of all processes.
    let mut all_pids = vec![0u32; 4096];
    let mut cb_needed = 0u32;
    let ok = unsafe {
        EnumProcesses(
            all_pids.as_mut_ptr(),
            (all_pids.len() * std::mem::size_of::<u32>()) as u32,
            &mut cb_needed,
        )
    };
    if ok != 0 {
        let count = cb_needed as usize / std::mem::size_of::<u32>();
        all_pids.truncate(count);
        for &pid in &all_pids {
            if pid == 0 {
                continue;
            }
            for module_path in get_process_modules(pid) {
                if let Some(kn) = wide_path_to_kernel_name(&module_path, &ntdll) {
                    if kernel_paths_match(&kn, &file_kernel_names, &dir_kernel_names) {
                        matching_pids.insert(pid as usize);
                    }
                }
            }
        }
    }

    matching_pids.into_iter().collect()
}
```

--------------------------------

### nt_query_system_information_loop

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Continuously queries the system for information using a dynamically resizing buffer until successful or an error occurs.

```APIDOC
## nt_query_system_information_loop

### Description
This function repeatedly calls `ntdll.query_system_information` with a given class, automatically adjusting the buffer size if `STATUS_INFO_LENGTH_MISMATCH` is returned. It continues until the information is successfully retrieved or a maximum buffer size is exceeded, or an error occurs.

### Parameters
- `ntdll` (*&NtdllFunctions*) - A reference to the NtdllFunctions struct containing necessary NTDLL function pointers.
- `class` (*u32*) - The system information class to query.

### Returns
- `Option<Vec<u8>>` - Returns `Some(Vec<u8>)` containing the system information if successful, otherwise returns `None`.
```

--------------------------------

### Enable Debug Privileges on Windows

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

This function attempts to enable the SeDebugPrivilege for the current process. It is necessary for certain operations that require elevated permissions. Returns false if the privilege cannot be enabled.

```rust
pub fn has_debug_privileges() -> bool {
    #[cfg(windows)]
    {
        use std::mem::zeroed;
        use std::ptr;
        use windows_sys::Win32::Foundation::{CloseHandle, ERROR_NOT_ALL_ASSIGNED};
        use windows_sys::Win32::Security::{AdjustTokenPrivileges, SE_PRIVILEGE_ENABLED};
        use windows_sys::Win32::System::Threading::{
            GetCurrentProcess,
            OpenProcessToken, TOKEN_ADJUST_PRIVILEGES,
            LookupPrivilegeValueW, LUID_AND_ATTRIBUTES, TOKEN_PRIVILEGES,
        };

        const SE_DEBUG_NAME: &str = "SeDebugPrivilege";

        unsafe {
            let mut token: HANDLE = ptr::null_mut();
            if OpenProcessToken(GetCurrentProcess(), TOKEN_ADJUST_PRIVILEGES, &mut token) == 0 {
                return false;
            }

            let mut luid = std::mem::zeroed();
            if LookupPrivilegeValueW(ptr::null(), SE_DEBUG_NAME.as_ptr(), &mut luid) == 0 {
                CloseHandle(token);
                return false;
            }

            let tp = TOKEN_PRIVILEGES {
                PrivilegeCount: 1,
                Privileges: [LUID_AND_ATTRIBUTES {
                    Luid: luid,
                    Attributes: SE_PRIVILEGE_ENABLED,
                }],
            };

            let ok = AdjustTokenPrivileges(
                token,
                0,
                &tp,
                std::mem::size_of::<TOKEN_PRIVILEGES>() as u32,
                ptr::null_mut(),
                ptr::null_mut(),
            );

            let failed = ok == 0 || GetLastError() == ERROR_NOT_ALL_ASSIGNED;
            CloseHandle(token);
            !failed
        }
    }
    #[cfg(not(windows))]
    {
        false
    }
}
```

--------------------------------

### Set Debug Privilege for Current Process (Windows)

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Attempts to enable the SeDebugPrivilege for the current process on Windows. This privilege is often required to interact with or terminate processes that are not owned by the current user. Administrator privileges are needed for this to succeed.

```rust
pub fn set_debug_privilege() -> bool {
    #[cfg(windows)]
    {
        use std::ptr;
        use windows_sys::Win32::Foundation::{
            CloseHandle, GetLastError, HANDLE, ERROR_NOT_ALL_ASSIGNED,
        };
        use windows_sys::Win32::Security::{
            AdjustTokenPrivileges, LookupPrivilegeValueW, LUID_AND_ATTRIBUTES,
            SE_PRIVILEGE_ENABLED, TOKEN_ADJUST_PRIVILEGES, TOKEN_PRIVILEGES,
        };
        use windows_sys::Win32::System::Threading::GetCurrentProcess;

        #[link(name = "advapi32")]
        extern "system" {
            fn OpenProcessToken(
                process_handle: HANDLE,
                desired_access: u32,
                token_handle: *mut HANDLE,
            ) -> i32;
        }

        // "SeDebugPrivilege\0"
        const SE_DEBUG_NAME: [u16; 17] = [

```

--------------------------------

### Define SystemHandleTableEntryInfoEx Structure

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Defines the undocumented SystemHandleTableEntryInfoEx structure used for querying handle information.

```rust
#[repr(C)]
pub struct SystemHandleTableEntryInfoEx {
    pub object: *mut c_void,
    pub unique_process_id: usize,
    pub handle_value: usize,
    pub granted_access: u32,
    pub creator_back_trace_index: u16,
    pub object_type_index: u16,
    pub handle_attributes: u32,
    pub reserved: u32,
}
```

--------------------------------

### Looping NT API Query System Information

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Repeatedly queries NT system information until a buffer of sufficient size is allocated. Handles buffer resizing and error conditions.

```rust
pub fn nt_query_system_information_loop(ntdll: &NtdllFunctions, class: u32) -> Option<Vec<u8>> {
    let mut size = DEFAULT_BUFFER_SIZE;
    loop {
        let mut buffer = vec![0u8; size];
        let mut return_length = 0u32;
        let status = unsafe {
            ntdll.query_system_information(
                class,
                buffer.as_mut_ptr().cast(),
                size as u32,
                &mut return_length,
            )
        };

        if status == STATUS_INFO_LENGTH_MISMATCH {
            size *= 2;
            if size > MAX_BUFFER_SIZE {
                return None;
            }
            continue;
        }

        if status < 0 {
            return None;
        }

        return Some(buffer);
    }
}
```

--------------------------------

### Enumerate File Handles in Rust

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Iterates through system handles to identify and collect information about file handles. It uses Windows API calls to query object types and retrieve kernel names for disk files.

```rust
fn enumerate_handles(ntdll: &NtdllFunctions) -> Vec<HandleInfo> {
    let buffer = match nt_query_system_information_loop(ntdll, SYSTEM_EXTENDED_HANDLE_INFORMATION) {
        Some(b) => b,
        None => return Vec::new(),
    };

    let info = buffer.as_ptr() as *const SystemHandleInformationEx;
    let handle_count = unsafe { (*info).number_of_handles };

    let state = SharedState {
        ntdll,
        handle_info_ptr: info,
        handle_count,
        current_index: AtomicUsize::new(0),
        current_dup_handle: AtomicUsize::new(0),
        results: UnsafeCell::new(Vec::new()),
        pid_to_handle: UnsafeCell::new(HashMap::new()),
        object_info_buffer: UnsafeCell::new(vec![0u8; DEFAULT_BUFFER_SIZE]),
    };
    let state_ptr = &state as *const SharedState as *mut c_void;

    let mut i: usize = 0;
    while i < handle_count {
        state.current_index.store(i, Ordering::Relaxed);

        let thread = unsafe {
            CreateThread(
                ptr::null(),
                0,
                Some(worker_thread_proc),
                state_ptr,
                0,
                ptr::null_mut(),
            )
        };
        if thread.is_null() {
            break;
        }

        let mut previous_i = i;
        loop {
            let wait = unsafe { WaitForSingleObject(thread, 200) };
            if wait == WAIT_OBJECT_0 {
                unsafe {
                    CloseHandle(thread);
                }
                i = state.current_index.load(Ordering::Relaxed);
                break;
            }

            let current = state.current_index.load(Ordering::Relaxed);
            if current <= previous_i {
                unsafe {
                    TerminateThread(thread, 1);
                    CloseHandle(thread);
                    let dangling = state.current_dup_handle.load(Ordering::Relaxed) as HANDLE;
                    if !dangling.is_null() {
                        CloseHandle(dangling);
                    }
                }
                i = current + 1;
                break;
            }
            previous_i = current;
        }
    }

    let pid_to_handle = unsafe { &*state.pid_to_handle.get() };
    for &h in pid_to_handle.values() {
        unsafe {
            CloseHandle(h);
        }
    }

    std::mem::take(unsafe { &mut *state.results.get() })
}
```

--------------------------------

### Define SystemHandleInformationEx Structure

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Defines the SystemHandleInformationEx structure, which contains an array of SystemHandleTableEntryInfoEx. The handles field is a flexible array member.

```rust
#[repr(C)]
pub struct SystemHandleInformationEx {
    pub number_of_handles: usize,
    pub reserved: usize,
    /// Flexible array member — access via pointer arithmetic.
    pub handles: [SystemHandleTableEntryInfoEx; 0],
}
```

--------------------------------

### Kernel Paths Match Logic

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Checks if a given kernel name matches any of the provided file or directory kernel names. It handles exact matches and directory matches, including cases where a trailing separator is needed.

```rust
fn kernel_paths_match(
    kernel_name: &[u16],
    file_kernel_names: &HashSet<Vec<u16>>,
    dir_kernel_names: &[Vec<u16>],
) -> bool {
    if file_kernel_names.contains(kernel_name) {
        return true;
    }
    for dir in dir_kernel_names {
        if kernel_name == dir.as_slice() {
            return true;
        }
        let needs_sep = !dir.is_empty() && *dir.last().unwrap() != b'\' as u16;
        if needs_sep {
            if kernel_name.len() > dir.len() + 1
                && kernel_name.starts_with(dir)
                && kernel_name[dir.len()] == b'\' as u16
            {
                return true;
            }
        } else if kernel_name.len() > dir.len() && kernel_name.starts_with(dir) {
            return true;
        }
    }
    false
}
```

--------------------------------

### NtdllFunctions Struct and Load Method

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Provides a struct to hold resolved NT API function pointers and a load method to dynamically resolve them from ntdll.dll. Returns None if any function lookup fails.

```rust
/// Resolved function pointers into ntdll.dll.
pub struct NtdllFunctions {
    query_system_information: NtQuerySystemInformationFn,
    query_object: NtQueryObjectFn,
}

impl NtdllFunctions {
    /// Resolve the NT functions from ntdll.dll. Returns `None` if any lookup fails.
    pub fn load() -> Option<Self> {
        // "ntdll.dll\0" as a null-terminated UTF-16 string
        const NTDLL: [u16; 10] = [110, 116, 100, 108, 108, 46, 100, 108, 108, 0];

        unsafe {
            let module = GetModuleHandleW(NTDLL.as_ptr());
            if module.is_null() {
                return None;
            }

            let qsi = GetProcAddress(module, b"NtQuerySystemInformation\0".as_ptr())?;
            let qo = GetProcAddress(module, b"NtQueryObject\0".as_ptr())?;

            Some(Self {
                query_system_information: std::mem::transmute(qsi),
                query_object: std::mem::transmute(qo),
            })
        }
    }

    pub unsafe fn query_system_information(
        &self,
        class: u32,
        buf: *mut c_void,
        len: u32,
        ret_len: *mut u32,
    ) -> i32 {
        (self.query_system_information)(class, buf, len, ret_len)
    }

    pub unsafe fn query_object(
        &self,
        handle: HANDLE,
        class: u32,
        buf: *mut c_void,
        len: u32,
        ret_len: *mut u32,
    ) -> i32 {
        (self.query_object)(handle, class, buf, len, ret_len)
    }
}
```

--------------------------------

### Find Processes Locking a Path (Windows)

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

This function finds processes locking a given file or folder path on Windows. It returns a vector of process IDs. Note that administrator privileges are required to detect all locking processes, especially if they are running with elevated permissions.

```rust
pub fn find_processes_locking_path<P: AsRef<Path>>(path: P) -> Vec<usize> {
    #[cfg(windows)]
    {
        handles::find_processes_for_paths(&[path.as_ref()])
    }
    #[cfg(not(windows))]
    {
        let _ = path;
        Vec::new()
    }
}

```

--------------------------------

### find_processes_locking_path

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.find_processes_locking_path.html

Finds processes locking a file or folder. Returns a list of process IDs. Note: If the current Rust process is not running as administrator, but the locking process is, the locking process will not be detected. Administrator privileges or SeDebugPrivilege are required for full detection.

```APIDOC
## find_processes_locking_path

### Description
Find processes locking a file or folder. Returns a list of process IDs.
If the current Rust process is not running as administrator, but the locking process is, the locking process will not be detected.
You can use `is_process_elevated` to check if the current process is running as administrator. Also, you can use `set_debug_privilege` to set the SeDebugPrivilege, which will allow the current process to detect all processes on the system. Note that `set_debug_privilege` also requires administrator privileges to work.

### Signature
```rust
pub fn find_processes_locking_path<P: AsRef<Path>>(path: P) -> Vec<usize>
```

### Parameters
#### Path Parameter
- **path** (P: AsRef<Path>) - The path to the file or folder to check for locking processes.

### Returns
- **Vec<usize>** - A vector containing the process IDs of the processes locking the specified path.

### Example
```rust
let pids = filelocksmith::find_processes_locking_path(r"C:\filelocksmith-test");
println!("{:?}", pids);

for pid in &pids {
    println!("[{}] {{:?}}", pid, filelocksmith::pid_to_process_path(*pid));
}
```
```

--------------------------------

### Add filelocksmith to Dependencies

Source: https://docs.rs/filelocksmith/latest/filelocksmith

Add the filelocksmith crate to your project's dependencies in Cargo.toml.

```toml
[dependencies]
filelocksmith = "0.1"
```

--------------------------------

### quit_processes

Source: https://docs.rs/filelocksmith/latest/filelocksmith/all.html

Attempts to terminate processes that are locking a specified file path.

```APIDOC
## quit_processes

### Description
Attempts to terminate processes that are locking a specified file path.

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path whose locking processes should be terminated.
```

--------------------------------

### pid_to_process_path

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.pid_to_process_path.html

Returns the full path of a process given its process ID. If the process is not found, or we do not have permission to access the process, this function will return None.

```APIDOC
## pid_to_process_path

### Description
Returns the full path of a process given its process ID. If the process is not found, or we do not have permission to access the process, this function will return None.

### Signature
```rust
pub fn pid_to_process_path(pid: usize) -> Option<String>
```

### Parameters
#### Path Parameters
- **pid** (usize) - Description: The process ID to look up.

### Response
- **Option<String>** - Returns `Some(String)` containing the process path if found and accessible, otherwise returns `None`.
```

--------------------------------

### SafeHandle

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

An RAII wrapper for Windows HANDLEs that automatically calls `CloseHandle` when dropped. It provides methods to safely wrap raw handles, ensuring proper cleanup.

```APIDOC
/// Owns a Windows `HANDLE` and calls `CloseHandle` on drop.
pub struct SafeHandle(HANDLE);

impl SafeHandle {
    /// Wrap a handle where 0 (NULL) **or** `INVALID_HANDLE_VALUE` means failure.
    pub fn from_raw(handle: HANDLE) -> Option<Self>;

    /// Wrap a handle where only `INVALID_HANDLE_VALUE` means failure (e.g. `CreateFileW`).
    pub fn from_raw_file(handle: HANDLE) -> Option<Self>;

    /// Returns the raw Windows HANDLE.
    pub fn raw(&self) -> HANDLE;
}

impl Drop for SafeHandle;

```

--------------------------------

### SafeHandle RAII Wrapper

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Implements a SafeHandle struct that wraps a Windows HANDLE and ensures CloseHandle is called when the handle is dropped, preventing resource leaks.

```rust
/// Owns a Windows `HANDLE` and calls `CloseHandle` on drop.
pub struct SafeHandle(HANDLE);

impl SafeHandle {
    /// Wrap a handle where 0 (NULL) **or** `INVALID_HANDLE_VALUE` means failure.
    pub fn from_raw(handle: HANDLE) -> Option<Self> {
        if handle.is_null() || handle == INVALID_HANDLE_VALUE {
            None
        } else {
            Some(Self(handle))
        }
    }

    /// Wrap a handle where only `INVALID_HANDLE_VALUE` means failure (e.g. `CreateFileW`).
    pub fn from_raw_file(handle: HANDLE) -> Option<Self> {
        if handle == INVALID_HANDLE_VALUE {
            None
        } else {
            Some(Self(handle))
        }
    }

    pub fn raw(&self) -> HANDLE {
        self.0
    }
}

impl Drop for SafeHandle {
    fn drop(&mut self) {
        unsafe {
            CloseHandle(self.0);
        }
    }
}
```

--------------------------------

### Quit Processes by PID on Windows

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Terminates a list of processes specified by their PIDs. Returns true if all processes were successfully terminated or if the list was empty. Returns false if any process could not be terminated. Requires `PROCESS_TERMINATE` access rights.

```rust
pub fn quit_processes(pids: Vec<usize>) -> bool {
    #[cfg(windows)]
    {
        use windows_sys::Win32::Foundation::CloseHandle;
        use windows_sys::Win32::System::Threading::{
            OpenProcess, TerminateProcess, PROCESS_TERMINATE,
        };

        let mut ok = true;
        for pid in pids {
            unsafe {
                let process = OpenProcess(PROCESS_TERMINATE, 0, pid as u32);
                if process.is_null() {
                    ok = false;
                    continue;
                }
                TerminateProcess(process, 0);
                CloseHandle(process);
            }
        }
        ok
    }
    #[cfg(not(windows))]
    {
        let _ = pids;
        true
    }
}
```

--------------------------------

### Find and Quit Processes Locking a File

Source: https://docs.rs/filelocksmith/latest/filelocksmith

Use filelocksmith to find processes locking a specified file and then quit them. Ensure the necessary functions are imported.

```rust
use filelocksmith::{find_processes_locking_path, quit_processes, pid_to_process_path};

let path = "C:\\path\\to\\file.txt";
let pids = find_processes_locking_path(path);

// print paths of processes locking the file
for pid in &pids {
   println!("[{}] {:?}", pid, pid_to_process_path(*pid));
}

// quit the processes locking the file
if quit_processes(pids) {
 println!("Processes quit successfully");
}
```

--------------------------------

### pid_to_process_path

Source: https://docs.rs/filelocksmith/latest/filelocksmith/all.html

Converts a Process ID (PID) to its corresponding process path.

```APIDOC
## pid_to_process_path

### Description
Converts a Process ID (PID) to its corresponding process path.

### Parameters
#### Path Parameters
- **pid** (i32) - Required - The Process ID to convert.
```

--------------------------------

### find_processes_locking_path

Source: https://docs.rs/filelocksmith/latest/filelocksmith/all.html

Finds all processes that are currently locking a specified file path.

```APIDOC
## find_processes_locking_path

### Description
Finds all processes that are currently locking a specified file path.

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to check for locks.
```

--------------------------------

### Define UNICODE_STRING Structure

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Defines the UNICODE_STRING structure as used by ntdll. This avoids external dependencies for string manipulation in NT API calls.

```rust
#[repr(C)]
pub struct UnicodeString {
    /// Length in **bytes** (not characters).
    pub length: u16,
    pub maximum_length: u16,
    pub buffer: *mut u16,
}
```

--------------------------------

### is_process_elevated

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.is_process_elevated.html

Checks if the current process is running with administrator privileges. Returns true if elevated, false otherwise.

```APIDOC
## Function is_process_elevated

### Description
Returns true if the current process is running as administrator.

### Signature
```rust
pub fn is_process_elevated() -> bool
```

### Returns
- `bool`: `true` if the process is elevated, `false` otherwise.

### Example
```rust
if filelocksmith::is_process_elevated() {
    println!("Process is elevated.");
} else {
    println!("Process is not elevated.");
}
```
```

--------------------------------

### quit_processes

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.quit_processes.html

Quits processes given a list of process IDs. Returns true if all processes were quit successfully, or there were no processes to quit. If one or more processes could not be quit, this function will return false.

```APIDOC
## quit_processes

### Description
Quits processes given a list of process IDs. Returns true if all processes were quit successfully, or there were no processes to quit. If one or more processes could not be quit, this function will return false.

### Signature
```rust
pub fn quit_processes(pids: Vec<usize>) -> bool
```

### Parameters
#### Path Parameters
- **pids** (Vec<usize>) - Required - A vector of process IDs to quit.

### Return Value
- **bool** - Returns true if all processes were quit successfully or if there were no processes to quit. Returns false if one or more processes could not be quit.

### Example
```rust
let pids = filelocksmith::find_processes_locking_path(r"C:\filelocksmith-test");
if filelocksmith::quit_processes(pids) {
    println!("Processes quit successfully");
}
```
```

--------------------------------

### Convert Path to Kernel Name

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Converts a given file path to its kernel-readable name. Requires a valid `NtdllFunctions` instance and handles potential errors during file creation and type checking.

```rust
fn path_to_kernel_name(path: &Path, ntdll: &NtdllFunctions) -> Option<Vec<u16>> {
    let wide: Vec<u16> = path.as_os_str().encode_wide().chain(Some(0)).collect();
    let handle = unsafe {
        CreateFileW(
            wide.as_ptr(),
            0,
            FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
            ptr::null(),
            OPEN_EXISTING,
            FILE_FLAG_BACKUP_SEMANTICS,
            ptr::null_mut(),
        )
    };
    let handle = SafeHandle::from_raw_file(handle)?;
    unsafe {
        if GetFileType(handle.raw()) != FILE_TYPE_DISK {
            return None;
        }
    }
    file_handle_to_kernel_name(handle.raw(), ntdll, &mut vec![0u8; DEFAULT_BUFFER_SIZE])
}
```

--------------------------------

### Convert File Handle to Kernel Name

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

Retrieves the kernel name for a given file handle using NT API's `QueryObject`. It populates a buffer and reads a Unicode string from it. Returns `None` if the status is negative or the name is empty.

```rust
fn file_handle_to_kernel_name(
    handle: HANDLE,
    ntdll: &NtdllFunctions,
    buffer: &mut Vec<u8>,
) -> Option<Vec<u16>> {
    let mut return_length = 0u32;
    let status = unsafe {
        ntdll.query_object(
            handle,
            OBJECT_NAME_INFORMATION,
            buffer.as_mut_ptr().cast(),
            buffer.len() as u32,
            &mut return_length,
        )
    };
    if status < 0 {
        return None;
    }
    let name = unsafe { read_unicode_string(buffer.as_ptr().cast()) };
    if name.is_empty() {
        None
    } else {
        Some(name)
    }
}
```

--------------------------------

### Check if Process is Elevated (Windows)

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Determines if the current process is running with administrator privileges on Windows. This is crucial for filelocksmith to detect all locking processes.

```rust
pub fn is_process_elevated() -> bool {
    #[cfg(windows)]
    {
        use std::ptr;
        use windows_sys::Win32::Foundation::{CloseHandle, HANDLE};
        use windows_sys::Win32::Security::{
            GetTokenInformation, TokenElevation, TOKEN_ELEVATION, TOKEN_QUERY,
        };
        use windows_sys::Win32::System::Threading::GetCurrentProcess;

        #[link(name = "advapi32")]
        extern "system" {
            fn OpenProcessToken(
                process_handle: HANDLE,
                desired_access: u32,
                token_handle: *mut HANDLE,
            ) -> i32;
        }

        unsafe {
            let mut token: HANDLE = ptr::null_mut();
            if OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token) == 0 {
                return false;
            }
            let mut elevation = TOKEN_ELEVATION {
                TokenIsElevated: 0,
            };
            let mut size = 0u32;
            let ok = GetTokenInformation(
                token,
                TokenElevation,
                (&mut elevation as *mut TOKEN_ELEVATION).cast(),
                std::mem::size_of::<TOKEN_ELEVATION>() as u32,
                &mut size,
            );
            CloseHandle(token);
            ok != 0 && elevation.TokenIsElevated != 0
        }
    }
    #[cfg(not(windows))]
    {
        false
    }
}

```

--------------------------------

### is_process_elevated

Source: https://docs.rs/filelocksmith/latest/filelocksmith/all.html

Checks if the current process is running with elevated privileges.

```APIDOC
## is_process_elevated

### Description
Checks if the current process is running with elevated privileges.

### Returns
- **bool** - True if the process is elevated, false otherwise.
```

--------------------------------

### Check if Process is Elevated

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.is_process_elevated.html

Call `is_process_elevated` to determine if the current process is running as administrator. This function returns `true` if elevated, `false` otherwise.

```rust
println!("{:?}", filelocksmith::is_process_elevated());
```

--------------------------------

### find_processes_locking_path

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Finds processes that are locking a specified file or folder. It returns a vector of process IDs (PIDs). Note that if the current process is not running as administrator, it might not detect locking processes that require elevated privileges. Administrator privileges or setting the SeDebugPrivilege may be required for full system visibility.

```APIDOC
## find_processes_locking_path

### Description
Find processes locking a file or folder. Returns a list of process IDs.

If the current Rust process is not running as administrator, but the locking process is, the locking process will not be detected. You can use `is_process_elevated` to check if the current process is running as administrator. Also, you can use `set_debug_privilege` to set the SeDebugPrivilege, which will allow the current process to detect all processes on the system. Note that `set_debug_privilege` also requires administrator privileges to work.

### Parameters
- **path** (*P: AsRef<Path>*) - The path to the file or folder to check for locks.

### Returns
- `Vec<usize>` - A vector containing the PIDs of the processes locking the specified path.

### Example
```rust
use filelocksmith::find_processes_locking_path;

let path = "C:\\path\\to\\file.txt";
let pids = find_processes_locking_path(path);
println!("Processes locking the path: {:?}", pids);
```
```

--------------------------------

### set_debug_privilege

Source: https://docs.rs/filelocksmith/latest/filelocksmith/fn.set_debug_privilege.html

Sets the SeDebugPrivilege for the current process. Returns true if successful.

```APIDOC
## Function set_debug_privilege

### Description
Sets the SeDebugPrivilege for the current process. Returns true if successful.

### Signature
```rust
pub fn set_debug_privilege() -> bool
```

### Example
```rust
use filelocksmith;

fn main() {
    // ... other operations ...
    let success = filelocksmith::set_debug_privilege();
    println!("Debug privilege set successfully: {}", success);
    // ... other operations ...
}
```
```

--------------------------------

### read_unicode_string

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Safely reads a UNICODE_STRING from a raw pointer into a Vec<u16>.

```APIDOC
## read_unicode_string

### Description
This unsafe function reads a `UNICODE_STRING` structure from a given raw pointer. It converts the string's buffer and length into a `Vec<u16>`, handling cases where the buffer is null or the length is zero.

### Parameters
- `ptr` (**const UnicodeString*) - A raw pointer to a `UnicodeString` structure.

### Returns
- `Vec<u16>` - A vector of `u16` representing the Unicode string. Returns an empty vector if the input string is invalid or empty.
```

--------------------------------

### Define NtQuerySystemInformation Function Pointer Type

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Defines the function pointer type for the NtQuerySystemInformation NT API, used for querying system-wide information.

```rust
type NtQuerySystemInformationFn = unsafe extern "system" fn(
    system_information_class: u32,
    system_information: *mut c_void,
    system_information_length: u32,
    return_length: *mut u32,
) -> i32;
```

--------------------------------

### set_debug_privilege

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Attempts to set the SeDebugPrivilege for the current process. This privilege is often required to allow the process to debug or interact with other processes on the system, which is necessary for filelocksmith to detect all locking processes. This function requires administrator privileges to succeed.

```APIDOC
## set_debug_privilege

### Description
Sets the SeDebugPrivilege for the current process. Returns true if successful.

### Returns
- `bool` - `true` if the privilege was successfully set, `false` otherwise.

### Example
```rust
use filelocksmith::set_debug_privilege;

if set_debug_privilege() {
    println!("SeDebugPrivilege set successfully.");
} else {
    println!("Failed to set SeDebugPrivilege. Administrator privileges may be required.");
}
```
```

--------------------------------

### Read UNICODE_STRING from Pointer

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Safely reads a UNICODE_STRING structure from a raw pointer into a Vec<u16>. Handles null pointers and zero-length strings.

```rust
/// Read a `UNICODE_STRING` from a raw pointer into a `Vec<u16>`.
pub unsafe fn read_unicode_string(ptr: *const UnicodeString) -> Vec<u16> {
    let us = &*ptr;
    if us.buffer.is_null() || us.length == 0 {
        return Vec::new();
    }
    let char_count = us.length as usize / 2;
    std::slice::from_raw_parts(us.buffer, char_count).to_vec()
}
```

--------------------------------

### NtdllFunctions

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Represents resolved function pointers to essential NT API functions within `ntdll.dll`. This struct allows for safe invocation of these low-level functions.

```APIDOC
/// Resolved function pointers into ntdll.dll.
pub struct NtdllFunctions {
    query_system_information: NtQuerySystemInformationFn,
    query_object: NtQueryObjectFn,
}

impl NtdllFunctions {
    /// Resolve the NT functions from ntdll.dll. Returns `None` if any lookup fails.
    pub fn load() -> Option<Self>;

    /// Calls the `NtQuerySystemInformation` function.
    pub unsafe fn query_system_information(
        &self,
        class: u32,
        buf: *mut c_void,
        len: u32,
        ret_len: *mut u32,
    ) -> i32;

    /// Calls the `NtQueryObject` function.
    pub unsafe fn query_object(
        &self,
        handle: HANDLE,
        class: u32,
        buf: *mut c_void,
        len: u32,
        ret_len: *mut u32,
    ) -> i32;
}

```

--------------------------------

### set_debug_privilege

Source: https://docs.rs/filelocksmith/latest/filelocksmith/all.html

Enables or disables the debug privilege for the current process.

```APIDOC
## set_debug_privilege

### Description
Enables or disables the debug privilege for the current process.

### Parameters
#### Query Parameters
- **enable** (bool) - Required - True to enable, false to disable.
```

--------------------------------

### is_process_elevated

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Checks if the current process is running with administrator privileges. This is important for filelocksmith to be able to detect all locking processes.

```APIDOC
## is_process_elevated

### Description
Returns true if the current process is running as administrator.

### Returns
- `bool` - `true` if the process is elevated, `false` otherwise.

### Example
```rust
use filelocksmith::is_process_elevated;

if is_process_elevated() {
    println!("Process is running as administrator.");
} else {
    println!("Process is not running as administrator.");
}
```
```

--------------------------------

### quit_processes

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/lib.rs.html

Attempts to terminate a list of processes specified by their Process IDs (PIDs). This function is useful for releasing file locks held by other applications.

```APIDOC
## quit_processes

### Description
Quits the processes specified by a list of process IDs.

### Parameters
- **pids** (`Vec<usize>`) - A vector of process IDs to terminate.

### Returns
- `bool` - `true` if all specified processes were successfully quit, `false` otherwise.

### Example
```rust
use filelocksmith::{find_processes_locking_path, quit_processes};

let path = "C:\\path\\to\\file.txt";
let pids = find_processes_locking_path(path);

if quit_processes(pids) {
    println!("Processes quit successfully");
} else {
    println!("Failed to quit one or more processes.");
}
```
```

--------------------------------

### Worker Thread for Handle Enumeration

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/handles.rs.html

The `worker_thread_proc` function is an unsafe extern 'system' function designed to be executed by a thread. It iterates through system handles, duplicates them, and collects information. It uses atomic operations for shared state management and handles potential errors during process opening and handle duplication.

```rust
unsafe extern "system" fn worker_thread_proc(param: *mut c_void) -> u32 {
    let state = &*(param as *const SharedState);
    let ntdll = &*state.ntdll;
    let info = &*state.handle_info_ptr;
    let results = &mut *state.results.get();
    let pid_to_handle = &mut *state.pid_to_handle.get();
    let buf = &mut *state.object_info_buffer.get();
    let handles_base = info.handles.as_ptr();
    let count = state.handle_count;

    let mut i = state.current_index.load(Ordering::Relaxed);
    while i < count {
        state.current_dup_handle.store(0, Ordering::Relaxed);

        let entry = &*handles_base.add(i);
        let pid = entry.unique_process_id;

        let process_handle = if let Some(&h) = pid_to_handle.get(&pid) {
            h
        } else {
            let h = OpenProcess(PROCESS_DUP_HANDLE, 0, pid as u32);
            if h.is_null() {
                i += 1;
                state.current_index.store(i, Ordering::Relaxed);
                continue;
            }
            pid_to_handle.insert(pid, h);
            h
        };

        let mut local_handle: HANDLE = ptr::null_mut();
        let ok = DuplicateHandle(
            process_handle,
            entry.handle_value as HANDLE,
            GetCurrentProcess(),
            &mut local_handle,
            0,
            0,
            DUPLICATE_SAME_ACCESS,
        );
        if ok == 0 {
            i += 1;
            state.current_index.store(i, Ordering::Relaxed);
            continue;
        }
        state
```

--------------------------------

### Define NtQueryObject Function Pointer Type

Source: https://docs.rs/filelocksmith/latest/src/filelocksmith/ntapi.rs.html

Defines the function pointer type for the NtQueryObject NT API, used for querying information about a specific object.

```rust
type NtQueryObjectFn = unsafe extern "system" fn(
    handle: HANDLE,
    object_information_class: u32,
    object_information: *mut c_void,
    object_information_length: u32,
    return_length: *mut u32,
) -> i32;
```
Tokens:
Raw