NAME

POSIX::1003::FdIO - POSIX handling file descriptors

INHERITANCE

POSIX::1003::FdIO
  is a POSIX::1003

SYNOPSIS

use POSIX::1003::FdIO;
$fd = openfd($fn, O_RDWR);
$fd = openfd($fn, O_WRONLY|O_TRUNC);
$fd = openfd($fn, O_CREAT|O_WRONLY, 0640);

my $buf;
$bytes_read    = readfd($fd, $buf, BUFSIZ);
$bytes_written = writefd($fd, $buf, 5);

$off_t = seekfd($fd, 0, SEEK_SET);  # rewind!
$fd2   = dupfd($fd);

closefd($fd) or die $!;

my ($r, $w) = pipefd();
writefd($w, "hello", 5);
readfd($r, $buf, 5);
closefd($r) && closefd($w) or die $!;

DESCRIPTION

Most people believe that the sys* commands in Perl-Core are not capable of doing unbuffered IO. For those people, we have this module. Whether sysread() or readfd() is meassurable faster cannot be answered.

Exporter

METHODS

POSIX::1003::FdIO->exampleValue(NAME)

See "METHODS" in POSIX::1003

FUNCTIONS

Overview

Perl defaults to use file-handles avoiding file descriptors. For that reason, the fread of POSIX is the read of Perl; that's confusing. The POSIX-in-Core implementation makes you write CORE::read() and POSIX::read() explicitly. However, POSIX::read() is the same as CORE::sysread()!

For all people who do not trust the sys* commands (and there are many), we provide the implementation of POSIX-in-Core with a less confusing name to avoid accidents.

POSIX   Perl-Core POSIX.pm POSIX::1003::FdIO
fseek   seek
lseek   sysseek   lseek    seekfd
fopen   open
open    sysopen            openfd  # sysopen clumpsy
fdopen                             # IO::Handle->new_from_fd
fclose  close
close   close     close    closefd
fread   read
read    sysread   read     readfd
fwrite  write
write   syswrite  write    writefd
pipe              pipe     pipefd
        pipe,open                  # buffered unless $|=0
creat             creat    creatfd
dup                        dupfd
stat    stat
fstat             fstat    statfd
lstat   lstat
ftell   tell
                           tellfd  # tell on fd not in POSIX

Standard POSIX

closefd(FD)

Always check the return code: undef on error, cause in $!. closefd $fd or die $!;

There is no sysclose() in core, because sysopen() does unbuffered IO via its perl-style file-handle: when you open with CORE::sysopen(), you must close with CORE::close().

creatfd(FILENAME, MODE)

Implemented via openfd(), which is true by definition of POSIX.

dup2fd(FD, NEWFD)

Copy file-descriptor FD to an explicit NEWFD number. When already in use, the file at NEWFD will be closed first. Returns undef on failure.

dupfd(FD)

Copy the file-descriptor FD into the lowest-numbered unused descriptor. The new fd is returned, undef on failure.

openfd(FILENAME, FLAGS, MODE)

Returned is an integer file descriptor (FD). FLAGS are composed from the O_* constants defined by Fcntl (import tag :mode) The MODE combines S_I* constants from that same module.

pipefd()

Returns the reader and writer file descriptors. my ($r, $w) = pipefd; writefd($w, "hello", 5 ); readfd($r, $buf, 5 );

readfd(FD, SCALAR, [LENGTH])

Read the maximum of LENGTH bytes from FD into the SCALAR. Returned is the actual number of bytes read.

seekfd(FD, OFFSET, WHENCE)

The WHENCE is a SEEK_* constant from Fcntl

statfd(FD)

Request file administration information about an open file. It returns the same list of values as stat on filenames.

writefd(FD, BYTES, [LENGTH])

Attempt to write the first LENGTH bytes of STRING to FD. Returned is the number of bytes actually written. The number of bytes written can be less than LENGTH without an error condition: you have to call write again with the remaining bytes. You have an error only when -1 is returned.

Additional

Zillions of Perl programs reimplement these functions. Let's simplify code.

readfd_all(FD, [SIZE, [DO_CLOSE]])

Read all remaining bytes from the FD. At most SIZE bytes are read, which defaults to SSIZE_MAX.

The maximum SIZE would be SSIZE_MAX, but POSIX.xs pre-allocs a buffer with that size, so 2^64 is too large. We will read in convenient

my $in = openfd $filename, O_RDONLY;
my $d  = readfd_all $in, undef, 1;
defined $d or die "cannot read from $filename: $!\n";

tellfd(FD)

Reports the location in the file. This call does not exist (not in POSIX, nor on other UNIXes), however is a logical counterpart of the tell() on filenames.

writefd_all(FD, BYTES, [DO_CLOSE])

Be sure that BYTES have the utf-8 flag off! We are working with bytes here, not strings. Returns false if something went wrong (error in $!) The FD will get closed when DO_CLOSE is provided and true.

example:

my $out = creatfd $outfile, 0600;
writefd_all $out, $bytes, 1
    or die "write to $outfile failed: $!\n";

CONSTANTS

The following constants are exported, shown here with the values discovered during installation of this module:

The constant names for this math module are inserted here during installation.

SEE ALSO

This module is part of POSIX-1003 distribution version 0.11, built on January 04, 2012. Website: http://perl.overmeer.net. The code is based on POSIX, which is released with Perl itself.

COPYRIGHTS

Copyrights of the perl code and the related documentation by 2011-2012 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html