winfsp-rs

Latest Version Docs License

Safe Rust bindings to WinFSP with examples.

Warning

A best effort has been made to keep Rust's aliasing rules in mind, and provide a safe and sound wrapper over WinFSP. However, FFI with WinFSP involves a lot of pointers that end up as references and the nature of FFI makes it difficult to test with miri. While ntptfs is used to test the correctness of the bindings, there is still a chance these bindings are unsound.

Please file a bug report if you encounter unsoundness when using the safe APIs of these bindings.

Usage

By default, winfsp-rs builds against an included import library. To build against the installed WinFSP libraries, enable the system feature. The path will automatically be determined via the Registry.

toml [dependencies.winfsp] version = "0.10" features = ["system"]

Delay-loading

To enable delay-loading of WinFSP, add winfsp to build-dependencies and call winfsp::build::winfsp_link_delayload() in the build script. This is required for winfsp-rs.

Cargo.toml

toml [build-dependencies] winfsp = "0.10"

build.rs

rust fn main() { winfsp::build::winfsp_link_delayload(); }

Debugging

Debug output can be enabled with the debug feature. Debug output will be written to standard output, and redirection of output is not configurable at this time. toml [dependencies.winfsp] features = ["debug"]

Building on Stable Rust

It is recommended you build winfsp-rs on nightly Rust as it relies on io_error_more and strict_provenance. However, it is possible to build winfsp-rs on stable Rust without support for these features.

toml [dependencies.winfsp] default-features = false features = ["stable"]

Using with windows-sys

With default features, the winfsp crate includes helper utilities and From implementations for error types in the version of the windows crate at the time of publishing. If you wish to use winfsp without windows types, disable the windows-rs crate feature.

toml [dependencies.winfsp] default-features = false features = ["stable", "nightly"]

Testing

ntptfs-winfsp-rs, a port of ntptfs to winfsp-rs is used to test the bindings. It passes all tests that ntptfs passes at the same elevation level.

Test results

❯ F:\winfsp-tests-x64 --external --resilient +* --case-insensitive-cmp -delete_access_test -getfileattr_test -exec_rename_dir_test -rename_flipflop_test -stream_rename_flipflop_test -stream_getstreaminfo_test -ea* create_test............................ OK 0.02s create_fileattr_test................... OK 0.01s create_readonlydir_test................ OK 0.01s create_related_test.................... OK 0.00s create_allocation_test................. OK 0.01s create_sd_test......................... OK 0.01s create_notraverse_test................. OK 0.00s create_backup_test..................... OK 0.00s create_restore_test.................... OK 0.00s create_share_test...................... OK 0.01s create_curdir_test..................... OK 0.00s create_namelen_test.................... OK 0.01s getfileinfo_test....................... OK 0.00s getfileinfo_name_test.................. OK 0.00s setfileinfo_test....................... OK 0.00s delete_test............................ OK 0.00s delete_pending_test.................... OK 0.00s delete_mmap_test....................... OK 0.00s delete_standby_test.................... OK 0.07s delete_ex_test......................... OK 0.01s rename_test............................ OK 0.02s rename_backslash_test.................. OK 0.01s rename_open_test....................... OK 0.00s rename_caseins_test.................... OK 0.01s rename_mmap_test....................... OK 0.01s rename_standby_test.................... OK 0.15s rename_ex_test......................... OK 0.01s getvolinfo_test........................ OK 0.00s setvolinfo_test........................ OK 0.00s getsecurity_test....................... OK 0.00s setsecurity_test....................... OK 0.00s security_stress_meta_test.............. OK 0.24s rdwr_noncached_test.................... OK 0.02s rdwr_noncached_overlapped_test......... OK 0.02s rdwr_cached_test....................... OK 0.02s rdwr_cached_append_test................ OK 0.01s rdwr_cached_overlapped_test............ OK 0.02s rdwr_writethru_test.................... OK 0.01s rdwr_writethru_append_test............. OK 0.01s rdwr_writethru_overlapped_test......... OK 0.01s rdwr_mmap_test......................... OK 0.15s rdwr_mixed_test........................ OK 0.01s flush_test............................. OK 0.05s flush_volume_test...................... OK 0.00s lock_noncached_test.................... OK 0.02s lock_noncached_overlapped_test......... OK 0.01s lock_cached_test....................... OK 0.01s lock_cached_overlapped_test............ OK 0.01s querydir_test.......................... OK 0.64s querydir_nodup_test.................... OK 4.43s querydir_single_test................... OK 1.78s querydir_expire_cache_test............. OK 0.00s querydir_buffer_overflow_test.......... OK 0.00s querydir_namelen_test.................. OK 0.01s dirnotify_test......................... OK 1.01s exec_test.............................. OK 0.02s exec_delete_test....................... OK 1.03s exec_rename_test....................... OK 1.03s reparse_guid_test...................... OK 4.83s reparse_nfs_test....................... OK 0.00s reparse_symlink_test................... OK 0.01s reparse_symlink_relative_test.......... OK 0.04s stream_create_test..................... OK 0.02s stream_create_overwrite_test........... OK 0.01s stream_create_related_test............. OK 0.00s stream_create_sd_test.................. OK 0.00s stream_create_share_test............... OK 0.03s stream_getfileinfo_test................ OK 0.00s stream_setfileinfo_test................ OK 0.01s stream_delete_test..................... OK 0.01s stream_delete_pending_test............. OK 0.01s stream_getsecurity_test................ OK 0.00s stream_setsecurity_test................ OK 0.00s stream_getstreaminfo_expire_cache_test. OK 0.00s stream_dirnotify_test.................. OK 1.01s oplock_level1_test..................... OK 1.31s oplock_level2_test..................... OK 2.48s oplock_batch_test...................... OK 1.25s oplock_filter_test..................... OK 1.24s oplock_rwh_test........................ OK 1.24s oplock_rw_test......................... OK 1.24s oplock_rh_test......................... OK 2.48s oplock_r_test.......................... OK 2.48s oplock_not_granted_test................ OK 0.00s wsl_stat_test.......................... OK 0.00s --- COMPLETE ---

Legal

winfsp-rs is licensed under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

Attribution

WinFsp - Windows File System Proxy,

Copyright (C) Bill Zissimopoulos \ https://github.com/winfsp/winfsp