Struct Client 

pub struct Client { /* private fields */ }

Blocking, path-oriented NFSv3 client.

Client owns one MOUNT/NFS connection pair and exposes storage-oriented operations such as whole-file reads, offset reads, atomic writes, copy, directory pagination, metadata updates, and recursive removal.

Methods take paths relative to the mounted export. The root of the export is /.

Implementations

impl Client

pub fn connect(target: &str) -> Result<Self>

Connects to a target in host:/export form.

pub fn builder( host: impl Into<String>, export: impl Into<String>, ) -> ClientBuilder

Creates a builder from host and export components.

pub fn fsinfo(&self) -> Option<&FsInfo>

Returns filesystem information discovered at connect time, if available.

Examples found in repository

examples/v3_cookbook.rs (line 30)

fn main() -> nfs::Result<()> {
    let config = Config::from_env();
    let mut client = connect(&config.target)?;

    println!("connected to NFSv3 target {}", config.target);
    if let Some(info) = client.fsinfo() {
        println!(
            "server fsinfo: read_preferred={} write_preferred={} dir_preferred={}",
            info.read_preferred, info.write_preferred, info.dir_preferred
        );
    }

    let work_dir = remote_path(
        &config.remote_dir,
        &format!("nfs-rs-v3-cookbook-{}", std::process::id()),
    );
    client.remove_all_if_exists(&work_dir)?;
    client.create_dir_all(&work_dir, 0o755)?;

    let flow_result = run_filesystem_flow(&mut client, &work_dir);
    let cleanup_result = client.remove_all_if_exists(&work_dir);
    let unmount_result = client.unmount();
    finish(flow_result, cleanup_result, unmount_result)
}

pub fn reconnect(&mut self) -> Result<()>

Reconnects using the original builder configuration.

Examples found in repository

examples/v3_cookbook.rs (line 224)

fn demonstrate_reconnect(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    client.reconnect()?;
    println!(
        "reconnected; workspace still exists = {}",
        client.exists(work_dir)?
    );
    Ok(())
}

pub fn fsstat(&mut self, path: &str) -> Result<FsStat>

Reads filesystem capacity information for a path.

Examples found in repository

examples/v3_cookbook.rs (line 197)

fn demonstrate_filesystem_queries(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let fsstat = client.fsstat(work_dir)?;
    println!(
        "fsstat: total={} free={} available={}",
        fsstat.total_bytes, fsstat.free_bytes, fsstat.available_bytes
    );

    let pathconf = client.pathconf(work_dir)?;
    println!(
        "pathconf: name_max={} link_max={} case_preserving={}",
        pathconf.name_max, pathconf.link_max, pathconf.case_preserving
    );

    Ok(())
}

pub fn pathconf(&mut self, path: &str) -> Result<PathConf>

Reads path configuration limits for a path.

Examples found in repository

examples/v3_cookbook.rs (line 203)

fn demonstrate_filesystem_queries(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let fsstat = client.fsstat(work_dir)?;
    println!(
        "fsstat: total={} free={} available={}",
        fsstat.total_bytes, fsstat.free_bytes, fsstat.available_bytes
    );

    let pathconf = client.pathconf(work_dir)?;
    println!(
        "pathconf: name_max={} link_max={} case_preserving={}",
        pathconf.name_max, pathconf.link_max, pathconf.case_preserving
    );

    Ok(())
}

pub fn metadata(&mut self, path: &str) -> Result<FileAttr>

Reads NFSv3 attributes for a path.

Examples found in repository

examples/basic.rs (line 38)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

examples/v3_cookbook.rs (line 77)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn file_type(&mut self, path: &str) -> Result<FileType>

Returns the remote file type for a path.

pub fn is_file(&mut self, path: &str) -> Result<bool>

Returns true when the path is a regular file.

pub fn is_dir(&mut self, path: &str) -> Result<bool>

Returns true when the path is a directory.

pub fn is_symlink(&mut self, path: &str) -> Result<bool>

Returns true when the path is a symbolic link.

pub fn access(&mut self, path: &str, access: u32) -> Result<AccessResult>

Checks server-granted access bits for a path.

