Lib.rs

› Filesystem | Operating systems › Windows APIs
#api-bindings #safe-bindings #file #fuse #sound #correctness

winfsp

Rust bindings to WinFSP

by Ronny Chan and 2 contributors

20 releases (8 breaking)

0.11.3+winfsp-2.0 Jan 19, 2024
0.10.0+winfsp-2.0 Jan 19, 2024
0.10.0-beta.2+winfsp-2.0 Sep 23, 2023
0.7.1+winfsp-2.0 May 3, 2023
0.5.2+winfsp-1.11 Oct 17, 2022

#164 in Filesystem

Download history 10/week @ 2024-08-05 3/week @ 2024-09-16 67/week @ 2024-09-23 9/week @ 2024-09-30 6/week @ 2024-10-07

267 downloads per month
Used in ntptfs-winfsp-rs

GPL-3.0 license

1.5MB
13K SLoC

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.

[dependencies.winfsp]
version = "0.11"
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

[build-dependencies]
winfsp = "0.11"

build.rs

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.

[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.

[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.

[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 ---

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

Dependencies

~129MB
~2M SLoC