<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE apiOperation PUBLIC "-//IBM//DTD DITA API Operation Reference Type//EN"
 "../dtd/apiOperation.dtd">
<apiOperation id="read">
<apiName>read</apiName>
<shortdesc>Read the specified quantity of data from a file into a variable. </shortdesc>
<apiOperationDetail>
<apiSyntax>
<apiSyntaxText>read <apiItemName>FILEHANDLE</apiItemName>, <apiItemName>SCALAR</apiItemName>, <apiItemName>LENGTH</apiItemName>, <apiItemName>OFFSET</apiItemName
>
read <apiItemName>FILEHANDLE</apiItemName>, <apiItemName>SCALAR</apiItemName>, <apiItemName>LENGTH</apiItemName></apiSyntaxText>
<apiSyntaxItem>
<apiItemName>FILEHANDLE</apiItemName>
<apiDefNote>The identifier for the file from which the data is read.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>SCALAR</apiItemName>
<apiDefNote>The name of the variable where the data is stored after reading.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>LENGTH</apiItemName>
<apiDefNote>The number of characters of data to read.</apiDefNote>
</apiSyntaxItem>
<apiSyntaxItem>
<apiItemName>OFFSET</apiItemName>
<apiDefNote>The number of characters from the start of the file prior to the
data to be read.</apiDefNote>
</apiSyntaxItem>
</apiSyntax>
<apiDesc>The <apioperation>read</apioperation> function returns the number
of characters actually read, 0 at end of file, or undef if there was an error
(in the latter case $! is also set). The <apivalue>SCALAR</apivalue> variable
will be grown or shrunk so that the last character actually read is the last
character of the scalar after the read.<p>An <apivalue>OFFSET</apivalue> may
be specified to place the read data at some place in the string other than
the beginning. A negative <apivalue>OFFSET</apivalue> specifies placement
at that many characters counting backwards from the end of the string. A positive <apivalue>OFFSET</apivalue> greater
than the length of <apivalue>SCALAR</apivalue> results in the string being
padded to the required size with "\0" bytes before the result of the read
is appended.</p></apiDesc>
</apiOperationDetail>
<apiValue id="rs">
<apiName>INPUT_RECORD_SEPARATOR</apiName>
<shortdesc>Defines what a line is.</shortdesc>
<apiValueDetail>
<apiSyntax>
<apiSyntaxText>$INPUT_RECORD_SEPARATOR
$RS
$/</apiSyntaxText>
</apiSyntax>
<apiDesc>The input record separator defines what a <q>line</q> is (newline
by default). The input record separator treats empty lines as a terminator
if set to the null string. An empty line cannot contain any spaces or tabs.
You may set it to a multi-character string to match a multi-character terminator,
or to undef to read through the end of file. <p>Setting it to "\n\n" means
something slightly different than setting to "", if the file contains consecutive
empty lines. Setting to "" will treat two or more consecutive empty lines
as a single empty line. Setting to "\n\n" will blindly assume that the next
input character belongs to the next paragraph, even if it's a newline. (Mnemonic:
/ delimits line boundaries when quoting poetry.)</p></apiDesc>
</apiValueDetail>
</apiValue>
</apiOperation>