Examples found in repository

examples/v3_cookbook.rs (lines 82-85)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn lookup(&mut self, path: &str) -> Result<()>

Resolves a path and returns success if it exists.

pub fn exists(&mut self, path: &str) -> Result<bool>

Returns whether a path exists.

Examples found in repository

examples/v3_cookbook.rs (line 79)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

fn demonstrate_optional_links(
    client: &mut Client,
    object: &str,
    work_dir: &str,
) -> nfs::Result<()> {
    let symlink = remote_path(work_dir, "object.symlink");
    if optional("symlink", client.symlink(&symlink, "object.txt")).is_some() {
        let target = client.read_link(&symlink)?;
        println!("symlink target: {target}");
    }

    let hard_link = remote_path(work_dir, "object.hardlink");
    if optional("hard_link", client.hard_link(object, &hard_link)).is_some() {
        println!("created hard link: {hard_link}");
    }

    Ok(())
}

fn demonstrate_directory_reads(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    println!("limited directory listing:");
    for entry in client.read_dir_limited(work_dir, 16)? {
        let kind = entry
            .attributes
            .as_ref()
            .map(|attrs| format!("{:?}", attrs.file_type))
            .unwrap_or_else(|| "unknown".to_owned());
        println!("  {} fileid={} type={kind}", entry.name, entry.fileid);
    }

    println!("paged directory listing:");
    let mut cursor: Option<DirPageCursor> = None;
    loop {
        let page = client.read_dir_page_limited(work_dir, cursor, 4)?;
        for entry in &page.entries {
            println!("  page entry: {}", entry.name);
        }
        if page.is_eof() {
            break;
        }
        cursor = page.next_cursor;
    }

    Ok(())
}

fn demonstrate_filesystem_queries(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let fsstat = client.fsstat(work_dir)?;
    println!(
        "fsstat: total={} free={} available={}",
        fsstat.total_bytes, fsstat.free_bytes, fsstat.available_bytes
    );

    let pathconf = client.pathconf(work_dir)?;
    println!(
        "pathconf: name_max={} link_max={} case_preserving={}",
        pathconf.name_max, pathconf.link_max, pathconf.case_preserving
    );

    Ok(())
}

fn demonstrate_error_handling(client: &mut Client, work_dir: &str) {
    let missing = remote_path(work_dir, "does-not-exist.txt");
    match client.read(&missing) {
        Ok(_) => println!("unexpectedly read missing file"),
        Err(err) if err.is_not_found() => println!("missing file classified as not found"),
        Err(err) if err.is_retryable() => println!("retryable error: {err}"),
        Err(err) if err.is_permission_denied() => println!("permission error: {err}"),
        Err(err) => println!("other read error: {err}"),
    }
}

fn demonstrate_reconnect(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    client.reconnect()?;
    println!(
        "reconnected; workspace still exists = {}",
        client.exists(work_dir)?
    );
    Ok(())
}

pub fn read(&mut self, path: &str) -> Result<Vec<u8>>

Reads an entire file into memory.

Examples found in repository

examples/v3_cookbook.rs (line 214)

fn demonstrate_error_handling(client: &mut Client, work_dir: &str) {
    let missing = remote_path(work_dir, "does-not-exist.txt");
    match client.read(&missing) {
        Ok(_) => println!("unexpectedly read missing file"),
        Err(err) if err.is_not_found() => println!("missing file classified as not found"),
        Err(err) if err.is_retryable() => println!("retryable error: {err}"),
        Err(err) if err.is_permission_denied() => println!("permission error: {err}"),
        Err(err) => println!("other read error: {err}"),
    }
}

examples/basic.rs (line 32)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

pub fn read_to_writer<W: Write + ?Sized>( &mut self, path: &str, writer: &mut W, ) -> Result<u64>

Streams an entire file into a local writer.

Examples found in repository

examples/v3_cookbook.rs (line 98)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn read_range_to_writer<W: Write + ?Sized>( &mut self, path: &str, offset: u64, count: u64, writer: &mut W, ) -> Result<u64>

Streams a byte range into a local writer.

