POSIX::1003::FdIO - POSIX handling file descriptors
POSIX::1003::FdIO is a POSIX::1003::Module
use POSIX::1003::FdIO; $fd = openfd($fn, O_RDWR); defined $fd or die $!; # $fd==0 is valid value! (STDIN) $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 $!; my $fh = fdopen($fd, 'w') or die $!;
Most people believe that the
sys* commands in Perl Core are not capable of doing unbuffered IO. For those people, we have this module. But there is more in file-descriptor space, missing from Core.
The question whether
sysread() or readfd() is meassurable faster cannot be answered.
fcntl() command has its separate module POSIX::1003::Fcntl. Locking functions are locate there as well, because they are often implemented via
Perl defaults to use file-handles, avoiding file descriptors. For that reason, the
fread of POSIX is the
read of Perl; that's confusing. But the POSIX standard is confused as well: some function names which start with an
f are actually for file-descriptors, other for file-handles!
The POSIX module, distributed with Perl, makes you write
POSIX::read() explicitly. However,
POSIX::read() is the same as
To avoid conflicts with function names in Perl core, and the confusion that the POSIX created, all exported function names provided by this module contain 'fd' in their name.
POSIX Perl-Core POSIX.pm POSIX::1003::FdIO FH fseek seek FD lseek sysseek lseek seekfd FH fopen open FD open sysopen openfd # sysopen is clumpsy FD fdopen open fdopen # IO::Handle->new_from_fd FH fclose close FD close close close closefd FH fread read FD read sysread read readfd FH fwrite print FD write syswrite write writefd FH pipe,open # buffered unless $|=0 FD pipe pipe pipefd FH stat stat FD fstat fstat statfd FN lstat lstat FH ftell tell FD tellfd # tell on fd not in POSIX FH rewind rewind FD rewindfd # rewind on fd not in POSIX FD creat creat creatfd FD dup dupfd FD fcntl fcntl (many) # see ::Fcntl FD flock flock flockfd # see ::Fcntl FD lockf lockf # see ::Fcntl FN truncate truncate FD ftruncate truncfd
Works on: FH=file handle, FD=file descriptor, FN=file name
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
Implemented via openfd(), which is true by definition of POSIX.
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.
Copy the file-descriptor FD into the lowest-numbered unused descriptor. The new fd is returned, undef on failure.
Converts a FD into an (buffered) FH. You probably want to set binmode after this. MODE can be Perl-like '<', '>', '>>', or POSIX standard 'r', 'w', 'a'. POSIX modes 'r+', 'w+', and 'a+' can probably not be supported.
Returned is an integer file descriptor (FD). Returns
undef on failure (and '0' is a valid FD!)
FLAGS are composed from the
O_* constants defined by this module (import tag
:mode) The MODE field combines
S_I* constants defined by POSIX::1003::FS (import tag
Returns the reader and writer file descriptors. See also POSIX::1003::Fcntl::setfd_pipe_size()
my ($r, $w) = pipefd; writefd($w, "hello", 5 ); readfd($r, $buf, 5 );
Read the maximum of LENGTH bytes from FD into the SCALAR. Returned is the actual number of bytes read. The value
-1 tells you there is an error, reported in
Be warned that a returned value smaller than LENGTH does not mean that the FD has nothing more to offer: the end is reached only when 0 (zero) is returned. Therefore, this reading is quite inconvenient. You may want to use POSIX::Util subroutine readfd_all
The WHENCE is a
Request file administration information about an open file. It returns the same list of values as
stat on filenames.
[0.96] Shorten the file to the LENGTH (defaults to 0). The file offset (your pointer in the file) is not changed, so you may need to seekfd() as well. Behavior is undefined when LENGTH is larger than the file size.
The POSIX name for this function is
Attempt to write the first LENGTH bytes of STRING to FD. Returned is the number of bytes actually written. You have an error only when
-1 is returned.
Zillions of Perl programs reimplement these functions. Let's simplify code.
Seek to the beginning of the file.
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.
The following constants are exported, shown here with the values discovered during installation of this module.
BUFSIZ 8192 EOF -1 MAX_INPUT 255 O_ACCMODE 3 O_APPEND 1024 O_ASYNC 8192 O_CLOEXEC 524288 O_CREAT 64 O_DIRECT 16384 O_DIRECTORY 65536 O_DSYNC 4096 O_EXCL 128 O_FSYNC 1052672 O_LARGEFILE 0 O_NDELAY 2048 O_NOATIME 262144 O_NOCTTY 256 O_NOFOLLOW 131072 O_NONBLOCK 2048 O_RDONLY 0 O_RDWR 2 O_RSYNC 1052672 O_SYNC 1052672 O_TRUNC 512 O_WRONLY 1 PIPE_BUF 4096 SEEK_CUR 1 SEEK_DATA 3 SEEK_END 2 SEEK_HOLE 4 SEEK_SET 0 SSIZE_MAX 9223372036854775807 STDERR_FILENO 2 STDIN_FILENO 0 STDOUT_FILENO 1
You can limit the import to the
SEEK_* constants by explicitly using the
:seek import tag. Use the
:mode for all
O_* constants, to be used with openfd().
This module is part of POSIX-1003 distribution version 0.98, built on December 03, 2013. Website: http://perl.overmeer.net. The code is based on POSIX, which is released with Perl itself. See also POSIX::Util for additional functionality.
Copyrights 2011-2013 on the perl code and the related documentation 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