NAME

read - read line of input into variables

SYNOPSIS

read [OPTIONS] [VARIABLE ...]

DESCRIPTION

NOTE: This page documents the fish builtin read. To see the documentation on any non-fish versions, use command man read.

read reads from standard input and stores the result in shell variables. In an alternative mode, it can also print to its own standard output, for example for use in command substitutions.

By default, read reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given.

Unlike other shells, there is no default variable (such as REPLY) for storing the result - instead, it is printed on standard output.

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.

If read sets a variable and you don't specify a scope, it will use the same rules that set - display and change shell variables does - if the variable exists, it will use it (in the lowest scope). If it doesn't, it will use an unexported function-scoped variable.

The following options, like the corresponding ones in set - display and change shell variables, control variable scope or attributes:

The following options control the interactive mode:

The following options control how much is read and how it is stored:

Without the --line option, read reads a single line of input from standard input, breaks it into tokens, 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.

If no option to determine how to split like --delimiter, --line or --tokenize is given, the variable IFS is used as a list of characters to split on. Relying on the use of IFS is deprecated and this behaviour will be removed in future versions. The default value of IFS contains space, tab and newline characters. As a special case, if IFS is set to the empty string, each character of the input is considered a separate token.

With the --line option, read reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized.

If no variable names are provided, read enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read a password from the console instead of hardcoding it in the command itself, which prevents it from showing up in fish's history:

mysql -uuser -p(read)

When running in this mode, read does not split the input in any way and text is redirected to standard output without any further processing or manipulation.

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

In order to protect the shell from consuming too many system resources, read will only consume a maximum of 100 MiB (104857600 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_limit variable. If set to 0 (zero), the limit is removed.

EXAMPLE

read has a few separate uses.

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

echo hello | read foo

The while command is a neat way to handle command output line-by-line:

printf '%s\n' line1 line2 line3 line4 | while read -l foo


                  echo "This is another line: $foo"


              end

Delimiters given via "-d" are taken as one string:

echo a==b==c | read -d == -l a b c
echo $a # a
echo $b # b
echo $c # c

--tokenize honors quotes and escaping like the shell's argument passing:

echo 'a\ b' | read -t first second
echo $first # outputs "a b", $second is empty
echo 'a"foo bar"b (command echo wurst)*" "{a,b}' | read -lt -l a b c
echo $a # outputs 'afoo barb' (without the quotes)
echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes)
echo $c # nothing

For an example on interactive use, see Querying for user input.

COPYRIGHT

2024, fish-shell developers