pub fn read_range( &mut self, path: &str, offset: u64, count: u64, ) -> Result<Vec<u8>>

Reads a byte range into memory.

Examples found in repository

examples/basic.rs (line 35)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

examples/v3_cookbook.rs (line 94)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn read_at( &mut self, path: &str, offset: u64, count: u32, ) -> Result<Vec<u8>>

Reads up to count bytes at offset.

pub fn read_exact_at( &mut self, path: &str, offset: u64, count: u32, ) -> Result<Vec<u8>>

Reads exactly count bytes at offset, failing if EOF is reached first.

Examples found in repository

examples/v3_cookbook.rs (line 88)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn read_link(&mut self, path: &str) -> Result<String>

Reads the target of a symbolic link.

Examples found in repository

examples/v3_cookbook.rs (line 157)

fn demonstrate_optional_links(
    client: &mut Client,
    object: &str,
    work_dir: &str,
) -> nfs::Result<()> {
    let symlink = remote_path(work_dir, "object.symlink");
    if optional("symlink", client.symlink(&symlink, "object.txt")).is_some() {
        let target = client.read_link(&symlink)?;
        println!("symlink target: {target}");
    }

    let hard_link = remote_path(work_dir, "object.hardlink");
    if optional("hard_link", client.hard_link(object, &hard_link)).is_some() {
        println!("created hard link: {hard_link}");
    }

    Ok(())
}

pub fn write(&mut self, path: &str, data: &[u8]) -> Result<()>

Replaces or creates a file with data using file-sync stability.

pub fn write_with_stability( &mut self, path: &str, data: &[u8], stable: StableHow, ) -> Result<()>

Replaces or creates a file with an explicit NFS write stability level.

pub fn write_from_reader<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, ) -> Result<u64>

Replaces or creates a file by streaming from a local reader.

pub fn write_from_reader_with_stability<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, stable: StableHow, ) -> Result<u64>

Replaces or creates a file from a reader with an explicit write stability level.

pub fn write_atomic(&mut self, path: &str, data: &[u8]) -> Result<()>

Writes a file through a temporary sibling and renames it into place.

Examples found in repository

examples/basic.rs (line 30)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

examples/v3_cookbook.rs (line 139)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn write_atomic_with_mode( &mut self, path: &str, data: &[u8], mode: u32, ) -> Result<()>

Atomic write with an explicit mode for the temporary file.

pub fn write_atomic_with_stability( &mut self, path: &str, data: &[u8], stable: StableHow, ) -> Result<()>

Atomic write with an explicit NFS write stability level.

pub fn write_atomic_with_mode_and_stability( &mut self, path: &str, data: &[u8], mode: u32, stable: StableHow, ) -> Result<()>

Atomic write with explicit mode and write stability.

Examples found in repository

examples/v3_cookbook.rs (line 76)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn write_atomic_from_reader<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, ) -> Result<u64>

Atomic write by streaming from a local reader.

pub fn write_atomic_from_reader_with_mode<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, mode: u32, ) -> Result<u64>

Atomic reader-based write with an explicit mode for the temporary file.

pub fn write_atomic_from_reader_with_stability<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, stable: StableHow, ) -> Result<u64>

Atomic reader-based write with an explicit NFS write stability level.

pub fn write_atomic_from_reader_with_mode_and_stability<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, mode: u32, stable: StableHow, ) -> Result<u64>

Atomic reader-based write with explicit mode and write stability.

Examples found in repository

examples/v3_cookbook.rs (lines 105-110)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn append(&mut self, path: &str, data: &[u8]) -> Result<u64>

Appends bytes to an existing file and returns bytes written.

pub fn append_with_stability( &mut self, path: &str, data: &[u8], stable: StableHow, ) -> Result<u64>

Appends bytes with an explicit NFS write stability level.

Examples found in repository

examples/v3_cookbook.rs (line 113)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn append_from_reader<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, ) -> Result<u64>

Appends bytes from a local reader and returns bytes written.

pub fn append_from_reader_with_stability<R: Read + ?Sized>( &mut self, path: &str, reader: &mut R, stable: StableHow, ) -> Result<u64>

