read

Overview ¶

Package read implements the read builtin command.

read — read a line from standard input and assign to shell variables

Usage: read [-r] [-p PROMPT] [-d DELIM] [-n NCHARS] [-N NBYTES] [-t TIMEOUT] [NAME...]

Read one record from standard input (terminated by newline by default, or by DELIM with -d), apply POSIX field-splitting based on IFS, and assign each field to a shell variable named by NAME. With no NAME the whole line is assigned to REPLY. EOF returns exit code 1; a positive -t TIMEOUT that fires returns 142 with any partially-read data still assigned (matching bash's 128 + SIGALRM convention).

Flags:

-r          Raw mode. Disable backslash-escape interpretation:
            backslashes are kept verbatim, no line continuation.
-p PROMPT   Print PROMPT to stderr before reading. Suppressed unless
            stdin is a terminal (matches bash).
-d DELIM    Use the first byte of DELIM as the line terminator
            instead of newline. An empty DELIM means NUL.
-n NCHARS   Return after reading at most NCHARS characters (max
            1 MiB). Counts UTF-8 code points; partial multi-byte
            sequences are preserved as-is.
-N NBYTES   Return after reading exactly NBYTES bytes (max 1 MiB),
            ignoring the delimiter. Last-set wins between -n and -N.
-t TIMEOUT  Time out after TIMEOUT seconds (decimal allowed).
            -t 0 / -t "" / -t . / -t + is a non-consuming poll:
            exit 0 if input is available, 1 otherwise. Ignored for
            regular-file stdin (bash's documented behaviour).
-h, --help  Print usage and exit.

Field splitting:

Whitespace IFS chars (space, tab, newline) coalesce into a single
separator; non-whitespace IFS chars do not coalesce. With more
NAMEs than fields, missing names are assigned "". With more fields
than NAMEs, the last NAME absorbs the remainder verbatim.

Backslash escapes (non-raw mode):

\<newline>       Line continuation — both bytes dropped.
\<X>             Literal X (escape suppresses delim and NUL on X).
\<NUL>           Both bytes dropped (NULs are always stripped).

Exit codes:

0  Read completed (or -t 0 found input ready).
1  EOF before any byte / -t 0 with no input available / invalid
   identifier / value-too-large.
2  Variable access not available (find -exec / -execdir grandchild).
142  Positive -t TIMEOUT expired (128 + SIGALRM).

Unsupported flags (vs. bash): -a (array), -s (silent), -u (read from FD), -e (readline), -i (initial text). These are not implemented because the underlying shell features (arrays, terminal-mode manipulation, FD redirection beyond pipe/file, line editor) are outside rshell's scope.