> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bash Read Command
The `read` command is a Bash builtin utility that reads a single line of text from standard input (`stdin`) or a specified file descriptor, splits the line into fields based on the Internal Field Separator (`IFS`), and assigns those fields to specified shell variables.
```bash theme={"dark"}
read [-ers] [-a array] [-d delim] [-i text] [-n nchars] [-N nchars] [-p prompt] [-t timeout] [-u fd] [name ...]
```
## Core Mechanics
**Field Splitting and Assignment**
When `read` processes an input string, it evaluates the `IFS` shell variable (which defaults to space, tab, and newline). It strips leading and trailing `IFS` whitespace characters, then splits the remaining string into discrete words.
These words are assigned sequentially to the variable identifiers provided in the `[name ...]` arguments:
* **Exact Match:** If the number of words equals the number of variables, each variable receives one word.
* **Overflow:** If there are more words than variables, the final variable in the sequence receives all remaining unparsed words, including their intervening `IFS` characters.
* **Underflow:** If there are fewer words than variables, the remaining variables are assigned an empty string (`""`).
**The Default Variable**
If no `name` arguments are supplied, `read` assigns the input line (excluding the terminating newline) to the default shell variable `$REPLY`. Although the input is not split into discrete fields, backslash escape processing still occurs and will mutate the string unless the `-r` flag is invoked.
## Parsing Behavior and Escape Characters
By default, `read` interprets the backslash (`\`) as an escape character. A backslash followed by a newline acts as a line continuation, instructing `read` to ignore the newline and continue reading the next line of input as part of the current string.
To disable this behavior and treat backslashes as literal characters, the `-r` (raw) option must be invoked.
```bash theme={"dark"}
# Default behavior (backslash escapes the newline)
read var1 var2
# Raw behavior (backslash is a literal character)
read -r var1 var2
```
## Flag Specifications
* **`-r` (Raw Input):** Disables backslash escape processing. This is the strictly recommended default for almost all programmatic implementations to prevent unintended data mutation.
* **`-a array` (Array Assignment):** Assigns the split words to sequential indices of an indexed array named `array`, starting at index `0`. Unsets the array before assignment.
* **`-d delim` (Delimiter):** Instructs `read` to terminate upon encountering the first character of the string `delim`, rather than the default newline (`\n`).
* **`-e` (Readline):** Uses the Readline library to obtain the line of input whenever standard input is a terminal. This allows for line editing and history traversal, and operates successfully even within non-interactive shells (such as standard executed Bash scripts).
* **`-i text` (Initial Text):** Inserts the string `text` into the Readline buffer as the initial text before reading input. This option is only evaluated if the `-e` flag is also invoked.
* **`-p prompt` (Prompt):** Outputs the string `prompt` to standard error (`stderr`) without a trailing newline before attempting to read input. The prompt is only displayed if input is coming from a terminal.
* **`-t timeout` (Timeout):** Causes `read` to time out and return a failure exit status if a complete line of input is not read within `timeout` seconds. `timeout` accepts fractional seconds.
* **`-n nchars` (Character Limit):** Returns after reading exactly `nchars` characters, rather than waiting for a delimiter. It will return earlier if a delimiter is encountered.
* **`-N nchars` (Strict Character Limit):** Returns only after reading exactly `nchars` characters, ignoring delimiters entirely (including newlines).
* **`-s` (Silent Mode):** Disables terminal echoing of characters as they are typed. This is achieved by temporarily disabling the `ECHO` flag in the terminal's `termios` settings.
* **`-u fd` (File Descriptor):** Reads input from the specified file descriptor `fd` instead of standard input (`0`).
## Exit Status
The `read` command returns an exit status of `0` upon successful execution. Success occurs when a delimiter is reached, or when the specified character limits of the `-n` or `-N` flags are fulfilled, even if no delimiter is encountered. It returns a non-zero exit status (`>0`) under the following conditions:
* End-of-file (EOF) is encountered before a delimiter or character limit is reached.
* A timeout specified by `-t` is exceeded (returns exit status `> 128`).
* An invalid file descriptor is supplied to `-u`.
* An invalid variable name is provided.
Tired of Poor Bash Skills? Fix That With Deep Grasping!
Learn More
