Expand description
§Description
The rsmount library is a safe Rust wrapper around util-linux/libmount.
rsmount allows users to, among other things:
- mount devices on an operating system’s file hierarchy,
- list/manage mount points in
/proc/<pid>/mountinfo, - consult the system’s swap usage from
/proc/swaps, - compose/edit
/etc/fstab, the file describing all devices an OS should mount at boot. - etc.
§Examples
Mount a device on a operating system’s file tree.
ⓘ
use rsmount::device::BlockDevice;
use rsmount::flags::MountFlag;
use rsmount::fs::FileSystem;
use rsmount::mount::Mount;
fn main() -> rsmount::Result<()> {
// Configure the `Mount` struct.
let block_device: BlockDevice = "/dev/vda".parse()?;
let mut mount = Mount::builder()
// Device to mount.
.source(block_device)
// Location of the mount point in the file tree.
.target("/mnt")
// Do not allow writing to the file system while it is mounted.
.mount_flags(vec![MountFlag::ReadOnly])
// Gives a hint about the file system used by the device (optional).
.file_system(FileSystem::Ext4)
.build()?;
// Mount `/dev/vda` at `/mnt`.
mount.mount_device()?;
Ok(())
}Create an fstab.
use std::str::FromStr;
use rsmount::tables::FsTab;
use rsmount::entries::FsTabEntry;
use rsmount::device::BlockDevice;
use rsmount::device::Pseudo;
use rsmount::device::Source;
use rsmount::device::Tag;
use rsmount::fs::FileSystem;
fn main() -> rsmount::Result<()> {
let mut fstab = FsTab::new()?;
fstab.set_intro_comments("# /etc/fstab\n")?;
fstab.append_to_intro_comments("# Example from scratch\n")?;
// Mount the device with the following UUID as the root file system.
let uuid = Tag::from_str("UUID=dd476616-1ce4-415e-9dbd-8c2fa8f42f0f")?;
let entry1 = FsTabEntry::builder()
.source(uuid)
.target("/")
.file_system_type(FileSystem::Ext4)
// Comma-separated list of mount options.
.mount_options("rw,relatime")
// Interval, in days, between file system backups by the dump command on ext2/3/4
// file systems.
.backup_frequency(0)
// Order in which file systems are checked by the `fsck` command.
.fsck_checking_order(1)
.build()?;
// Mount the removable device `/dev/usbdisk` on demand.
let block_device = BlockDevice::from_str("/dev/usbdisk")?;
let entry2 = FsTabEntry::builder()
.source(block_device)
.target("/media/usb")
.file_system_type(FileSystem::VFAT)
.mount_options("noauto")
.backup_frequency(0)
.fsck_checking_order(0)
.build()?;
// Mount a pseudo-filesystem (tmpfs) at `/tmp`
let entry3 = FsTabEntry::builder()
.source(Pseudo::None)
.target("/tmp")
.file_system_type(FileSystem::Tmpfs)
.mount_options("nosuid,nodev")
.backup_frequency(0)
.fsck_checking_order(0)
.build()?;
fstab.push(entry1);
fstab.push(entry2);
fstab.push(entry3);
println!("{}", fstab);
// Example output
//
// # /etc/fstab
// # Example from scratch
//
// UUID=dd476616-1ce4-415e-9dbd-8c2fa8f42f0f / ext4 rw,relatime 0 1
// /dev/usbdisk /media/usb vfat noauto 0 0
// none /tmp tmpfs nosuid,nodev 0 0
Ok(())
}§API structure
rsmount’s API is roughly divided into two main modules:
tables: a module for manipulating file system descriptions tables (/etc/fstab,/proc/self/mountinfo,/proc/swaps,/run/mount/utab).mount: a module to mount devices on the system’s file tree.
Finally, look to the debug module if you need to consult debug messages during development.
§From libmount to rsmount API
This section maps libmount functions to rsmount methods. It follows the same layout as
libmount’s documentation. You can use it as a reference to ease the transition from one API
to the other.
§Higher-level API
§Library high-level context
§Mount context
§Umount context
§Files parsing
§Table of filesystems
§Filesystem
§Tables management
§Locking
libmount | rsmount |
|---|---|
struct libmnt_lock | FileLock |
mnt_free_lock | FileLock is automatically deallocated when it goes out of scope. |
mnt_lock_file | FileLock::lock |
mnt_new_lock | FileLock::new |
mnt_unlock_file | FileLock::unlock |
mnt_lock_block_signals | FileLock::block_signals FileLock::unblock_signals |
§Tables update
§Monitor
§Compare changes in mount tables
§Mount options
§Options string
§Option maps
§Misc
§Library initialization
libmount | rsmount |
|---|---|
mnt_init_debug | debug::init_default_debugdebug::init_full_debug |
§Cache
libmount | rsmount |
|---|---|
struct libmnt_cache | Cache |
mnt_new_cache | Cache::new |
mnt_free_cache | Cache is automatically deallocated when it goes out of scope. |
mnt_ref_cache | Managed automatically. |
mnt_unref_cache | Managed automatically. |
mnt_cache_device_has_tag | Cache::device_has_tag |
mnt_cache_find_tag_value | Cache::find_tag_value |
mnt_cache_read_tags | Cache::import_tags |
mnt_cache_set_targets | Cache::import_paths |
mnt_cache_set_sbprobe | Cache::collect_fs_properties |
mnt_get_fstype | Cache::find_file_system_typeCache::find_and_cache_file_system_type |
mnt_pretty_path | Cache::canonicalizeCache::canonicalize_and_cache |
mnt_resolve_path | Cache::resolveCache::resolve_and_cache |
mnt_resolve_spec | Not implemented. Use the specialized functions corresponding to mnt_resolve_path or mnt_resolve_tag as applicable. |
mnt_resolve_tag | Cache::find_first_device_with_tagCache::find_and_cache_first_device_with_tag |
mnt_resolve_target | Cache::find_device_mounted_atCache::find_and_cache_device_mounted_at |
§Iterator
libmount | rsmount |
|---|---|
struct libmnt_iter | GenIterator |
mnt_free_iter | GenIterator is automatically deallocated when it goes out of scope. |
mnt_iter_get_direction | GenIterator::direction |
mnt_new_iter | GenIterator::new |
mnt_reset_iter | GenIterator::resetGenIterator::reset_forwardGenIterator::reset_backward |
§Utils
§Version functions
Modules§
- cache
- High-level API to handle device identification, and tag extraction.
- debug
- Activate debug message output.
- device
- Module describing supported mount sources.
- entries
- Collection of data structures representing lines in file system description files.
- errors
- Runtime errors.
- flags
- Configuration flags.
- fs
- Module for working with file systems.
- iter
- File system description file iterators.
- mount
- High-level API to mount/unmount devices.
- optstring
- Low-level functions to manipulate mount option strings.
- tables
- Module for working with file system description files.
- utils
- Miscellaneous utilities.
- version
- Functions to get library version data.
Enums§
- RsMount
Error - Library-level runtime errors.