/ 
POSIX-1003-0.99_01
River stage one • 2 direct dependents • 2 total dependents
/ POSIX::1003::FdIO

NAME

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

SYNOPSIS

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 $!;

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. But there is more in file-descriptor space, missing from Core.

The question whether sysread() or readfd() is meassurable faster cannot be answered.

The fcntl() command has its separate module POSIX::1003::Fcntl. Locking functions are locate there as well, because they are often implemented via fcntl.

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. 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 CORE::read() and POSIX::read() explicitly. However, POSIX::read() is the same as CORE::sysread()!

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

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.

fdopen($fd, $mode)

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.

openfd($filename, $flags, $mode)

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 :stat).

pipefd()

Returns the reader and writer file descriptors. See also POSIX::1003::Fcntl::setfd_pipe_size()

example:

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. 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

seekfd($fd, $offset, $whence)

The $whence is a SEEK_* constant.

statfd($fd)

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

truncfd( $fd, [$length] )

[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 ftruncate.

writefd( $fd, $bytes, [$length] )

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.

Additional

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

rewindfd($fd)

Seek to the beginning of the file.

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.

CONSTANTS

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().

SEE ALSO

This module is part of POSIX-1003 distribution version 0.99_01, built on January 31, 2015. 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

Copyrights 2011-2015 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