read(1)

NAME
readread - read line of input into variables
 -

  Synopsis

read [OPTIONS] [VARIABLES...]

  Description
read reads from standard input and stores the result in one or more shell variables. By default, one line (terminated by a newline) is read into each variable. Alternatively, a null character or a maximum number of characters can be used to terminate the input. Unlike other shells, there is no default variable (such as REPLY) for storing the result.

The following options are available:

•   -c CMD or --command=CMD sets the initial string in the interactive mode command buffer to CMD.

•   -g or --global makes the variables global.

•   -i or --silent makes the characters typed obfuscated. This is useful for reading things like passwords or other sensitive information. Note that in bash the short flag is -s. We can't use that due to the existing use as an alias for --shell.

•   -l or --local makes the variables local.

•   -n NCHARS or --nchars=NCHARS makes read return after reading NCHARS characters or the end of the line, whichever comes first.

•   -p PROMPT_CMD or --prompt=PROMPT_CMD uses the output of the shell command PROMPT_CMD as the prompt for the interactive mode. The default prompt command is set_color green; echo read; set_color normal; echo '> '.

•   -P PROMPT_STR or --prompt-str=PROMPT_STR uses the string as the prompt for the interactive mode. It is equivalent to echo PROMPT_STR and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the echo command.

•   -R RIGHT_PROMPT_CMD or --right-prompt=RIGHT_PROMPT_CMD uses the output of the shell command RIGHT_PROMPT_CMD as the right prompt for the interactive mode. There is no default right prompt command.

•   -s or --shell enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.

•   -u or --unexport prevents the variables from being exported to child processes (default behaviour).

•   -U or --universal causes the specified shell variable to be made universal.

•   -x or --export exports the variables to child processes.

•   -a or --array stores the result as an array in a single variable.

•   -z or --null marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.

read reads a single line of input from stdin, breaks it into tokens based on the IFS shell variable, and then assigns one token to each variable specified in VARIABLES. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if IFS is set to the empty string, each character of the input is considered a separate token.

If -a or --array is provided, only one variable name is allowed and the tokens are stored as an array in this variable.

See the documentation for set for more details on the scoping rules for variables.

When read reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1. Otherwise, it is set to 0.

In order to protect the shell from consuming too many system resources, read will only consume a maximum of 10 MiB (1048576 bytes); if the terminator is not reached before this limit then VARIABLE is set to empty and the exit status is set to 122. This limit can be altered with the FISH_READ_BYTE_LIMIT variable. If set to 0 (zero), the limit is removed.

  Using another read history file
The read command supported the -m and --mode-name flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the fish_history variable to specify a history session ID. That will affect both the read history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available.

  Example
The following code stores the value 'hello' in the shell variable $foo.

echo hello|read foo

  This is a neat way to handle command output by-line:
printf '%s\n' line1 line2 line3 line4 | while read -l foo
                  echo 'This is another line: $foo'
              end