Struct LxVolume

pub struct LxVolume { /* private fields */ }

A platform-independent abstraction that allows you to treat an area of the file system as if it has Unix semantics.

N.B.: all methods take relative paths, but do not attempt to make sure the path does not escape the root of the LxVolume, and therefore should not be relied upon for security.

Use PathExt and PathBufExt to write cross-platform code that deals only with Unix-style paths.

Windows

Unix behavior is emulated on Windows, specifically targeting the behavior of Linux. The semantics of some calls may differ slightly. In particular:

• Linux specific attributes (such as a file’s mode and owner, and special file types like fifos and device files) are only supported if metadata is enabled in the LxVolumeOptions, and the underlying file system supports the required functionality (extended attributes and reparse points). If this is not enabled, emulation of certain behavior like chmod is limited.
• For files that don’t have Linux metadata, LxVolumeOptions can be used to influence how values for Linux attributes are created.
• The owner of a newly created file is specified in the LxCreateOptions passed to the relevant create call.
• Linux permissions are not enforced, even if metadata is enabled.

Unix

All calls pass through directly to their libc equivalent. Attributes like mode are always enabled if the file system supports them. LxVolumeOptions is entirely ignored, as are the uid and gid fields of LxCreateOptions.

Implementations

impl LxVolume

pub fn new(root_path: impl AsRef<Path>) -> Result<Self>

Creates a new instance of LxVolume using the specified root path.

pub fn supports_stable_file_id(&self) -> bool

Indicates whether the file IDs (inode numbers) on this file system are stable.

Windows

This is determined by whether or not a file system supports the FILE_SUPPORTS_OPEN_BY_FILE_ID flag. For example, FAT does not have stable inode numbers.

If a file system doesn’t have stable inode numbers, it means a file’s inode number can change when that file is renamed, and the original inode number can be reused by another file.

Unix

This is a requirement for file systems in Linux, so this is always true. Note that IDs may still conflict if a path traverses a mount point.

pub fn lstat(&self, path: impl AsRef<Path>) -> Result<Stat>

Retrieves the attributes of a file. Symlinks are not followed.

pub fn set_attr( &self, path: impl AsRef<Path>, attr: SetAttributes, ) -> Result<()>

Sets the attributes of a file. Symlinks are not followed.

This function combines the functionality of truncate, chmod, chown and utimensat.

If this function fails, some of the operations may still have succeeded.

Windows

Chmod and chown are only fully supported if metadata is enabled and the file system supports it. Without metadata, chmod only changes the read-only attribute if all write bits are removed from the mode, and chown silently succeeds without taking any action.

This function disables the set-user-ID and set-group-ID as required if a request is made to change the size, owner or group of a file. This is done based on whether the SetAttributes::thread_uid field indicates the user is root.

Unix

Symlinks are followed for chmod, because the fchmodat syscall does not offer a way to not follow symlinks.

The SetAttributes::thread_uid field is ignored, and the thread’s actual capabilities are are used.

If SetAttributes::ctime is set, the ctime is set to the current time rather than the specified value.

pub fn set_attr_stat( &self, path: impl AsRef<Path>, attr: SetAttributes, ) -> Result<Stat>

Sets the attributes of a file, and gets the new attributes. Symlinks are not followed.

See set_attr for more details.

Windowows

Attributes are set and retrieved using the same handle, and is therefore faster than calling set_attr and lstat separately.

Unix

This does the operations separately, and is therefore susceptible to a race if the item is removed or replaced between creation and retrieving its attributes.

pub fn truncate( &self, path: impl AsRef<Path>, size: off_t, thread_uid: uid_t, ) -> Result<()>

Truncates a file.

Windows

The thread_uid argument is used to determine whether or not the set-user-ID and set-group-ID bits should be cleared. This is ignored if metadata is disabled.

Unix

Unlike the normal truncate syscall on Linux, this function does not follow symlinks. The thread_uid argument is ignored, and the thread’s actual capabilities are used.

pub fn chmod(&self, path: impl AsRef<Path>, mode: mode_t) -> Result<()>

