filedescriptor

https://docs.rs/filedescriptor/0.8.3
Admin
A Rust crate that provides ergonomic abstractions for managing platform-level file descriptors with...
Tokens:33,398
Snippets:268
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Handling File Metadata with and_then

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Example of using `and_then` for file system operations that might fail.

```APIDOC
## File Metadata Example with `and_then`

### Description
Uses `and_then` to chain file metadata retrieval, handling potential errors like `NotFound`.

### Method
`and_then`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Poll File Descriptors for Readiness

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/index.html

Demonstrates using the `poll` function to check for I/O readiness on a socket pair. This example shows how to use `poll` with a timeout and checks for read events. Requires the `filedescriptor` crate and `std::time::Duration`.

```rust
use filedescriptor::*;
use std::time::Duration;
use std::io::{Read, Write};

let (mut a, mut b) = filedescriptor::socketpair()?;
let mut poll_array = [pollfd {
   fd: a.as_socket_descriptor(),
   events: POLLIN,
   revents: 0
}];
// sleeps for 20 milliseconds because `a` is not yet ready
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 0);

b.write(b"hello")?;

// Now a is ready for read
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 1);
```

--------------------------------

### Getting Metadata with Error Handling

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Demonstrates using `metadata().and_then(|md| md.modified())` to get file modification times, handling potential errors like `ErrorKind::NotFound`.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Providing a Default Value with unwrap_or

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Use `unwrap_or` to get the `Ok` value or a provided default if the Result is `Err`. Arguments are eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Create and use a Pipe

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.Pipe.html

Demonstrates initializing a pipe, writing data to the write end, and reading it back from the read end.

```rust
use filedescriptor::{Pipe, Error};
use std::io::{Read,Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");
```

--------------------------------

### Use a Kernel Pipe

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Demonstrates creating a pipe and performing read/write operations.

```rust
use filedescriptor::{Pipe, Error};
use std::io::{Read,Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");
# Ok::<(), Error>(())
```

--------------------------------

### Create and manage a Pipe

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Shows how to create a pipe and manage the lifetime of its read and write ends.

```rust
use filedescriptor::{Pipe, Error};
use std::io::{Read, Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");
# Ok::<(), Error>(())
```

--------------------------------

### Convert to Stdio or File

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Convenience methods to create standard library Stdio or File objects from a FileDescriptor.

```rust
pub fn as_stdio(&self) -> Result<std::process::Stdio> {
        self.as_stdio_impl()
    }

    pub fn as_file(&self) -> Result<std::fs::File> {
        self.as_file_impl()
    }
```

--------------------------------

### Lazily Computing a Default Value with unwrap_or_else

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Use `unwrap_or_else` to get the `Ok` value or compute a default value using a closure if the Result is `Err`. This allows for lazy evaluation of the default.

```rust
fn count(x: &str) -> usize { x.len() }

assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

--------------------------------

### Create and Use a Pipe

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/index.html

Conveniently creates a pipe and manages the read and write ends. Ensure the write end is dropped before reading to avoid blocking indefinitely. Requires the `filedescriptor` crate.

```rust
use filedescriptor::{Pipe, Error};
use std::io::{Read, Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");
```

--------------------------------

### Adapter Methods

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.FileDescriptor.html

Methods for creating adapters for Read and Write operations.

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Read`.

### Method
`by_ref` (for Read)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **&mut Self** - A mutable reference to the adapter.

#### Response Example
None
```

```APIDOC
## fn bytes(self) -> Bytes<Self>

### Description
Transforms this `Read` instance to an `Iterator` over its bytes.

### Method
`bytes`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Bytes<Self>** - An iterator over the bytes.

#### Response Example
None
```

```APIDOC
## fn chain<R>(self, next: R) -> Chain<Self, R>

### Description
Creates an adapter which will chain this stream with another.

### Method
`chain`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Chain<Self, R>** - The chained stream adapter.

#### Response Example
None
```

```APIDOC
## fn take(self, limit: u64) -> Take<Self>

### Description
Creates an adapter which will read at most `limit` bytes from it.

### Method
`take`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Take<Self>** - The limited read adapter.

#### Response Example
None
```

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Write`.

### Method
`by_ref` (for Write)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **&mut Self** - A mutable reference to the adapter.

#### Response Example
None
```

--------------------------------

### Implement CloneToUninit (Nightly)

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.pollfd.html

Provides an experimental, nightly-only `clone_to_uninit` method for types that implement `Clone`, allowing copying to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Create and Use Socket Pair

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/index.html

Creates a pair of connected sockets that function on both POSIX and Windows systems. Dropping one end before reading from the other demonstrates basic communication. Requires the `filedescriptor` crate.

```rust
use std::io::{Read, Write};
use filedescriptor::Error;

let (mut a, mut b) = filedescriptor::socketpair()?;
a.write(b"hello")?;
drop(a);

let mut s = String::new();
b.read_to_string(&mut s)?;
assert_eq!(s, "hello");
```

--------------------------------

### Pipe Management

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Creating and using kernel pipes.

```APIDOC
## Pipe::new

### Description
Creates a new pair of FileDescriptors connected via a kernel pipe.

### Response
- **Result<Pipe>** - A struct containing the read and write FileDescriptor ends.
```

--------------------------------

### Create Pipe

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Creates a new pipe, using pipe2 on Linux for atomic CLOEXEC, or manual configuration on other platforms.

```rust
#[cfg(target_os = "linux")]
    pub fn new() -> Result<Pipe> {
        let mut fds = [-1i32; 2];
        let res = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_CLOEXEC) };
        if res == -1 {
            Err(Error::Pipe(std::io::Error::last_os_error()))
        } else {
            let read = FileDescriptor {
                handle: OwnedHandle {
                    handle: fds[0],
                    handle_type: (),
                },
            };
            let write = FileDescriptor {
                handle: OwnedHandle {
                    handle: fds[1],
                    handle_type: (),
                },
            };
            Ok(Pipe { read, write })
        }
    }
```

```rust
#[cfg(not(target_os = "linux"))]
    pub fn new() -> Result<Pipe> {
        let mut fds = [-1i32; 2];
        let res = unsafe { libc::pipe(fds.as_mut_ptr()) };
        if res == -1 {
            Err(Error::Pipe(std::io::Error::last_os_error()))
        } else {
            let mut read = FileDescriptor {
                handle: OwnedHandle {
                    handle: fds[0],
                    handle_type: (),
                },
            };
            let mut write = FileDescriptor {
                handle: OwnedHandle {
                    handle: fds[1],
                    handle_type: (),
                },
            };
            read.handle.cloexec()?;
            write.handle.cloexec()?;
            Ok(Pipe { read, write })
        }
    }
```

--------------------------------

### Create a socketpair

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Creates a pair of connected SOCK_STREAM sockets that function on both POSIX and Windows systems.

```rust
use std::io::{Read, Write};
use filedescriptor::Error;

let (mut a, mut b) = filedescriptor::socketpair()?;
a.write(b"hello")?;
drop(a);

let mut s = String::new();
b.read_to_string(&mut s)?;
assert_eq!(s, "hello");
# Ok::<(), Error>(())
```

--------------------------------

### Create Pipe

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Creates a new pipe, returning a pair of file descriptors for reading and writing.

```APIDOC
## POST /create_pipe

### Description
Creates a new pipe, returning a pair of file descriptors for reading and writing.

### Method
POST

### Endpoint
`/create_pipe`

### Parameters
None

### Response
#### Success Response (200)
- **read_fd** (FileDescriptor) - The file descriptor for reading from the pipe.
- **write_fd** (FileDescriptor) - The file descriptor for writing to the pipe.

#### Response Example
```json
{
  "read_fd": "<read_file_descriptor_representation>",
  "write_fd": "<write_file_descriptor_representation>"
}
```
```

--------------------------------

### Trait Implementations

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Summary of trait implementations for Result including Hash, Ord, PartialEq, and PartialOrd.

```APIDOC
## Trait Implementations

### Hash
- **hash(&self, state: &mut __H)**: Feeds this value into the given Hasher.
- **hash_slice<H>(data: &[Self], state: &mut H)**: Feeds a slice of this type into the given Hasher.

### Ord
- **cmp(&self, other: &Result<T, E>) -> Ordering**: Returns an Ordering between self and other.
- **max(self, other: Self) -> Self**: Compares and returns the maximum of two values.
- **min(self, other: Self) -> Self**: Compares and returns the minimum of two values.
- **clamp(self, min: Self, max: Self) -> Self**: Restrict a value to a certain interval.

### PartialEq
- **eq(&self, other: &Result<T, E>) -> bool**: Tests for self and other values to be equal.
- **ne(&self, other: &Rhs) -> bool**: Tests for inequality.
```

--------------------------------

### macOS poll(2) implementation using select(2)

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

This module provides a workaround for macOS's broken poll(2) implementation by using the select(2) system call. It requires the `libc` crate and `std::os::unix::io::RawFd`.

```rust
mod macos {
    use super::*;
    use libc::{fd_set, timeval, FD_ISSET, FD_SET, FD_SETSIZE, FD_ZERO, POLLERR, POLLIN, POLLOUT};
    use std::os::unix::io::RawFd;

    struct FdSet {
        set: fd_set,
    }

    #[inline]
    fn check_fd(fd: RawFd) -> Result<()>
    {
        if fd < 0 {
            return Err(Error::IllegalFdValue(fd.into()));
        }
        if fd as usize >= FD_SETSIZE {
            return Err(Error::FdValueOutsideFdSetSize(fd.into()));
        }
        Ok(())
    }

    impl FdSet {
        pub fn new() -> Self {
            unsafe {
                let mut set = std::mem::MaybeUninit::uninit();
                FD_ZERO(set.as_mut_ptr());
                Self {
                    set: set.assume_init(),
                }
            }
        }

        pub fn add(&mut self, fd: RawFd) -> Result<()>
        {
            check_fd(fd)?;
            unsafe {
                FD_SET(fd, &mut self.set);
            }
            Ok(())
        }

        pub fn contains(&mut self, fd: RawFd) -> bool {
            check_fd(fd).unwrap();
            unsafe { FD_ISSET(fd, &mut self.set) }
        }
    }

    fn materialize(set: &mut Option<FdSet>) -> &mut FdSet {
        set.get_or_insert_with(FdSet::new)
    }

    fn set_ptr(set: &mut Option<FdSet>) -> *mut fd_set {
        set.as_mut()
            .map(|s| &mut s.set as *mut _)
            .unwrap_or_else(std::ptr::null_mut)
    }

    fn is_set(set: &mut Option<FdSet>, fd: RawFd) -> bool {
        set.as_mut().map(|s| s.contains(fd)).unwrap_or(false)
    }

    pub fn poll_impl(pfd: &mut [pollfd], duration: Option<Duration>) -> Result<usize> {
        let mut read_set = None;
        let mut write_set = None;
        let mut exception_set = None;
        let mut nfds = 0;

        for item in pfd.iter_mut() {
            item.revents = 0;

            nfds = nfds.max(item.fd);

            if item.events & POLLIN != 0 {
                materialize(&mut read_set).add(item.fd)?;
            }
            if item.events & POLLOUT != 0 {
                materialize(&mut write_set).add(item.fd)?;
            }
            materialize(&mut exception_set).add(item.fd)?;
        }

        let mut timeout = duration.map(|d| timeval {
            tv_sec: d.as_secs() as _,
            tv_usec: d.subsec_micros() as _,
        });

        let res = unsafe {
            libc::select(
                nfds + 1,
                set_ptr(&mut read_set),
                set_ptr(&mut write_set),
                set_ptr(&mut exception_set),
                timeout
                    .as_mut()
                    .map(|t| t as *mut _)
                    .unwrap_or_else(std::ptr::null_mut),
            )
        };

        if res < 0 {
            Err(std::io::Error::last_os_error().into())
        } else {
            for item in pfd.iter_mut() {
                if is_set(&mut read_set, item.fd) {
                    item.revents |= POLLIN;
                }
                if is_set(&mut write_set, item.fd) {
                    item.revents |= POLLOUT;
                }
                if is_set(&mut exception_set, item.fd) {
                    item.revents |= POLLERR;
                }
            }

            Ok(res as usize)
        }
    }
}
```

```rust
pub use macos::poll_impl;
```

--------------------------------

### Implement dup2 for Linux with O_CLOEXEC fallback

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

This function implements dup2 for Linux, attempting to use dup3 with O_CLOEXEC. If that fails due to EINVAL (e.g., on older kernels or WSL), it falls back to non-atomic dup2.

```rust
pub(crate) unsafe fn dup2_impl<F: AsRawFileDescriptor>(fd: &F, dest_fd: RawFd) -> Result<Self> {
        let fd = fd.as_raw_file_descriptor();

        #[cfg(not(target_os = "linux"))]
        return Self::non_atomic_dup2(fd, dest_fd);

        #[cfg(target_os = "linux")]
        {
            let duped = libc::dup3(fd, dest_fd, libc::O_CLOEXEC);

            if duped == -1 {
                let err = std::io::Error::last_os_error();
                if let Some(libc::EINVAL) = err.raw_os_error() {
                    // We may be running on eg: WSL or an old kernel that
                    // doesn't support O_CLOEXEC; fall back.
                    Self::non_atomic_dup2(fd, dest_fd)
                } else {
                    Err(Error::Dup2 {
                        src_fd: fd.into(),
                        dest_fd: dest_fd.into(),
                        source: err,
                    })
                }
            } else {
                Ok(OwnedHandle {
                    handle: duped,
                    handle_type: (),
                })
            }
        }
    }
```

--------------------------------

### Create Socket Pair

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Creates a pair of connected sockets, handling platform-specific flags for CLOEXEC.

```rust
#[cfg(target_os = "linux")]
#[doc(hidden)]
pub fn socketpair_impl() -> Result<(FileDescriptor, FileDescriptor)> {
    let mut fds = [-1i32; 2];
    let res = unsafe {
        libc::socketpair(
            libc::PF_LOCAL,
            libc::SOCK_STREAM | libc::SOCK_CLOEXEC,
            0,
            fds.as_mut_ptr(),
        )
    };
    if res == -1 {
        Err(Error::Socketpair(std::io::Error::last_os_error()))
    } else {
        let read = FileDescriptor {
            handle: OwnedHandle {
                handle: fds[0],
                handle_type: (),
            },
        };
        let write = FileDescriptor {
            handle: OwnedHandle {
                handle: fds[1],
                handle_type: (),
            },
        };
        Ok((read, write))
    }
}
```

```rust
#[cfg(not(target_os = "linux"))]
#[doc(hidden)]
pub fn socketpair_impl() -> Result<(FileDescriptor, FileDescriptor)> {
    let mut fds = [-1i32; 2];
    let res = unsafe { libc::socketpair(libc::AF_UNIX, libc::SOCK_STREAM, 0, fds.as_mut_ptr()) };
    if res == -1 {
        Err(Error::Socketpair(std::io::Error::last_os_error()))
    } else {
        let mut read = FileDescriptor {
            handle: OwnedHandle {
                handle: fds[0],
                handle_type: (),
            },
        };
        let mut write = FileDescriptor {
            handle: OwnedHandle {
                handle: fds[1],
                handle_type: (),
            },
        };
        read.handle.cloexec()?;
        write.handle.cloexec()?;
        Ok((read, write))
    }
}
```

--------------------------------

### Create references with as_ref

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Converts from &Result<T, E> to Result<&T, &E>.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Create and Use FileDescriptor for Stdout

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/index.html

Demonstrates avoiding conditional code when accessing platform-specific file descriptors like stdout. Requires the `filedescriptor` crate.

```rust
use filedescriptor::{FileDescriptor, FromRawFileDescriptor, Result};
use std::io::Write;

fn get_stdout() -> Result<FileDescriptor> {
  let stdout = std::io::stdout();
  let handle = stdout.lock();
  FileDescriptor::dup(&handle)
}

fn print_something() -> Result<()> {
   get_stdout()?.write(b"hello")?;
   Ok(())
}
```

--------------------------------

### Pipe::new()

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.Pipe.html

Constructs a new Pipe, returning the readable and writable ends.

```APIDOC
## impl Pipe

### pub fn new() -> Result<Pipe>

Creates a new pipe and returns a `Pipe` struct containing the read and write `FileDescriptor`s.
```

--------------------------------

### socketpair

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Creates a pair of connected sockets.

```APIDOC
## socketpair

### Description
Creates a pair of connected SOCK_STREAM sockets.

### Response
- **Result<(FileDescriptor, FileDescriptor)>** - Returns a tuple containing two connected FileDescriptor objects or an error.
```

--------------------------------

### FileDescriptor Crate Overview

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/all.html

This section lists the main components of the filedescriptor crate, including structs, enums, traits, functions, type aliases, and constants.

```APIDOC
## FileDescriptor Crate Components

### Structs
  * FileDescriptor
  * OwnedHandle
  * Pipe
  * pollfd

### Enums
  * Error
  * StdioDescriptor

### Traits
  * AsRawFileDescriptor
  * AsRawSocketDescriptor
  * FromRawFileDescriptor
  * FromRawSocketDescriptor
  * IntoRawFileDescriptor
  * IntoRawSocketDescriptor

### Functions
  * poll
  * socketpair

### Type Aliases
  * RawFileDescriptor
  * Result
  * SocketDescriptor

### Constants
  * POLLERR
  * POLLHUP
  * POLLIN
  * POLLOUT
```

--------------------------------

### expect

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Returns the contained Ok value, or panics if the result is Err.

```APIDOC
## expect(self, msg: &str) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`, with a panic message including the passed message.

### Parameters
- **msg** (&str) - Required - The message to include in the panic if the result is an error.
```

--------------------------------

### Redirect Stdio

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Redirects standard input/output streams to the underlying handle.

```rust
pub fn redirect_stdio<F: AsRawFileDescriptor>(f: &F, stdio: StdioDescriptor) -> Result<Self> {
        Self::redirect_stdio_impl(f, stdio)
    }
```

--------------------------------

### unwrap

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Returns the contained Ok value, or panics if the result is Err.

```APIDOC
## unwrap(self) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`.
```

--------------------------------

### Result `or_else` Method

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Explains and demonstrates the `or_else` method for lazily evaluating a fallback `Result`.

```APIDOC
## `or_else`

### Description
Calls `op` if the result is `Err`, otherwise returns the `Ok` value of `self`. This function can be used for control flow based on result values.

### Method
`or_else`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
fn err(x: u32) -> Result<u32, u32> { Err(x) }

assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Redirect Standard I/O

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Redirects standard input/output/error to a provided file descriptor and returns the original descriptor.

```rust
pub(crate) fn redirect_stdio_impl<F: AsRawFileDescriptor>(
        f: &F,
        stdio: StdioDescriptor,
    ) -> Result<Self> {
        let std_descriptor = match stdio {
            StdioDescriptor::Stdin => libc::STDIN_FILENO,
            StdioDescriptor::Stdout => libc::STDOUT_FILENO,
            StdioDescriptor::Stderr => libc::STDERR_FILENO,
        };

        let std_original = FileDescriptor::dup(&std_descriptor)?;
        // Assign f into std_descriptor, then convert to an fd so that
        // we don't close it when the returned FileDescriptor is dropped.
        // Then we discard/ignore the fd because it is nominally owned by
        // the stdio machinery for the process
        let _ = unsafe { FileDescriptor::dup2(f, std_descriptor) }?.into_raw_fd();
        Self::no_cloexec(std_descriptor)?;

        Ok(std_original)
    }
```

--------------------------------

### Result `unwrap_or_else` Method

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Explains and demonstrates the `unwrap_or_else` method for lazily computing a default value.

```APIDOC
## `unwrap_or_else`

### Description
Returns the contained `Ok` value or computes it from a closure. This is lazily evaluated.

### Method
`unwrap_or_else`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
fn count(x: &str) -> usize { x.len() }

assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Blanket Implementations

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.FileDescriptor.html

Details on blanket implementations for FileDescriptor.

```APIDOC
## impl<T> Any for T

### Description
Implementation of the `Any` trait.

### Method
`type_id`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **TypeId** - The `TypeId` of `self`.

#### Response Example
None
```

```APIDOC
## impl<T> AsRawFileDescriptor for T

### Description
Implementation of the `AsRawFileDescriptor` trait.

### Method
`as_raw_file_descriptor`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **i32** - The raw file descriptor.

#### Response Example
None
```

```APIDOC
## impl<T> AsRawSocketDescriptor for T

### Description
Implementation of the `AsRawSocketDescriptor` trait.

### Method
`as_socket_descriptor`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **i32** - The socket descriptor.

#### Response Example
None
```

```APIDOC
## impl<T> Borrow<T> for T

### Description
Implementation of the `Borrow` trait.

### Method
`borrow`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **&T** - An immutable reference to the borrowed value.

#### Response Example
None
```

```APIDOC
## impl<T> BorrowMut<T> for T

### Description
Implementation of the `BorrowMut` trait.

### Method
`borrow_mut`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **&mut T** - A mutable reference to the borrowed value.

#### Response Example
None
```

```APIDOC
## impl<T> From<T> for T

### Description
Implementation of the `From` trait.

### Method
`from`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **T** - The argument unchanged.

#### Response Example
None
```

```APIDOC
## impl<T> FromRawFileDescriptor for T

### Description
Implementation of the `FromRawFileDescriptor` trait.

### Method
`from_raw_file_descriptor`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **T** - The constructed type from the raw file descriptor.

#### Response Example
None
```

```APIDOC
## impl<T> FromRawSocketDescriptor for T

### Description
Implementation of the `FromRawSocketDescriptor` trait.

### Method
`from_socket_descriptor`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **T** - The constructed type from the raw socket descriptor.

#### Response Example
None
```

--------------------------------

### Result `or` Method

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Explains and demonstrates the `or` method for providing a default `Result`.

```APIDOC
## `or`

### Description
Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`. Arguments passed to `or` are eagerly evaluated.

### Method
`or`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Result `unwrap_or` Method

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Explains and demonstrates the `unwrap_or` method for providing a default value.

```APIDOC
## `unwrap_or`

### Description
Returns the contained `Ok` value or a provided default. Arguments passed to `unwrap_or` are eagerly evaluated.

### Method
`unwrap_or`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Configure Non-blocking IO

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Attempts to set the non-blocking mode for the file descriptor, primarily supported for sockets.

```rust
pub fn set_non_blocking(&mut self, non_blocking: bool) -> Result<()> {
        self.set_non_blocking_impl(non_blocking)
    }
```

--------------------------------

### FileDescriptor Methods

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.FileDescriptor.html

This section covers the various methods available for the FileDescriptor struct, including duplication, creation, and stream redirection.

```APIDOC
### impl FileDescriptor

#### pub unsafe fn dup2<F: AsRawFileDescriptor>( f: &F, dest_fd: RawFd, ) -> Result<Self>

Attempt to duplicate the underlying handle from an object that is representable as the system `RawFileDescriptor` type and assign it to a destination file descriptor. It then returns a `FileDescriptor` wrapped around the duplicate. Since the duplication requires kernel resources that may not be available, this is a potentially fallible operation. The returned handle has a separate lifetime from the source, but references the same object at the kernel level.

#### pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self

Create a new descriptor from some object that is convertible into the system `RawFileDescriptor` type. This consumes the parameter and replaces it with a `FileDescriptor` instance.

#### pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Result<Self>

Attempt to duplicate the underlying handle from an object that is representable as the system `RawFileDescriptor` type and return a `FileDescriptor` wrapped around the duplicate. Since the duplication requires kernel resources that may not be available, this is a potentially fallible operation. The returned handle has a separate lifetime from the source, but references the same object at the kernel level.

#### pub fn try_clone(&self) -> Result<Self>

Attempt to duplicate the underlying handle and return a `FileDescriptor` wrapped around the duplicate. Since the duplication requires kernel resources that may not be available, this is a potentially fallible operation. The returned handle has a separate lifetime from the source, but references the same object at the kernel level.

#### pub fn as_stdio(&self) -> Result<Stdio>

A convenience method for creating a `std::process::Stdio` object to be used for eg: redirecting the stdio streams of a child process. The `Stdio` is created using a duplicated handle so that the source handle remains alive.

#### pub fn as_file(&self) -> Result<File>

A convenience method for creating a `std::fs::File` object. The `File` is created using a duplicated handle so that the source handle remains alive.

#### pub fn set_non_blocking(&mut self, non_blocking: bool) -> Result<()>

Attempt to change the non-blocking IO mode of the file descriptor. Not all kinds of file descriptor can be placed in non-blocking mode on all systems, and some file descriptors will claim to be in non-blocking mode but it will have no effect. File descriptors based on sockets are the most portable type that can be successfully made non-blocking.

#### pub fn redirect_stdio<F: AsRawFileDescriptor>( f: &F, stdio: StdioDescriptor, ) -> Result<Self>

Attempt to redirect stdio to the underlying handle and return a `FileDescriptor` wrapped around the original stdio source. Since the redirection requires kernel resources that may not be available, this is a potentially fallible operation. Supports stdin, stdout, and stderr redirections.
```

--------------------------------

### FileDescriptor Operations

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

Methods for managing, cloning, and converting file descriptors.

```APIDOC
## FileDescriptor::dup

### Description
Duplicates the underlying handle from an object representable as a RawFileDescriptor.

### Parameters
#### Request Body
- **f** (AsRawFileDescriptor) - Required - The object to duplicate.

### Response
- **Result<Self>** - A new FileDescriptor instance.
```

```APIDOC
## FileDescriptor::try_clone

### Description
Attempts to duplicate the underlying handle of the current FileDescriptor.

### Response
- **Result<Self>** - A new FileDescriptor instance.
```

```APIDOC
## FileDescriptor::set_non_blocking

### Description
Attempts to change the non-blocking IO mode of the file descriptor.

### Parameters
#### Request Body
- **non_blocking** (bool) - Required - The desired non-blocking state.
```

--------------------------------

### Implement FromRawFd for FileDescriptor

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Implements the `FromRawFd` trait for `FileDescriptor`, enabling the creation of a `FileDescriptor` from a raw file descriptor.

```rust
impl FromRawFd for FileDescriptor {
    unsafe fn from_raw_fd(fd: RawFd) -> Self {
        Self {
            handle: OwnedHandle::from_raw_fd(fd),
        }
    }
}
```

--------------------------------

### Map Result or default with map_or

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Returns a default value if Err, or applies a function if Ok.

```rust
let x: Result<_, &str> = Ok("foo");
assert_eq!(x.map_or(42, |v| v.len()), 3);

let x: Result<&str, _> = Err("bar");
assert_eq!(x.map_or(42, |v| v.len()), 42);
```

--------------------------------

### Blanket Implementations for Generic Types

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.OwnedHandle.html

Blanket implementations that apply to generic types, demonstrating conversions and descriptor access.

```APIDOC
## Blanket Implementations

### impl<T> Any for T

#### fn type_id(&self) -> TypeId

##### Description
Gets the `TypeId` of `self`.

### impl<T> AsRawFileDescriptor for T

#### fn as_raw_file_descriptor(&self) -> i32

### impl<T> AsRawSocketDescriptor for T

#### fn as_socket_descriptor(&self) -> i32

### impl<T> Borrow<T> for T

#### fn borrow(&self) -> &T

##### Description
Immutably borrows from an owned value.

### impl<T> BorrowMut<T> for T

#### fn borrow_mut(&mut self) -> &mut T

##### Description
Mutably borrows from an owned value.

### impl<T> From<T> for T

#### fn from(t: T) -> T

##### Description
Returns the argument unchanged.

### impl<T> FromRawFileDescriptor for T

#### unsafe fn from_raw_file_descriptor(fd: i32) -> T

### impl<T> FromRawSocketDescriptor for T

#### unsafe fn from_socket_descriptor(fd: i32) -> T

### impl<T, U> Into<U> for T

#### fn into(self) -> U

##### Description
Calls `U::from(self)`.

### impl<T> IntoRawFileDescriptor for T

#### fn into_raw_file_descriptor(self) -> i32

### impl<T> IntoRawSocketDescriptor for T

#### fn into_socket_descriptor(self) -> i32

### impl<T, U> TryFrom<U> for T

#### type Error = Infallible

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

##### Description
Performs the conversion.

### impl<T, U> TryInto<U> for T

#### type Error = <U as TryFrom<T>>::Error

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

##### Description
Performs the conversion.
```

--------------------------------

### Result Chaining with and_then

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Demonstrates chaining fallible operations using `and_then`.

```APIDOC
## `and_then`

### Description
Chains fallible operations that may return `Err`.

### Method
`and_then`

### Endpoint
N/A (Method on `Result` type)

### Parameters
None

### Request Example
```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}

assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### FileDescriptor Trait Implementations

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/struct.FileDescriptor.html

Information about trait implementations for FileDescriptor.

```APIDOC
## impl Freeze for FileDescriptor

### Description
Auto trait implementation for `Freeze`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

```APIDOC
## impl RefUnwindSafe for FileDescriptor

### Description
Auto trait implementation for `RefUnwindSafe`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

```APIDOC
## impl Send for FileDescriptor

### Description
Auto trait implementation for `Send`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

```APIDOC
## impl Sync for FileDescriptor

### Description
Auto trait implementation for `Sync`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

```APIDOC
## impl Unpin for FileDescriptor

### Description
Auto trait implementation for `Unpin`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

```APIDOC
## impl UnwindSafe for FileDescriptor

### Description
Auto trait implementation for `UnwindSafe`.

### Method
None

### Parameters
None

### Request Example
None

### Response
None

### Response Example
None
```

--------------------------------

### Convert Result to Option with ok

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Converts a Result into an Option, discarding the error.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### Redirect Standard I/O

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Redirects a given file descriptor to one of the standard I/O streams (stdin, stdout, stderr).

```APIDOC
## POST /redirect_stdio

### Description
Redirects a given file descriptor to one of the standard I/O streams (stdin, stdout, stderr).

### Method
POST

### Endpoint
`/redirect_stdio`

### Parameters
#### Request Body
- **f** (AsRawFileDescriptor) - Required - The file descriptor to redirect.
- **stdio** (StdioDescriptor) - Required - The target standard I/O stream (Stdin, Stdout, Stderr).

### Request Example
```json
{
  "f": "<file_descriptor_representation>",
  "stdio": "Stdout"
}
```

### Response
#### Success Response (200)
- **original_descriptor** (FileDescriptor) - The original file descriptor of the redirected stream.

#### Response Example
```json
{
  "original_descriptor": "<original_file_descriptor_representation>"
}
```
```

--------------------------------

### Unwrap Result or default

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Returns the contained Ok value or the default value for the type if the result is an Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Create Socket Pair

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/unix.rs.html

Creates a pair of connected sockets, useful for inter-process communication.

```APIDOC
## POST /create_socketpair

### Description
Creates a pair of connected sockets, useful for inter-process communication.

### Method
POST

### Endpoint
`/create_socketpair`

### Parameters
None

### Response
#### Success Response (200)
- **fd1** (FileDescriptor) - The first file descriptor in the socket pair.
- **fd2** (FileDescriptor) - The second file descriptor in the socket pair.

#### Response Example
```json
{
  "fd1": "<file_descriptor_representation_1>",
  "fd2": "<file_descriptor_representation_2>"
}
```
```

--------------------------------

### Pipe Creation and Management

Source: https://docs.rs/filedescriptor/0.8.3/index.html

The Pipe type provides a convenient way to create a pipe and manage the lifetime of both the read and write ends.

```APIDOC
## Pipe

### Description
Creates a new pipe and returns a structure containing the readable and writable ends.

### Request Example
```rust
let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);
```
```

--------------------------------

### Function: socketpair

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/index.html

Creates a pair of connected SOCK_STREAM sockets that function on both POSIX and Windows systems.

```APIDOC
## socketpair

### Description
Creates a pair of connected sockets that can be used for bidirectional communication.

### Method
Function

### Response
- **(FileDescriptor, FileDescriptor)** - A tuple containing the two connected socket ends.
```

--------------------------------

### Result::ok

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/type.Result.html

Converts a Result<T, E> into an Option<T>, consuming the Result and discarding any error.

```APIDOC
## pub fn ok(self) -> Option<T>

### Description
Converts from `Result<T, E>` to `Option<T>`.
Consumes `self`, and discards the error, if any.

### Method
`self.ok()`

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

### Response Example
```rust
// Returns Some(value) if Ok, None if Err
```
```

--------------------------------

### Implementing From<Error> for Error

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/enum.Error.html

Provides a conversion from an existing Error to itself, useful in error handling chains.

```rust
impl From<Error> for Error
Source
fn from(source: Error) -> Self
```

--------------------------------

### FromRawSocketDescriptor Implementation

Source: https://docs.rs/filedescriptor/0.8.3/filedescriptor/trait.FromRawSocketDescriptor.html

Generic implementation for types that already implement FromRawFd.

```rust
impl<T: FromRawFd> FromRawSocketDescriptor for T
```

--------------------------------

### Create FileDescriptor from IntoRawFileDescriptor

Source: https://docs.rs/filedescriptor/0.8.3/src/filedescriptor/lib.rs.html

The `new` function for FileDescriptor creates a new instance by consuming an object convertible to a RawFileDescriptor via the IntoRawFileDescriptor trait.

```rust
pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {

```
Tokens:
Raw