4

I would love to learn more about 'read' so to enhance my shell scripting abilities.

Usually when I have a thirst for knowledge for any program, I simply type:

man [program]

Then I learn how to work a program. I've been doing it this way for the past 15 years.

But a few days ago, I stumbled onto the most useless and unexpected man page (IMO) for a program called 'read'. It's a commonly used program for reading user input and a lot of shell scripts use it.

Here's it being used in one of my shell scripts.. It simply grabs a variable and outputs it, whilst allowing it to be edited by the end user:

read -e -p "HOSTip: " -i "${HOSTip}" HOSTip

This command took a lot of trawling about the web to find how to use it in this way. The man page was zero help.

Any help would be greatly appreciated in helping me figure out why a proper manual for using read doesn't appear to exist on my machine.

John Kugelman
  • 349,597
  • 67
  • 533
  • 578
  • I dream of the day that all shell built-ins should also have a man page... Thank you. – CyanMan2019 Jan 17 '22 at 18:56
  • The problem is that the details depend on which shell you're using. The man page for all the shell builtins has cross-references to all the shell man pages. – Barmar Jan 17 '22 at 18:57
  • So should `man read` provide a manual for `read` as implemented in POSIX shell, `bash`, `zsh`, `ksh`, `dash`, `fish`, or some other shell you have installed? (All six shells I mentioned provide distinct, mutually incompatible implementations of `read`.) – chepner Jan 17 '22 at 19:12
  • Each shell could provide its own section (I don't know if `man` sections are restricted to single characters or not), and require a call like `man b read` to get the documentation for `bash` read (assuming `bash` uses section `b`). At that point, you need to know the correct section to request, so you man as well just search `man bash` for the documentation. – chepner Jan 17 '22 at 19:15

1 Answers1

3

If your shell is bash, its builtin commands don't have individual man pages. Use help to see a list of builtins and help <command> to get help on an individual one.

$ help
GNU bash, version 5.1.4(1)-release (x86_64-pc-linux-gnu)
These shell commands are defined internally.  Type `help' to see this list.
Type `help name' to find out more about the function `name'.
Use `info bash' to find out more about the shell in general.
Use `man -k' or `info' to find out more about commands not in this list.

A star (*) next to a name means that the command is disabled.

 job_spec [&]                                               history [-c] [-d offset] [n] or history -anrw [filename>
 (( expression ))                                           if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMA>
 . filename [arguments]                                     jobs [-lnprs] [jobspec ...] or jobs -x command [args]
 :                                                          kill [-s sigspec | -n signum | -sigspec] pid | jobspec >
 [ arg... ]                                                 let arg [arg ...]
 [[ expression ]]                                           local [option] name[=value] ...
 alias [-p] [name[=value] ... ]                             logout [n]
 bg [job_spec ...]                                          mapfile [-d delim] [-n count] [-O origin] [-s count] [->
 bind [-lpsvPSVX] [-m keymap] [-f filename] [-q name] [-u>  popd [-n] [+N | -N]
 break [n]                                                  printf [-v var] format [arguments]
 builtin [shell-builtin [arg ...]]                          pushd [-n] [+N | -N | dir]
 caller [expr]                                              pwd [-LP]
 case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... es>  read [-ers] [-a array] [-d delim] [-i text] [-n nchars]>
 cd [-L|[-P [-e]] [-@]] [dir]                               readarray [-d delim] [-n count] [-O origin] [-s count] >
 command [-pVv] command [arg ...]                           readonly [-aAf] [name[=value] ...] or readonly -p
 compgen [-abcdefgjksuv] [-o option] [-A action] [-G glob>  return [n]
 complete [-abcdefgjksuv] [-pr] [-DEI] [-o option] [-A ac>  select NAME [in WORDS ... ;] do COMMANDS; done
 compopt [-o|+o option] [-DEI] [name ...]                   set [-abefhkmnptuvxBCHP] [-o option-name] [--] [arg ...>
 continue [n]                                               shift [n]
 coproc [NAME] command [redirections]                       shopt [-pqsu] [-o] [optname ...]
 declare [-aAfFgiIlnrtux] [-p] [name[=value] ...]           source filename [arguments]
 dirs [-clpv] [+N] [-N]                                     suspend [-f]
 disown [-h] [-ar] [jobspec ... | pid ...]                  test [expr]
 echo [-neE] [arg ...]                                      time [-p] pipeline
 enable [-a] [-dnps] [-f filename] [name ...]               times
 eval [arg ...]                                             trap [-lp] [[arg] signal_spec ...]
 exec [-cl] [-a name] [command [argument ...]] [redirecti>  true
 exit [n]                                                   type [-afptP] name [name ...]
 export [-fn] [name[=value] ...] or export -p               typeset [-aAfFgiIlnrtux] [-p] name[=value] ...
 false                                                      ulimit [-SHabcdefiklmnpqrstuvxPT] [limit]
 fc [-e ename] [-lnr] [first] [last] or fc -s [pat=rep] [>  umask [-p] [-S] [mode]
 fg [job_spec]                                              unalias [-a] name [name ...]
 for NAME [in WORDS ... ] ; do COMMANDS; done               unset [-f] [-v] [-n] [name ...]
 for (( exp1; exp2; exp3 )); do COMMANDS; done              until COMMANDS; do COMMANDS; done
 function name { COMMANDS ; } or name () { COMMANDS ; }     variables - Names and meanings of some shell variables
 getopts optstring name [arg ...]                           wait [-fn] [-p var] [id ...]
 hash [-lr] [-p pathname] [-dt] [name ...]                  while COMMANDS; do COMMANDS; done
 help [-dms] [pattern ...]                                  { COMMANDS ; }
$ help read
read: read [-ers] [-a array] [-d delim] [-i text] [-n nchars] [-N nchars] [-p prompt] [-t timeout] [-u fd] [name ...]
    Read a line from the standard input and split it into fields.

    Reads a single line from the standard input, or from file descriptor FD
    if the -u option is supplied.  The line is split into fields as with word
    splitting, and the first word is assigned to the first NAME, the second
    word to the second NAME, and so on, with any leftover words assigned to
    the last NAME.  Only the characters found in $IFS are recognized as word
    delimiters.

    If no NAMEs are supplied, the line read is stored in the REPLY variable.

    Options:
      -a array  assign the words read to sequential indices of the array
                variable ARRAY, starting at zero
      -d delim  continue until the first character of DELIM is read, rather
                than newline
      -e        use Readline to obtain the line
      -i text   use TEXT as the initial text for Readline
      -n nchars return after reading NCHARS characters rather than waiting
                for a newline, but honor a delimiter if fewer than
                NCHARS characters are read before the delimiter
      -N nchars return only after reading exactly NCHARS characters, unless
                EOF is encountered or read times out, ignoring any
                delimiter
      -p prompt output the string PROMPT without a trailing newline before
                attempting to read
      -r        do not allow backslashes to escape any characters
      -s        do not echo input coming from a terminal
      -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
      -u fd     read from file descriptor FD instead of the standard input

    Exit Status:
    The return code is zero, unless end-of-file is encountered, read times out
    (in which case it's greater than 128), a variable assignment error occurs,
    or an invalid file descriptor is supplied as the argument to -u.

You can also find their documentation collected in man builtins or near the bottom of the bash man page under "Shell Builtin Commands".

John Kugelman
  • 349,597
  • 67
  • 533
  • 578