Struct close_fds::FdIterBuilder

pub struct FdIterBuilder { /* fields omitted */ }

A “builder” to construct an FdIter with custom parameters.

Warnings

TL;DR: Don’t use FdIter/FdIterBuilder in multithreaded programs unless you know what you’re doing, and avoid opening/closing file descriptors while consuming an FdIter.

1. File descriptors that are opened during iteration may or may not be included in the results (exact behavior is platform-specific and depends on several factors).

2. IMPORTANT: On some platforms, if other threads open file descriptors at very specific times during a call to FdIter::next(), that may result in other file descriptors being skipped. Use with caution. (If this is a problem for you, set .threadsafe(true), which avoids this issue).

3. Closing file descriptors during iteration (in the same thread or in another thread) will not affect the iterator’s ability to list other open file descriptors (if it does, that is a bug). However, in most cases you should use CloseFdsBuilder to do this.

4. Some of the file descriptors yielded by this iterator may be in active use by other sections of code. Be very careful about which operations you perform on them.

   If your program is multi-threaded, this is especially true, since a file descriptor returned by this iterator may have been closed by the time your code tries to do something with it.

Implementations

impl FdIterBuilder

pub fn new() -> Self

Create a new builder.

minfd specifies the number of the file descriptor at which iteration will begin.

pub fn possible(&mut self, possible: bool) -> &mut Self

Set whether the returned FdIter is allowed to yield invalid file descriptors for efficiency (default is false).

If this flag is set, the caller is responsible for checking if the returned file descriptors are valid.

Proper usage

You should only use this flag if you immediately perform an operation on each file descriptor that implicitly checks if the file descriptor is valid.

pub fn threadsafe(&mut self, threadsafe: bool) -> &mut Self

Set whether the returned FdIter needs to behave reliably in multithreaded programs (default is false).

If other threads open file descriptors at specific times, an FdIter may skip over other file descriptors. Setting .threadsafe(true) prevents this, but may come at the cost of significantly increased performance on some platforms (because the code which may behave strangely in the presence of threads provides a potential performance improvement).

Currently, setting this flag will only affect performance on 1) OpenBSD and 2) FreeBSD without an fdescfs mounted on /dev/fd.

pub fn allow_filesystem(&mut self, fs: bool) -> &mut Self

Set whether returned FdIter is allowed to look at special files for speedups (default is true).

On some systems, /dev/fd and/or /proc/self/fd provide an accurate view of the file descriptors that the current process has open; if this flag is set to true then those may be examined as an optimization.

It may be desirable to set this to false e.g. if chroot()ing into an environment where untrusted code may be able to replace /proc or /dev. However, on some platforms (such as Linux<5.9 and macOS) setting this to false may significantly decrease performance.

pub fn iter_from(&self, minfd: c_int) -> FdIter

Create an FdIter that iterates over the open file descriptors starting at minfd.

Trait Implementations

impl Clone for FdIterBuilder

fn clone(&self) -> FdIterBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FdIterBuilder

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

Formats the value using the given formatter.

impl Default for FdIterBuilder

fn default() -> Self

Returns the “default value” for a type.