Changes the permissions of a file.

Windows

Chmod is only fully supported if metadata is enabled and the file system supports it. Without metadata, chmod only changes the read-only attribute if all write bites are removed from the mode.

Unix

Symlinks are followed for chmod, because the fchmodat syscall does not offer a way to not follow symlinks.

pub fn chown( &self, path: impl AsRef<Path>, uid: Option<uid_t>, gid: Option<gid_t>, ) -> Result<()>

Changes the owner and/or group of a file.

Windows

Chown is only fully supported if metadata is enabled and the file system supports it. Without metadata, chown silently succeeds without taking any action.

pub fn set_times( &self, path: impl AsRef<Path>, atime: SetTime, mtime: SetTime, ) -> Result<()>

Changes a file’s time stamps.

The change time of the file is always set to the current time if this function is called.

pub fn open( &self, path: impl AsRef<Path>, flags: i32, options: Option<LxCreateOptions>, ) -> Result<LxFile>

Opens or creates a file.

Windows

Not all open flags are supported. In particular, only the flags present in the lx module are supported. Unknown flags are ignored.

The O_NOFOLLOW flag will successfully open a symbolic link, whereas on Unix it will fail without the O_PATH flag (the O_PATH flag is ignored on Windows).

pub fn mkdir( &self, path: impl AsRef<Path>, options: LxCreateOptions, ) -> Result<()>

Creates a new directory.

pub fn mkdir_stat( &self, path: impl AsRef<Path>, options: LxCreateOptions, ) -> Result<Stat>

Creates a new directory and retrieves its attributes.

Windows

This uses the handle opened during creation, and is therefore faster than doing the operations separately.

Unix

This does the operations separately, and is therefore susceptible to a race if the item is removed or replaced between creation and retrieving its attributes.

pub fn symlink( &self, path: impl AsRef<Path>, target: impl AsRef<LxStr>, options: LxCreateOptions, ) -> Result<()>

Creates a new symbolic link.

The mode on the create options is ignored, as symbolic links always have a mode of 0o777.

Windows

This will attempt to create an NTFS symbolic link, but will fall back to a WSL-style link if this is not possible.

pub fn symlink_stat( &self, path: impl AsRef<Path>, target: impl AsRef<LxStr>, options: LxCreateOptions, ) -> Result<Stat>

Creates a new symbolic link and retrieves its attributes.

The mode on the create options is ignored, as symbolic links always have a mode of 0o777.

Windows

This uses the handle opened during creation, and is therefore faster than doing the operations separately.

Unix

This does the operations separately, and is therefore susceptible to a race if the item is removed or replaced between creation and retrieving its attributes.

pub fn read_link(&self, path: impl AsRef<Path>) -> Result<LxString>

Reads the target of a symbolic link.

Windows

NTFS symlinks will be translated to a Unix-style path. WSL-style symlinks are returned as is. Use PathExt or PathBufExt to convert the result to a native path if required.

pub fn unlink(&self, path: impl AsRef<Path>, flags: i32) -> Result<()>

Removes a file or directory.

When the lx::AT_REMOVEDIR flag is specified, this method removes directories; otherwise, it removes files.

Windows

NTFS directory symbolic links are counted as files, not directories.

pub fn mknod( &self, path: impl AsRef<Path>, options: LxCreateOptions, device_id: dev_t, ) -> Result<()>

Creates a regular, character device, block device, fifo or socket file.

Windows

Only regular files are supported unless metadata is enabled.

pub fn mknod_stat( &self, path: impl AsRef<Path>, options: LxCreateOptions, device_id: dev_t, ) -> Result<Stat>

Creates a regular, character device, block device, fifo or socket file, and retrieves its attributes.

Windows

Only regular files are supported unless metadata is enabled.

This uses the handle opened during creation, and is therefore faster than doing the operations separately.

Unix

This does the operations separately, and is therefore susceptible to a race if the item is removed or replaced between creation and retrieving its attributes.