Appends from a reader with an explicit NFS write stability level.

pub fn truncate(&mut self, path: &str, size: u64) -> Result<()>

Truncates or extends a file to size bytes.

Examples found in repository

examples/v3_cookbook.rs (line 115)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn setattr(&mut self, path: &str, attr: &SetAttr) -> Result<()>

Applies NFSv3 attributes to a path.

pub fn set_mode(&mut self, path: &str, mode: u32) -> Result<()>

Sets POSIX mode bits.

Examples found in repository

examples/v3_cookbook.rs (line 136)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn set_uid(&mut self, path: &str, uid: u32) -> Result<()>

Sets numeric uid.

pub fn set_gid(&mut self, path: &str, gid: u32) -> Result<()>

Sets numeric gid.

pub fn set_ownership(&mut self, path: &str, uid: u32, gid: u32) -> Result<()>

Sets numeric uid and gid.

pub fn set_times( &mut self, path: &str, atime: Option<NfsTime>, mtime: Option<NfsTime>, ) -> Result<()>

Sets access and modification times.

pub fn touch(&mut self, path: &str) -> Result<()>

Updates access and modification times to the server time.

Examples found in repository

examples/v3_cookbook.rs (line 135)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn write_at(&mut self, path: &str, offset: u64, data: &[u8]) -> Result<()>

Writes bytes at offset using file-sync stability.

pub fn write_at_with_stability( &mut self, path: &str, offset: u64, data: &[u8], stable: StableHow, ) -> Result<()>

Writes bytes at offset with an explicit NFS write stability level.

Examples found in repository

examples/v3_cookbook.rs (line 114)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn copy(&mut self, from: &str, to: &str) -> Result<u64>

Copies a file, replacing or creating the destination.

pub fn copy_with_stability( &mut self, from: &str, to: &str, stable: StableHow, ) -> Result<u64>

Copies a file with an explicit NFS write stability level.

pub fn copy_atomic(&mut self, from: &str, to: &str) -> Result<u64>

Copies through a temporary sibling and renames it into place.

pub fn copy_atomic_with_stability( &mut self, from: &str, to: &str, stable: StableHow, ) -> Result<u64>

Atomic copy with an explicit NFS write stability level.

Examples found in repository

examples/v3_cookbook.rs (line 131)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn commit( &mut self, path: &str, offset: u64, count: u32, ) -> Result<CommitResult>

Commits previously unstable writes for a byte range.

Examples found in repository

examples/v3_cookbook.rs (line 116)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn create(&mut self, path: &str, mode: u32) -> Result<()>

Creates a new file using guarded create semantics.

pub fn create_new(&mut self, path: &str, mode: u32) -> Result<()>

Creates a new file and fails if it already exists.

Examples found in repository

examples/v3_cookbook.rs (line 119)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn create_unchecked(&mut self, path: &str, mode: u32) -> Result<()>

Creates or replaces a file using unchecked create semantics.

pub fn mkdir(&mut self, path: &str, mode: u32) -> Result<()>

Creates a directory.

pub fn create_dir_all(&mut self, path: &str, mode: u32) -> Result<()>

Creates a directory and missing parents, like mkdir -p.

Examples found in repository

examples/v3_cookbook.rs (line 42)

fn main() -> nfs::Result<()> {
    let config = Config::from_env();
    let mut client = connect(&config.target)?;

    println!("connected to NFSv3 target {}", config.target);
    if let Some(info) = client.fsinfo() {
        println!(
            "server fsinfo: read_preferred={} write_preferred={} dir_preferred={}",
            info.read_preferred, info.write_preferred, info.dir_preferred
        );
    }

    let work_dir = remote_path(
        &config.remote_dir,
        &format!("nfs-rs-v3-cookbook-{}", std::process::id()),
    );
    client.remove_all_if_exists(&work_dir)?;
    client.create_dir_all(&work_dir, 0o755)?;

    let flow_result = run_filesystem_flow(&mut client, &work_dir);
    let cleanup_result = client.remove_all_if_exists(&work_dir);
    let unmount_result = client.unmount();
    finish(flow_result, cleanup_result, unmount_result)
}

