Struct close_fds::CloseFdsBuilder

pub struct CloseFdsBuilder<'a> { /* fields omitted */ }

A “builder” for either closing all open file descriptors or setting them as close-on-exec.

Implementations

impl<'a> CloseFdsBuilder<'a>

pub fn new() -> Self

Create a new builder.

pub fn keep_fds(&mut self, keep_fds: &'a [c_int]) -> &mut Self

Leave the file descriptors listed in keep_fds alone; i.e. do not close them or set the close-on-exec flag on them.

Calling this method multiple times will replace the list of file descriptors to be left alone, not extend it. Additionally, it’s not recommended to call this method multiple times, since it pre-scans the list to collect information for later use.

Efficiency

It is highly recommended to sort the keep_fds slice first (see also Self::keep_fds_sorted(). This will give you significant performance improvements (especially on Linux 5.9+ and FreeBSD 12.2+).

close_fds can’t just copy the slice and sort it for you because allocating memory is not async-signal-safe (see “Async-signal-safety”).

pub unsafe fn keep_fds_sorted(&mut self, keep_fds: &'a [c_int]) -> &mut Self

Identical to Self::keep_fds(), but assumes that the given list of file descriptors is sorted.

Safety

keep_fds must be sorted in ascending order.

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

Set whether Self::cloexecfrom() needs to behave reliably in multithreaded programs (default is false).

See FdIterBuilder::threadsafe() for more information.

Note that this only applies when using Self::cloexecfrom(). Self::closefrom() is unsafe in the presence of threads anyway, so it is not required to honor this.

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

Set whether this crate is allowed to look at special files for speedups when closing the specified file descriptors (default is true).

See FdIterBuilder::allow_filesystem() for more information.

pub fn cloexecfrom(&self, minfd: c_int)

Identical to Self::closefrom(), but sets the FD_CLOEXEC flag on the file descriptors instead of closing them.

On some platforms (most notably, some of the BSDs), this is significantly less efficient than Self::closefrom(), and use of that function should be preferred when possible.

pub unsafe fn closefrom(&self, minfd: c_int)

Close all of the file descriptors starting at minfd and not excluded by Self::keep_fds().

Safety

This function is NOT safe to use if other threads are interacting with files, networking, or anything else that could possibly involve file descriptors in any way, shape, or form. (Note: On some systems, file descriptor use may be more common than you think! For example, on Linux with some versions of musl libc, std::fs::canonicalize() will open a file descriptor to the given path.)

In addition, some objects, such as std::fs::File, may open file descriptors and then assume that they will remain open. This function, by closing those file descriptors, violates those assumptions.

This function is safe to use if it can be verified that these are not concerns. For example, it should be safe at startup or just before an exec(). At all other times, exercise extreme caution when using this function, as it may lead to race conditions and/or security issues.

(Note: The above warnings, by definition, make it unsafe to call this function concurrently from multiple threads. As a result, this function may perform other non-thread-safe operations.)

Trait Implementations

impl<'a> Clone for CloseFdsBuilder<'a>

fn clone(&self) -> CloseFdsBuilder<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for CloseFdsBuilder<'a>

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

Formats the value using the given formatter.

impl<'a> Default for CloseFdsBuilder<'a>

fn default() -> Self

Returns the “default value” for a type.