help read shows:
-t timeout time out and return failure if a complete line of
input is not read within TIMEOUT seconds. The value of the
TMOUT variable is the default timeout. TIMEOUT may be a
fractional number. If TIMEOUT is 0, read returns
immediately, without trying to read any data, returning
success only if input is available on the specified
file descriptor. The exit status is greater than 128
if the timeout is exceeded
The full documentation says:
-t timeout
Cause read to time out and return failure if a complete line of
input (or a specified number of characters) is not read within
timeout seconds. timeout may be a decimal number with a fractional
portion following the decimal point. This option is only effective if
read is reading input from a terminal, pipe, or other special file;
it has no effect when reading from regular files. If read times out,
read saves any partial input read into the specified variable name.
If timeout is 0, read returns immediately, without trying to read any
data. The exit status is 0 if input is available on the specified
file descriptor, or the read will return EOF, non-zero otherwise. The
exit status is greater than 128 if the timeout is exceeded.
Given that read can operate on file descriptors and that bash supports named
descriptors, I think the sentence about -t having no effect on regular files
should be included in the help output as well. It would have saved me some
time anyway. Probably the sentence about partial data being saved should be in
there as well. The -t option (and read command in general) is pretty heavily
overloaded and the small reduction in size of the help vs. actual documentation
isn't worth it. If it's going to leave out critical info I'd rather just see a
'See the full documentation for details' in the help.
In general even the full documentation is confusing about exact behavior
without -t, with -t 0, and with -t nonzero. I'm not exactly sure how I'd fix
it other than an explicit table but I think it could be better somehow.
Britton