fn connect(target: &str) -> nfs::Result<Client> {
    ClientBuilder::from_target(target)?
        .auth_sys(AuthSys::current())
        .timeout(Some(Duration::from_secs(10)))
        .io_size(128 * 1024)
        .dir_size(64 * 1024)
        .max_dir_entries(4096)
        .retry_policy(RetryPolicy::new(
            4,
            Duration::from_millis(50),
            Duration::from_secs(2),
        ))
        .connect()
}

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn symlink(&mut self, path: &str, target: &str) -> Result<()>

Creates a symbolic link at path pointing to target.

Examples found in repository

examples/v3_cookbook.rs (line 156)

fn demonstrate_optional_links(
    client: &mut Client,
    object: &str,
    work_dir: &str,
) -> nfs::Result<()> {
    let symlink = remote_path(work_dir, "object.symlink");
    if optional("symlink", client.symlink(&symlink, "object.txt")).is_some() {
        let target = client.read_link(&symlink)?;
        println!("symlink target: {target}");
    }

    let hard_link = remote_path(work_dir, "object.hardlink");
    if optional("hard_link", client.hard_link(object, &hard_link)).is_some() {
        println!("created hard link: {hard_link}");
    }

    Ok(())
}

pub fn hard_link(&mut self, existing: &str, link: &str) -> Result<()>

Creates a hard link.

Examples found in repository

examples/v3_cookbook.rs (line 162)

fn demonstrate_optional_links(
    client: &mut Client,
    object: &str,
    work_dir: &str,
) -> nfs::Result<()> {
    let symlink = remote_path(work_dir, "object.symlink");
    if optional("symlink", client.symlink(&symlink, "object.txt")).is_some() {
        let target = client.read_link(&symlink)?;
        println!("symlink target: {target}");
    }

    let hard_link = remote_path(work_dir, "object.hardlink");
    if optional("hard_link", client.hard_link(object, &hard_link)).is_some() {
        println!("created hard link: {hard_link}");
    }

    Ok(())
}

pub fn remove(&mut self, path: &str) -> Result<()>

Removes a non-directory entry.

pub fn remove_if_exists(&mut self, path: &str) -> Result<bool>

Removes a non-directory entry if it exists.

Examples found in repository

examples/basic.rs (line 51)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

pub fn rmdir(&mut self, path: &str) -> Result<()>

Removes an empty directory.

pub fn rmdir_if_exists(&mut self, path: &str) -> Result<bool>

Removes an empty directory if it exists.

pub fn remove_all(&mut self, path: &str) -> Result<()>

Recursively removes a file tree.

The export root itself cannot be removed through this method.

pub fn remove_all_if_exists(&mut self, path: &str) -> Result<bool>

Recursively removes a file tree if it exists.

Examples found in repository

examples/v3_cookbook.rs (line 41)

fn main() -> nfs::Result<()> {
    let config = Config::from_env();
    let mut client = connect(&config.target)?;

    println!("connected to NFSv3 target {}", config.target);
    if let Some(info) = client.fsinfo() {
        println!(
            "server fsinfo: read_preferred={} write_preferred={} dir_preferred={}",
            info.read_preferred, info.write_preferred, info.dir_preferred
        );
    }

    let work_dir = remote_path(
        &config.remote_dir,
        &format!("nfs-rs-v3-cookbook-{}", std::process::id()),
    );
    client.remove_all_if_exists(&work_dir)?;
    client.create_dir_all(&work_dir, 0o755)?;

    let flow_result = run_filesystem_flow(&mut client, &work_dir);
    let cleanup_result = client.remove_all_if_exists(&work_dir);
    let unmount_result = client.unmount();
    finish(flow_result, cleanup_result, unmount_result)
}

pub fn rename(&mut self, from: &str, to: &str) -> Result<()>

Renames or moves a path.

Examples found in repository

examples/v3_cookbook.rs (line 134)

