PIOMAXLNSIZE

sip

    $nlines = sip($filename, @lines);
    $nlines = sip($filename, @lines, 1);

This function allows you to read a text file into memory in chunks, the lines of which are placed into the passed array reference. The chunks are read in at up to PIOMAXFSIZE in size at a time. File locking is used and autochomping is also supported.

This returns the number of lines extracted or boolean false if any errors occurred, such as lines exceeding PIOMAXLNSIZE or other I/O errors. If there were no errors but also no content it will return 0 but true, which will satisfy boolean tests.

The passed array is always purged prior to execution. This can potentially help differentiate types of errors:

    $nlines = sip($filename, @lines);

    warn "successfully extracted lines" 
        if $nlines and scalar @lines;
    warn "no errors, but no lines" 
        if $nlines and ! scalar @lines;
    warn "line length exceeded on some lines" 
        if !$nlines and scalar @lines;
    warn "I/O errors or all lines exceeded line length" 
        if !$nlines and ! scalar @lines;

Typically, if all one cares about is extracting good lines and discarding bad ones all you need is:

    warn "good to go" if scalar @lines or $nlines;
 
    # or, more likely:
    if (@lines) {
        # process input...
    }

NOTE: sip does try to check the file stat with every call. This allows us to automatically flush buffers and reopen files in the event that the file you're sipping from was truncated, deleted, or overwritten.

The third argument is a boolean option which controls whether lines are automatically chomped or not. It defaults to not.

nlsip

    $nlines = nlsip($filename, @lines);
    $nlines = nlsip($filename, @lines, 1);

A very thin wrapper for sip that disables file locking.

tailf

    $nlines = tailf($filename, @lines);
    $nlines = tailf($filename, @lines, 1);
    $nlines = tailf($filename, @lines, 1, -100);

The only difference between this function and sip is that tailf opens the file and immediately seeks to the end. If an optional fourth argument is passed it will seek backwards to extract and return that number of lines (if possible). Depending on the number passed one must be prepared for enough memory to be allocated to store PIOMAXLNSIZE * that number. If no number is specified it is assumed to be -10. Specifying this argument on a file already opened by sip or tailf will have no effect.

Return values are identical to sip.

nltailf

    $nlines = nltailf($filename, @lines);
    $nlines = nltailf($filename, @lines, -100);
    $nlines = nltailf($filename, @lines, -100, 1);

A very thin wrapper for tailf that disables file locking.

slurp

  $nlines = slurp($filename, @lines);
  $nlines = slurp($filename, @lines, 1);

This function is essentially another wrapper for sip, but with some different behavior. While sip was written from the expectation that the developer would be either working on chunks from a very large file or a file that may grow while being accessed. slurp, on the other hand, expects to work exclusively on small files that can safely fit into memory. It also sees no need to cache file handles since all operations will subsequently be done in memory.

Files with slurp are explicitly closed after the read. All the normal safeguards apply: PIOMAXFSIZE is the largest amount of data that will be read into memory, and all lines must be within PIOMAXLNSIZE.

The third argument is a boolean option which controls whether lines are automatically chomped or not. It defaults to not.

nlslurp

  $nlines = nlslurp($filename, @lines);
  $nlines = nlslurp($filename, @lines, 1);

A very thin wrapper for slurp that disables file locking.

piolClose

  $rv = piolClose($filename);

This closes all file handles and deletes any existing buffers. Works indiscriminatley and returns the exit value of pclose.