=head1 NAME
POSIX::1003::FdIO - POSIX handling file descriptors
=head1 INHERITANCE
POSIX::1003::FdIO
is a POSIX::1003
=head1 SYNOPSIS
$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 $!;
=head1 DESCRIPTION
Most people believe that the C<sys*> commands in Perl-Core are not
capable of doing unbuffered IO. For those people, we have this module.
Whether C<sysread()> or L<readfd()|POSIX::1003::FdIO/"Standard POSIX"> is meassurable faster cannot be
answered.
=head2 Exporter
=head1 FUNCTIONS
=head2 Overview
Perl defaults to use file-handles avoiding file descriptors. For
that reason, the C<fread> of POSIX is the C<read> of Perl; that's
confusing. The POSIX-in-Core implementation makes you write
C<CORE::read()> and C<POSIX::read()> explicitly. However,
C<POSIX::read()> is the same as C<CORE::sysread()>!
For all people who do not trust the C<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
=head2 Standard POSIX
=over 4
=item B<closefd>(FD)
Always check the return code: C<undef> on error, cause in C<$!>.
closefd $fd or die $!;
There is no C<sysclose()> in core, because C<sysopen()> does unbuffered
IO via its perl-style file-handle: when you open with C<CORE::sysopen()>,
you must close with C<CORE::close()>.
=item B<creatfd>(FILENAME, MODE)
Implemented via L<openfd()|POSIX::1003::FdIO/"Standard POSIX">, which is true by definition of POSIX.
=item B<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.
=item B<dupfd>(FD)
Copy the file-descriptor FD into the lowest-numbered unused descriptor.
The new fd is returned, undef on failure.
=item B<openfd>(FILENAME, FLAGS, MODE)
Returned is an integer file descriptor (FD). FLAGS are composed
from the C<O_*> constants defined by Fcntl (import tag C<:mode>)
The MODE combines C<S_I*> constants from that same module.
=item B<pipefd>()
Returns the reader and writer file descriptors.
my ($r, $w) = pipefd;
writefd($w, "hello", 5 );
readfd($r, $buf, 5 );
=item B<readfd>(FD, SCALAR, [LENGTH])
Read the maximum of LENGTH bytes from FD into the SCALAR. Returned is
the actual number of bytes read.
=item B<seekfd>(FD, OFFSET, WHENCE)
The WHENCE is a C<SEEK_*> constant from Fcntl
=item B<statfd>(FD)
Request file administration information about an open file. It returns
the same list of values as C<stat> on filenames.
=item B<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 C<-1>
is returned.
=back
=head2 Additional
Zillions of Perl programs reimplement these functions. Let's simplify
code.
=over 4
=item B<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";
=item B<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 C<tell()> on
filenames.
=item B<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 C<$!>)
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";
=back
=head1 CONSTANTS
The following constants are exported, shown here with the values
discovered during installation of this module:
=for comment
#TABLE_FDIO_START
The constant names for this math module are inserted here during
installation.
=for comment
#TABLE_FDIO_END
=head1 SEE ALSO
This module is part of POSIX-1003 distribution version 0.07,
built on December 28, 2011. Website: F<http://perl.overmeer.net>. The code is based on L<POSIX>, which
is released with Perl itself.
=head1 COPYRIGHTS
Copyrights of the perl code and the related documentation by
2011 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.