fn run_filesystem_flow(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    let object = remote_path(work_dir, "object.txt");
    let streamed = remote_path(work_dir, "streamed.txt");
    let created = remote_path(work_dir, "created.txt");
    let copied = remote_path(work_dir, "copied.txt");
    let renamed = remote_path(work_dir, "renamed.txt");
    let nested_dir = remote_path(work_dir, "nested/a/b");
    let nested_file = remote_path(&nested_dir, "payload.bin");

    println!("workspace: {work_dir}");

    client.write_atomic_with_mode_and_stability(&object, OBJECT, 0o640, StableHow::FileSync)?;
    print_v3_metadata("object after atomic write", &client.metadata(&object)?);

    let exists = client.exists(&object)?;
    println!("exists({object}) = {exists}");

    let access = client.access(
        &object,
        ACCESS3_READ | ACCESS3_LOOKUP | ACCESS3_MODIFY | ACCESS3_EXTEND | ACCESS3_DELETE,
    )?;
    println!("access mask granted by server: 0x{:x}", access.access);

    let first_five = client.read_exact_at(&object, 0, 5)?;
    println!(
        "first five bytes: {:?}",
        String::from_utf8_lossy(&first_five)
    );

    let middle = client.read_range(&object, 7, 14)?;
    println!("range read: {:?}", String::from_utf8_lossy(&middle));

    let mut downloaded = Vec::new();
    let downloaded_len = client.read_to_writer(&object, &mut downloaded)?;
    println!(
        "streamed object into local Vec: {downloaded_len} bytes, {}",
        String::from_utf8_lossy(&downloaded)
    );

    let mut upload = Cursor::new(STREAMED);
    let uploaded_len = client.write_atomic_from_reader_with_mode_and_stability(
        &streamed,
        &mut upload,
        0o644,
        StableHow::FileSync,
    )?;
    println!("streamed upload wrote {uploaded_len} bytes");

    client.append_with_stability(&streamed, b"appended\n", StableHow::FileSync)?;
    client.write_at_with_stability(&streamed, 0, b"STREAMED", StableHow::FileSync)?;
    client.truncate(&streamed, 24)?;
    let commit = client.commit(&streamed, 0, 0)?;
    println!("commit verifier: {:02x?}", commit.verifier);

    client.create_new(&created, 0o600)?;
    client.write_at_with_stability(
        &created,
        0,
        b"created with create_new\n",
        StableHow::FileSync,
    )?;
    let _ = optional(
        "create_new existing file",
        client.create_new(&created, 0o600),
    );

    let copied_len = client.copy_atomic_with_stability(&streamed, &copied, StableHow::FileSync)?;
    println!("copied {copied_len} bytes from {streamed} to {copied}");

    client.rename(&copied, &renamed)?;
    let _ = optional("touch", client.touch(&renamed));
    let _ = optional("set_mode", client.set_mode(&renamed, 0o644));

    client.create_dir_all(&nested_dir, 0o755)?;
    client.write_atomic(&nested_file, b"nested file\n")?;

    demonstrate_optional_links(client, &object, work_dir)?;
    demonstrate_directory_reads(client, work_dir)?;
    demonstrate_filesystem_queries(client, work_dir)?;
    demonstrate_error_handling(client, work_dir);
    demonstrate_reconnect(client, work_dir)?;

    Ok(())
}

pub fn read_dir(&mut self, path: &str) -> Result<Vec<DirEntry>>

Reads all entries in a directory, subject to the client’s entry limit.

Examples found in repository

examples/basic.rs (line 47)

fn main() -> nfs::Result<()> {
    // Usage:
    //   cargo run --example basic -- 127.0.0.1:/export /writable-dir
    //
    // The first argument is an NFSv3 target in `host:/export` form.
    // The second argument is a writable directory inside that export.
    let mut args = std::env::args().skip(1);
    let target = args
        .next()
        .unwrap_or_else(|| "127.0.0.1:/export".to_owned());
    let dir = args.next().unwrap_or_else(|| "/".to_owned());
    let file = remote_path(&dir, &format!("nfs-rs-v3-{}.txt", std::process::id()));

    let mut client = ClientBuilder::from_target(&target)?
        .timeout(Some(Duration::from_secs(10)))
        .connect()?;

    println!("connected to NFSv3 target {target}");
    println!("writing {file}");
    client.write_atomic(&file, CONTENT)?;

    let data = client.read(&file)?;
    println!("read: {}", String::from_utf8_lossy(&data));

    let range = client.read_range(&file, 0, 5)?;
    println!("first 5 bytes: {:?}", String::from_utf8_lossy(&range));

    let metadata = client.metadata(&file)?;
    println!(
        "metadata: type={:?} size={} mode={:o}",
        metadata.file_type,
        metadata.size,
        metadata.mode & 0o777
    );

    println!("first entries in {dir}:");
    for entry in client.read_dir(&dir)?.into_iter().take(8) {
        println!("  {}", entry.name);
    }

    client.remove_if_exists(&file)?;
    println!("removed {file}");
    Ok(())
}

