# read

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           read — read from standard input into shell variables
    


## SYNOPSIS



           read **[** -r**]**_var_...
    


## DESCRIPTION



           The _read_ utility shall read a single logical line from standard
           input into one or more shell variables.
    
           By default, unless the **-r** option is specified, <backslash> shall
           act as an escape character. An unescaped <backslash> shall
           preserve the literal value of the following character, with the
           exception of a <newline>.  If a <newline> follows the <backslash>,
           the _read_ utility shall interpret this as line continuation. The
           <backslash> and <newline> shall be removed before splitting the
           input into fields. All other unescaped <backslash> characters
           shall be removed after splitting the input into fields.
    
           If standard input is a terminal device and the invoking shell is
           interactive, _read_ shall prompt for a continuation line when it
           reads an input line ending with a <backslash> <newline>, unless
           the **-r** option is specified.
    
           The terminating <newline> (if any) shall be removed from the input
           and the results shall be split into fields as in the shell for the
           results of parameter expansion (see _Section 2.6.5_ , _Field_
           _Splitting_); the first field shall be assigned to the first
           variable _var_ , the second field to the second variable _var_ , and so
           on. If there are fewer fields than there are _var_ operands, the
           remaining _var_ s shall be set to empty strings. If there are fewer
           _var_ s than fields, the last _var_ shall be set to a value comprising
           the following elements:
    
            *  The field that corresponds to the last _var_ in the normal
               assignment sequence described above
    
            *  The delimiter(s) that follow the field corresponding to the
               last _var_
    
            *  The remaining fields and their delimiters, with trailing _IFS_
               white space ignored
    
           The setting of variables specified by the _var_ operands shall
           affect the current shell execution environment; see _Section 2.12_ ,
           _Shell Execution Environment_.  If it is called in a subshell or
           separate utility execution environment, such as one of the
           following:
    
               (read foo)
               nohup read ...
               find . -exec read ... \;
    
           it shall not affect the shell variables in the caller's
           environment.
    


## OPTIONS



           The _read_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following option is supported:
    
           **-r** Do not treat a <backslash> character in any special way.
                     Consider each <backslash> to be part of the input line.
    


## OPERANDS



           The following operand shall be supported:
    
           _var_       The name of an existing or nonexisting shell variable.
    


## STDIN



           The standard input shall be a text file.
    


## INPUT FILES



           None.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _read_ :
    
           _IFS_       Determine the internal field separators used to delimit
                     fields; see _Section 2.5.3_ , _Shell Variables_.
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte as opposed to multi-byte characters in
                     arguments).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    
           _PS2_       Provide the prompt string that an interactive shell
                     shall write to standard error when a line ending with a
                     <backslash> <newline> is read and the **-r** option was not
                     specified.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           Not used.
    


## STDERR



           The standard error shall be used for diagnostic messages and
           prompts for continued input.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    End-of-file was detected or an error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           The **-r** option is included to enable _read_ to subsume the purpose of
           the _line_ utility, which is not included in POSIX.1‐2008.
    


## EXAMPLES



           The following command:
    
               while read -r xx yy
               do
                   printf "%s %s\n$yy$xx"
               done < _input_file_
    
           prints a file with the first field of each line moved to the end
           of the line.
    


## RATIONALE



           The _read_ utility historically has been a shell built-in. It was
           separated off into its own utility to take advantage of the richer
           description of functionality introduced by this volume of
           POSIX.1‐2017.
    
           Since _read_ affects the current shell execution environment, it is
           generally provided as a shell regular built-in. If it is called in
           a subshell or separate utility execution environment, such as one
           of the following:
    
               (read foo)
               nohup read ...
               find . -exec read ... \;
    
           it does not affect the shell variables in the environment of the
           caller.
    
           Although the standard input is required to be a text file, and
           therefore will always end with a <newline> (unless it is an empty
           file), the processing of continuation lines when the **-r** option is
           not used can result in the input not ending with a <newline>.
           This occurs if the last line of the input file ends with a
           <backslash> <newline>.  It is for this reason that ``if any'' is
           used in ``The terminating <newline> (if any) shall be removed from
           the input'' in the description.  It is not a relaxation of the
           requirement for standard input to be a text file.
    


## FUTURE DIRECTIONS



           None.
    


* * *