<READLN [options] $file[ /]>
... statements ...
READLN statement reads the given
$file one line at
a time, returning the line(s) in successive values of
$file is "
-" (a single dash), the standard input is read
instead. For each line read, the statements inside the
block are executed, and
$ret is looped over, much like a
SQL, the special variables
$next are set inside the
READLN loop. At the end of the
$loop is the number of iterations completed
(e.g. the number of lines returned);
$next is that number plus
SKIP if any.
BREAK statement, if encountered, will exit the loop.
Options that may be given are:
REVRead the file in reverse order, and start from the end. This is extremely useful in analyzing the latest information appended to a constantly-growing file, such as a web server log, without attempting to read the entire file (often impossible). Note that the
ENDexpressions are matched in line-read order, which means that with
ENDline will occur at or before the
STARTline in the file itself.
START=$exprStart returning lines with the first one that matches the REX expression
$expr. By default lines are returned starting with the first in the file (or last if
END=$exprStop returning lines when one matches the REX expression
$expr; it will be the last line. By default the rest of the file (until
MAXLINESreached) will be returned.
MAX=$nReturn at most
$nlines, e.g. loop at most
$ntimes. Note that this is not necessarily the number of lines actually read from the file: returned lines (and hence
MAX) are counted after the application of the
MAXLINES. If unspecified, empty or negative, no limit is imposed.
MAXLINES=$linesRead at most
$linesfrom the file. Note that this is not necessarily the number of lines returned (looped over); it is a limit to read before the
ENDexpressions are matched. E.g. if the
STARTexpression matches line 50, the
ENDexpression matches line 100, and
MAXLINESis 75, only 26 lines will be returned: lines 50 through 75.
MAXLINESis a "safety limit" in case the
ENDexpressions are not found: otherwise a huge file might be read in its entirety looking for a
STARTexpression that does not exist, before any line(s) are returned at all. If unspecified, empty or negative, no limit is imposed.
SQL, don't append lines into a list in
$ret, but replace previous value each time. Saves memory if a copious file is being read and the lines need be examined only once. Also enables functions called inside the block to return multiple values for
$retis then not a loop variable.
SQL, skip the first
$nreturned lines. Note that this is counted after
READLN returns a list of the lines read from the file
(without newlines), or the last line read if
ROW is set.
Last 100 lines of the web server log:
<READLN REV ROW MAXLINES=100 /usr/local/httpd/logs/transfer.log>
READLN statement was added in version 2.1.901200000 19980723.
$next were added in version 2.6.938650000 19990929.
Note the distinction between
MAX applies to returned lines (i.e. loop iterations),
MAXLINES applies to read lines, some of which may
not be returned (e.g. before the
Support for standard input was added in version 2.6.939250000 19991006. If the
REV attribute is applied when reading
from a non-file standard input,
READLN can consume a lot of
memory, as the entire file must be read in first. It is not
recommended to read standard input in a CGI environment, as it may
have been already read for
POST form variables.