Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
commands:builtin:read [2011/12/23 16:15]
striker [Reading Columns] IFS must be something other than whitespace for this to work.
commands:builtin:read [2018/07/17 08:42] (current)
thebonsai [Synopsis]
Line 4: Line 4:
 ===== Synopsis ===== ===== Synopsis =====
 <​code>​ <​code>​
-read [-ers] [-u <FD>] [-t <​TIMEOUT>​] [-p <​PROMPT>​] [-a <​ARRAY>​] [-n <​NCHARS>​] [-d <​DELIM>​] [-i <​TEXT>​] [<​NAME...>​]+read [-ers] [-u <FD>] [-t <​TIMEOUT>​] [-p <​PROMPT>​] [-a <​ARRAY>​] [-n <​NCHARS>​] [-N <​NCHARS>​] [-d <​DELIM>​] [-i <​TEXT>​] [<​NAME...>​]
 </​code>​ </​code>​
  
 ===== Description ===== ===== Description =====
 The ''​read''​ builtin reads **one line** of data (text, user input, ...) from standard input or a supplied filedescriptor number into one or more variables named by ''<​NAME...>''​. The ''​read''​ builtin reads **one line** of data (text, user input, ...) from standard input or a supplied filedescriptor number into one or more variables named by ''<​NAME...>''​.
 +
 +Since Bash 4.3-alpha, ''​read''​ skips any ''​NUL''​ (ASCII code 0) characters in input.
  
 If ''<​NAME...>''​ is given, the line is word-split using [[syntax:​shellvars#​IFS|IFS]] variable, and every word is assigned to one ''<​NAME>''​. The remaining words are all assigned to the last ''<​NAME>''​ if more words than variable names are present. If ''<​NAME...>''​ is given, the line is word-split using [[syntax:​shellvars#​IFS|IFS]] variable, and every word is assigned to one ''<​NAME>''​. The remaining words are all assigned to the last ''<​NAME>''​ if more words than variable names are present.
  
 <WRAP center round info 90%> <WRAP center round info 90%>
-If no ''<​NAME>''​ is given, the whole line read (without performing word-splitting!) is assigned to the shell variable [[syntax:​shellvars#​REPLY|REPLY]]. ​Then, ''​REPLY''​ really contains ​the line as it was read, without mangeling pre- and postfix spaces and other things!+If no ''<​NAME>''​ is given, the whole line read (without performing word-splitting!) is assigned to the shell variable [[syntax:​shellvars#​REPLY|REPLY]]. ​The following code will strip leading and trailing whitespace from the input:
 <​code>​ <​code>​
 while read -r; do while read -r; do
Line 21: Line 23:
 </​code>​ </​code>​
 </​WRAP>​ </​WRAP>​
 +
 +To preserve leading and trailing whitespace in the result, set IFS to the null string:
 +
 +<​code>​
 +while IFS= read -r; do
 +  line=$REPLY
 +  ...
 +done < text.txt
 +</​code>​
 +
 +Alternately,​ you can enclose $REPLY in double quotes and avoid fiddling with IFS altogether:
 +
 +<​code>​
 +while read -r; do
 +  line="​$REPLY"​
 +  ...
 +done < text.txt
 +</​code>​
 +
 +If a timeout is given, or if the shell variable [[syntax:​shellvars#​TMOUT|TMOUT]] is set, it is counted from initially waiting for input until the completion of input (i.e. until the complete line is read). That means the timeout can occur during input, too.
 +
 +
  
 ==== Options ==== ==== Options ====
Line 28: Line 52:
 |''​-d <​DELIM>''​|recognize ''<​DELIM>''​ as data-end, rather than ''<​newline>''​| |''​-d <​DELIM>''​|recognize ''<​DELIM>''​ as data-end, rather than ''<​newline>''​|
 |''​-e''​|on interactive shells: use Bash's readline interface to read the data| |''​-e''​|on interactive shells: use Bash's readline interface to read the data|
-|''​-i <​STRING>''​|:V4: preloads the input buffer with text from ''<​STRING>'',​ only works when Readline (''​-e''​) is used|+|''​-i <​STRING>''​|preloads the input buffer with text from ''<​STRING>'',​ only works when Readline (''​-e''​) is used|
 |''​-n <​NCHARS>''​|reads ''<​NCHARS>''​ characters of input, then quits| |''​-n <​NCHARS>''​|reads ''<​NCHARS>''​ characters of input, then quits|
-|''​-N <​NCHARS>''​|:V4: reads ''<​NCHARS>''​ characters of input, //ignoring any delimiter//,​ then quits|+|''​-N <​NCHARS>''​|reads ''<​NCHARS>''​ characters of input, //ignoring any delimiter//,​ then quits|
 |''​-p <​PROMPT>''​|the prompt string ''<​PROMPT>''​ is output (without a trailing automatic newline) before the read is performed| |''​-p <​PROMPT>''​|the prompt string ''<​PROMPT>''​ is output (without a trailing automatic newline) before the read is performed|
 |''​-r''​|raw input - **disables** interpretion of **backslash escapes** and **line-continuation** in the read data| |''​-r''​|raw input - **disables** interpretion of **backslash escapes** and **line-continuation** in the read data|
 |''​-s''​|secure input - don't echo input if on a terminal (passwords!)| |''​-s''​|secure input - don't echo input if on a terminal (passwords!)|
-|''​-t <​TIMEOUT>''​|wait for data ''<​TIMEOUT>''​ seconds, then quit (exit code 1). :V4: Fractional seconds ("​5.33"​) are allowed. A value of 0 immediately returns and indicates if data is waiting in the exit code. Timeout is indicated by an exit code greater than 128. If timeout arrives before data is read completely (before end-of-line),​ the partial data is saved.|+|''​-t <​TIMEOUT>''​|wait for data ''<​TIMEOUT>''​ seconds, then quit (exit code 1). Fractional seconds ("​5.33"​) are allowed ​since Bash 4. A value of 0 immediately returns and indicates if data is waiting in the exit code. Timeout is indicated by an exit code greater than 128. If timeout arrives before data is read completely (before end-of-line),​ the partial data is saved.|
 |''​-u <​FD>''​|use the filedescriptor number ''<​FD>''​ rather than ''​stdin''​ (0)| |''​-u <​FD>''​|use the filedescriptor number ''<​FD>''​ rather than ''​stdin''​ (0)|
  
Line 58: Line 82:
 To avoid this, either **disable pathname expansion** or **quote** the array name and index: To avoid this, either **disable pathname expansion** or **quote** the array name and index:
 <​code>​ <​code>​
-read "x[1]"+read 'x[1]'
 </​code>​ </​code>​
  
Line 73: Line 97:
 |!=0   ​|end-of-file reached ​ | |!=0   ​|end-of-file reached ​ |
  
 +==== read without -r ====
 +
 +Essentially all you need to know about ''​-r''​ is to **ALWAYS** use it. The exact behavior you get without ''​-r''​ is completely useless even for weird purposes. It basically allows the escaping of input which matches something in IFS, and also escapes line continuations. It's explained pretty well in the [[http://​pubs.opengroup.org/​onlinepubs/​9699919799/​utilities/​read.html#​tag_20_109 | POSIX read]] spec.
 +
 +<​code>​
 +2012-05-23 13:​48:​31 geirha it should only remove the backslashes,​ not change \n and \t and such into newlines and tabs
 +2012-05-23 13:​49:​00 ormaaj so that's what read without -r does?
 +2012-05-23 13:​49:​16 geirha no,​ -r doesn'​t remove the backslashes
 +2012-05-23 13:​49:​34 ormaaj I thought read <<<'​str'​ was equivalent to read -r <<<​$'​str'​
 +2012-05-23 13:​49:​38 geirha #​ read x y <<<​ 'foo\ bar baz'; echo "<​$x><​$y>"​
 +2012-05-23 13:​49:​40 shbot geirha:​ <foo bar><​baz>​
 +2012-05-23 13:​50:​32 geirha no,​ read without -r is mostly pointless. Damn bourne
 +2012-05-23 13:​51:​08 ormaaj So it's mostly (entirely) used to escape spaces
 +2012-05-23 13:​51:​24 ormaaj and insert newlines
 +2012-05-23 13:​51:​47 geirha ormaaj:​ you mostly get the same effect as using \ at the prompt
 +2012-05-23 13:​52:​04 geirha echo \" ​ outputs a " ,  read x <<<​ '​\"' ​ reads a "
 +2012-05-23 13:​52:​32 ormaaj oh weird
 +2012-05-23 13:52:46 * ormaaj struggles to think of a point to that...
 +2012-05-23 13:​53:​01 geirha ormaaj:​ ask Bourne :P
 +2012-05-23 13:​53:​20 geirha (not Jason)
 +2012-05-23 13:​53:​56 ormaaj hm thanks anyway :)
 +</​code>​
  
 ===== Examples ===== ===== Examples =====
Line 183: Line 229:
 ==== Ask for a path with a default value ==== ==== Ask for a path with a default value ====
  
-__**Note:​**__ ​:V4: The ''​-i''​ option was introduced with Bash 4+__**Note:​**__ The ''​-i''​ option was introduced with Bash 4
  
 <​code>​ <​code>​
Line 214: Line 260:
 ===== See also ===== ===== See also =====
   * Internal: [[commands:​builtin:​printf | The printf builtin command]]   * Internal: [[commands:​builtin:​printf | The printf builtin command]]
- 
  
  • commands/builtin/read.1324656914.txt
  • Last modified: 2011/12/23 16:15
  • by striker