Module redir

yash_semantics

Module redir 

Source
Expand description

Redirection semantics.

§Effect of redirections

A redirection modifies its target file descriptor on the basis of its body.

If the body is Normal, the operand word is expanded first. Then, the operator defines the next behavior:

  • FileIn: Opens a file for reading, regarding the expanded field as a pathname.
  • FileInOut: Likewise, opens a file for reading and writing.
  • FileOut, FileClobber: Likewise, opens a file for writing and clears the file content. Creates an empty regular file if the file does not exist.
  • FileAppend: Likewise, opens a file for appending. Creates an empty regular file if the file does not exist.
  • FdIn: Copies a file descriptor, regarding the expanded field as a non-negative decimal integer denoting a readable file descriptor to copy from. Closes the target file descriptor if the field is a single hyphen (-) instead.
  • FdOut: Likewise, copies or closes a file descriptor, but the source file descriptor must be writable instead of readable.
  • Pipe: Opens a pipe, regarding the expanded field as a non-negative decimal integer denoting a file descriptor to become the reading end of the pipe. The target file descriptor will be the writing end. (TODO: Pipe is not yet implemented.)
  • String: Opens a readable file descriptor from which you can read the expanded field followed by a newline character. (TODO: String is not yet implemented.)

If the Clobber shell option is off and a regular file exists at the target pathname, then FileOut will fail.

If the body is HereDoc, the redirection opens a readable file descriptor that yields expansion of the content. The current implementation uses an unnamed temporary file for the file descriptor, but we may change the behavior in the future.

§Performing redirections

To perform redirections, you need to wrap an Env in a RedirGuard first. Then, you call RedirGuard::perform_redir to affect the target file descriptor. When you drop the RedirGuard, it undoes the effect to the file descriptor. See the documentation for RedirGuard for details.

§The CLOEXEC flag

The shell may open file descriptors to accomplish its tasks. For example, the dot built-in opens an FD to read a script file. Such FDs should be invisible to the user, so the shell should set the CLOEXEC flag on the FDs.

When the user tries to redirect an FD with the CLOEXEC flag, it fails with a ReservedFd error to protect the FD from being overwritten.

Note that POSIX requires FDs between 0 and 9 (inclusive) to be available for the user. The shell should move an FD to 10 or above before setting its CLOEXEC flag. Also note that the above described behavior about the CLOEXEC flag is specific to this implementation.

Structs§

Error
Explanation of a redirection error.
RedirGuard
Env wrapper for performing redirections.

Enums§

ErrorCause
Types of errors that may occur in the redirection.