Crate clircle

The clircle crate helps you detect IO circles in your CLI applications.

Imagine you want to read data from a couple of files and output something according to the contents of these files. If the user redirects the output of your program to one of the input files, you might end up in an infinite circle of reading and writing.

The crate provides the struct Identifier which is a platform dependent type alias, so that you can use it on all platforms and do not need to introduce any conditional compilation yourself. Identifier implements the Clircle trait, which is where you should look for the public functionality.

The Clircle trait is implemented on both of these structs and requires TryFrom for the clircle::Stdio enum and for File, so that all possible inputs can be represented as an Identifier. Additionally, there are unsafe methods for each specific implementation, but they are not recommended to use. Finally, Clircle is a subtrait of Eq, which allows checking if two Identifiers point to the same file, even if they don’t conflict. If you only need this last feature, you should use same-file instead of this crate.

Examples

To check if two Identifiers conflict, use Clircle::surely_conflicts_with:

let stdin = Identifier::stdin()?;
let stdout = Identifier::stdout()?;

if stdin.surely_conflicts_with(&stdout) {
    eprintln!("stdin and stdout are conflicting!");
}

On Linux, the above snippet could be used to detect cat < x > x, while allowing just cat, although stdin and stdout are pointing to the same pty in both cases. On Windows, this code will not print anything, because the same operation is safe there.

Re-exports

• pub use clircle_unix::libc;

Structs

• UnixIdentifier
  Implementation of Clircle for Unix.

Enums

• Stdio
  The three stdio streams.

Traits

• Clircle
  The Clircle trait describes the public interface of the crate. It contains all the platform-independent functionality. Additionally, an implementation of Eq is required, that gives a simple way to check for conflicts, if using the more elaborate surely_conflicts_with method is not wanted. This trait is implemented for the structs UnixIdentifier and WindowsIdentifier.

Functions

• output_among_inputs
  Finds a common Identifier in the two given slices.
• stdout_among_inputs
  Checks if Stdio::Stdout is in the given slice.

Type Definitions

• Identifier
  Identifies a file. The type is aliased according to the target platform.