SYNOPSIS
       read [-r] var...

DESCRIPTION
       The read utility shall read a single line from standard input.

       By  default, unless the -r option is specified, backslash ( '\' ) shall
       act as an escape character, as described  in  Escape  Character  (Back-
       slash)  . If standard input is a terminal device and the invoking shell
       is interactive, read shall prompt for a continuation line when:

        * The shell reads an input line ending with a backslash, unless the -r
          option is specified.

        * A here-document is not terminated after a <newline> is entered.

       The  line  shall be split into fields as in the shell (see Field Split-
       ting ); 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 var operands specified than there are fields, the leftover fields
       and  their intervening separators shall be assigned to the last var. If
       there are fewer fields than vars, the remaining vars shall  be  set  to
       empty strings.

       The setting of variables specified by the var operands shall affect the
       current shell execution environment; see Shell Execution Environment  .
       If  it  is  called in a subshell or separate utility execution environ-
       ment, 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
       IEEE Std 1003.1-2001, 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
              that are unset or null. (See  the  Base  Definitions  volume  of
              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari-
              ables 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 is read
              and the -r option was not specified, or if  a  here-document  is
              not terminated after a <newline> is entered.


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.


              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 sepa-
       rated off into its own utility to take advantage of the richer descrip-
       tion    of    functionality    introduced    by    this    volume    of
       IEEE Std 1003.1-2001.

       Since read affects the current shell execution environment, it is  gen-
       erally  provided as a shell regular built-in. If it is called in a sub-
       shell 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 call-
       er.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Shell Command Language

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .