<?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 xml:lang="en" id="GUID-1F809632-82B0-5B4C-92DB-9C4D1316AF03"><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> Symbian platform does not support the use of <codeph>-c</codeph> or <codeph>-l</codeph> option. </p> </conbody></concept>