pub fn read_dir_limited( &mut self, path: &str, max_entries: usize, ) -> Result<Vec<DirEntry>>

Reads all entries in a directory with a per-call entry limit.

Examples found in repository

examples/v3_cookbook.rs (line 171)

fn demonstrate_directory_reads(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    println!("limited directory listing:");
    for entry in client.read_dir_limited(work_dir, 16)? {
        let kind = entry
            .attributes
            .as_ref()
            .map(|attrs| format!("{:?}", attrs.file_type))
            .unwrap_or_else(|| "unknown".to_owned());
        println!("  {} fileid={} type={kind}", entry.name, entry.fileid);
    }

    println!("paged directory listing:");
    let mut cursor: Option<DirPageCursor> = None;
    loop {
        let page = client.read_dir_page_limited(work_dir, cursor, 4)?;
        for entry in &page.entries {
            println!("  page entry: {}", entry.name);
        }
        if page.is_eof() {
            break;
        }
        cursor = page.next_cursor;
    }

    Ok(())
}

pub fn read_dir_page( &mut self, path: &str, cursor: Option<DirPageCursor>, ) -> Result<DirPage>

Reads one page of directory entries.

pub fn read_dir_page_limited( &mut self, path: &str, cursor: Option<DirPageCursor>, max_entries: usize, ) -> Result<DirPage>

Reads one page of directory entries with a per-page entry limit.

Examples found in repository

examples/v3_cookbook.rs (line 183)

fn demonstrate_directory_reads(client: &mut Client, work_dir: &str) -> nfs::Result<()> {
    println!("limited directory listing:");
    for entry in client.read_dir_limited(work_dir, 16)? {
        let kind = entry
            .attributes
            .as_ref()
            .map(|attrs| format!("{:?}", attrs.file_type))
            .unwrap_or_else(|| "unknown".to_owned());
        println!("  {} fileid={} type={kind}", entry.name, entry.fileid);
    }

    println!("paged directory listing:");
    let mut cursor: Option<DirPageCursor> = None;
    loop {
        let page = client.read_dir_page_limited(work_dir, cursor, 4)?;
        for entry in &page.entries {
            println!("  page entry: {}", entry.name);
        }
        if page.is_eof() {
            break;
        }
        cursor = page.next_cursor;
    }

    Ok(())
}

pub fn unmount(self) -> Result<()>

Sends an NFSv3 unmount request for the export.

Examples found in repository

examples/v3_cookbook.rs (line 46)

fn main() -> nfs::Result<()> {
    let config = Config::from_env();
    let mut client = connect(&config.target)?;

    println!("connected to NFSv3 target {}", config.target);
    if let Some(info) = client.fsinfo() {
        println!(
            "server fsinfo: read_preferred={} write_preferred={} dir_preferred={}",
            info.read_preferred, info.write_preferred, info.dir_preferred
        );
    }

    let work_dir = remote_path(
        &config.remote_dir,
        &format!("nfs-rs-v3-cookbook-{}", std::process::id()),
    );
    client.remove_all_if_exists(&work_dir)?;
    client.create_dir_all(&work_dir, 0o755)?;

    let flow_result = run_filesystem_flow(&mut client, &work_dir);
    let cleanup_result = client.remove_all_if_exists(&work_dir);
    let unmount_result = client.unmount();
    finish(flow_result, cleanup_result, unmount_result)
}

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.