<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-1F809632-82B0-5B4C-92DB-9C4D1316AF03" xml:lang="en"><title>read</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><userinput>read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim
] [ -u n ] [ name[?prompt] ] [ name ... ]</userinput> </p>
<p>Read one line and break it into fields using the characters in <codeph>$IFS</codeph> as
separators, except as noted below. The first field is assigned to the first <codeph>name</codeph>,
the second field to the second <codeph>name</codeph>, and so on, with leftover
fields assigned to the last <codeph>name</codeph>. If <codeph>name</codeph> is
omitted then REPLY is used for scalars and reply for arrays. </p>
<table id="GUID-B061F101-FEDC-535A-8293-79ADF690695D">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>-r</codeph>  </p> </entry>
<entry><p>Raw mode: a <codeph>\</codeph> at the end of a line does not signify
line continuation and backslashes in the line don't quote the following character
and are not removed. </p> </entry>
</row>
<row>
<entry><p> <codeph>-s</codeph>  </p> </entry>
<entry><p>Don't echo back characters if reading from the terminal. Currently
does not work with the <codeph>-q</codeph> option. </p> </entry>
</row>
<row>
<entry><p> <codeph>-q</codeph>  </p> </entry>
<entry><p>Read only one character from the terminal and set <codeph>name</codeph> to <codeph>y</codeph> if
this character was <codeph>y</codeph> or <codeph>Y</codeph> and to <codeph>n</codeph> otherwise.
With this flag set the return value is zero only if the character was <codeph>y</codeph> or <codeph>Y</codeph>.
Note that this always reads from the terminal, even if used with the<codeph> -p </codeph> or <codeph>-u</codeph> or <codeph>-z </codeph> flags
or with redirected input. This option may also be used within <codeph>zle</codeph> widgets. </p> </entry>
</row>
<row>
<entry><p> <codeph>-k[num]</codeph>  </p> </entry>
<entry><p>Read only one (or <codeph>num</codeph>) characters. All are assigned
to the first <codeph>name</codeph>, without word splitting. This flag is ignored
when <codeph>-q </codeph> is present. Input is read from the terminal unless
one of <codeph>-u</codeph> or <codeph>-p</codeph> is present. This option
may also be used within <codeph>zle</codeph> widgets. </p> </entry>
</row>
<row>
<entry><p> <codeph>-z</codeph>  </p> </entry>
<entry><p>Read one entry from the editor buffer stack and assign it to the
first <codeph>name</codeph>, without word splitting. Text is pushed onto the
stack with <codeph>print -z</codeph> or with <codeph>push-line</codeph> from
the line editor. This flag is ignored when the <codeph>-k</codeph> or <codeph>-q</codeph> flags
are present. </p> </entry>
</row>
<row>
<entry><p> <codeph>-A</codeph>  </p> </entry>
<entry><p>The first <codeph>name</codeph> is taken as the <codeph>name</codeph> of
an array and all words are assigned to it. </p> </entry>
</row>
<row>
<entry><p> <codeph>-n</codeph>  </p> </entry>
<entry><p>Together with <codeph>-c</codeph>, the number of the word the cursor
is on is read. With <codeph>-l</codeph>, the index of the character the cursor
is on is read. Note that the command <codeph>name</codeph> is word number
1, not word 0, and that when the cursor is at the end of the line, its character
index is the length of the line plus one. </p> </entry>
</row>
<row>
<entry><p> <codeph>-u n</codeph>  </p> </entry>
<entry><p>Input is read from file descriptor <codeph>n</codeph>. </p> </entry>
</row>
<row>
<entry><p> <codeph>-d delim </codeph>  </p> </entry>
<entry><p>Input is terminated by the first character of <codeph>delim</codeph> instead
of by newline. </p> </entry>
</row>
<row>
<entry><p> <codeph>-t [ num ] </codeph>  </p> </entry>
<entry><p>Test if input is available before attempting to read. If <codeph>num</codeph> is
present, it must begin with a digit and will be evaluated to give a number
of seconds, which may be a floating point number; in this case the read times
out if input is not available within this time. If <codeph>num</codeph> is
not present, it is taken to be zero, so that read returns immediately if no
input is available. If no input is available, return status 1 and do not set
any variables. </p> <p>This option is not available when reading from the
editor buffer with<codeph> -z</codeph>, when called from within completion
with <codeph>-c</codeph> or <codeph>-l</codeph>, with <codeph>-q</codeph> which
clears the input queue before reading, or within <codeph>zle</codeph> where
other mechanisms should be used to test for input. </p> <p>Note: <codeph>read</codeph> does
not attempt to alter the input processing mode. The default mode is canonical
input, in which an entire line is read at a time, so usually <codeph>read
-t</codeph> will not read anything until an entire line has been typed. However,
when reading from the terminal with <codeph>-k</codeph> input is processed
one key at a time; in this case, only availability of the first character
is tested, for example <codeph>read -t -k                 2</codeph> can still
block on the second character. Use two instances of <codeph>read -t -k</codeph> if
this is not what is wanted. </p> </entry>
</row>
<row>
<entry><p> <codeph>?</codeph>  </p> </entry>
<entry><p>If the first argument contains a <codeph>?</codeph>, the remainder
of this word is used as a prompt on standard error when the shell is interactive. </p> </entry>
</row>
</tbody>
</tgroup>
</table>
<p>The value (exit status) of <codeph>read</codeph> is 1 when an end-of-file
is encountered, or as described for <codeph>-q</codeph>. Otherwise the value
is 0. </p>
<p>The behavior of some combinations of the <codeph>-k</codeph>, <codeph>-p</codeph>, <codeph>-q</codeph>, <codeph>-u</codeph> and <codeph>-z</codeph> flags is undefined. Presently <codeph>-q</codeph> cancels all the others, <codeph>-p</codeph> cancels <codeph>-u</codeph>, <codeph>-k</codeph> cancels <codeph>-z</codeph>, and otherwise <codeph>-z</codeph> cancels both <codeph>-p</codeph> and <codeph>-u</codeph>. </p>
<p> <b>Note:</b> The Symbian platform does not support the use
of <codeph>-c</codeph> or <codeph>-l</codeph> option. </p>
</conbody></concept>