<?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>