=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);
$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.
=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
fdopen
fclose
close
close
close
close
closefd
fread
read
read
sysread
read
readfd
fwrite
write
write
syswrite
write
writefd
pipe
pipe
pipefd
pipe
,
open
creat creat creatfd
dup dupfd
stat
stat
fstat fstat statfd
lstat
lstat
ftell
tell
tellfd
=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)
=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.
=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
=head2 Constants from unistd.h
STDIN_FILENO 0
STDOUT_FILENO 1
STDERR_FILENO 2
=head2 Constants from limits.h
PIPE_BUF
STREAM_MAX == _POSIX_STREAM_MAX
Minimum nr of streams supported by POSIX compliant
systems
MAX_INPUT Size of the type-ahead buffer (terminal)
SSIZE_MAX Max bytes taken in a single
read
or
write
system
call
=head2 Constants from stdio.h
There is
no
C<POSIX::1003::Stdio> (yet), but these
values
may
also be useful in non-buffered IO.
BUFSIZ Common IO buffer size
EOF End of file
=head1 SEE ALSO
This module is part of POSIX-1003 distribution version 0.02,
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.