pub fn rename( &self, path: impl AsRef<Path>, new_path: impl AsRef<Path>, flags: u32, ) -> Result<()>

Renames a file.

Flags correspond to the flags of the renameat2 syscall in Linux.

Windows

This function will use POSIX rename if the file system supports it. No flags are currently supported.

pub fn link( &self, path: impl AsRef<Path>, new_path: impl AsRef<Path>, ) -> Result<()>

Creates a new hard link to a file.

pub fn link_stat( &self, path: impl AsRef<Path>, new_path: impl AsRef<Path>, ) -> Result<Stat>

Creates a new hard link to a file and retrieves its attributes.

Windows

This uses the handle opened during creation, and is therefore faster than doing the operations separately.

Unix

This does the operations separately, and is therefore susceptible to a race if the item is removed or replaced between creation and retrieving its attributes.

pub fn stat_fs(&self, path: impl AsRef<Path>) -> Result<StatFs>

Retrieve attributes of the file system.

The path passed should not really matter, unless there are multiple file systems accessible from this LxVolume.

Windows

The StatFs::fs_type and StatFs::flags field will not be set as they are not relevant to Windows.

pub fn set_xattr( &self, path: impl AsRef<Path>, name: impl AsRef<LxStr>, value: &[u8], flags: i32, ) -> Result<()>

Sets an extended attribute on a file.

Windows

Extended attribute names are not case sensitive. They are stored as upper case in NTFS but list_xattr will report them as lower case for greater compatibility with Linux.

Extended attribute names are prefixed with “LX.”, and have a slightly shorter maximum length limit than Linux. Attribute values are prefixed with a 4-byte header to allow for “empty” values, which NTFS does not normally allow. get_xattr and list_xattr will strip these prefixes.

Security for accessing the various attribute namespaces is not enforced.

If the flags XATTR_CREATE or XATTR_REPLACE are used, the operation is not atomic because Windows has to separately check for the attribute’s existence. In this case, there is a small possibility of a race where an attribute created by another thread gets overwritten.

pub fn get_xattr( &self, path: impl AsRef<Path>, name: impl AsRef<LxStr>, value: Option<&mut [u8]>, ) -> Result<usize>

Gets the value or size of an extended attribute on a file.

This function will return the size of the attribute.

Windows

Extended attribute names are not case sensitive. They are stored as upper case in NTFS but list_xattr will report them as lower case for greater compatibility with Linux.

Extended attribute names are prefixed with “LX.”, and have a slightly shorter maximum length limit than Linux. Attribute values are prefixed with a 4-byte header to allow for “empty” values, which NTFS does not normally allow. get_xattr and list_xattr will strip these prefixes.

Security for accessing the various attribute namespaces is not enforced.

pub fn list_xattr( &self, path: impl AsRef<Path>, list: Option<&mut [u8]>, ) -> Result<usize>

Gets a list of all the extended attributes on a file.

This function will return the size of the list.

The list contains the names of all the attributes, separated by NULL characters.

Windows

Extended attribute names are not case sensitive. They are stored as upper case in NTFS but list_xattr will report them as lower case for greater compatibility with Linux.

Extended attribute names are prefixed with “LX.”, and have a slightly shorter maximum length limit than Linux. Attribute values are prefixed with a 4-byte header to allow for “empty” values, which NTFS does not normally allow. get_xattr and list_xattr will strip these prefixes.

Security for accessing the various attribute namespaces is not enforced.

pub fn remove_xattr( &self, path: impl AsRef<Path>, name: impl AsRef<LxStr>, ) -> Result<()>

Removes an extended attribute from the file.

Windows

Extended attribute names are not case sensitive. They are stored as upper case in NTFS but list_xattr will report them as lower case for greater compatibility with Linux.

Extended attribute names are prefixed with “LX.”, and have a slightly shorter maximum length limit than Linux. Attribute values are prefixed with a 4-byte header to allow for “empty” values, which NTFS does not normally allow. get_xattr and list_xattr will strip these prefixes.

Security for accessing the various attribute namespaces is not enforced.