Mark Overmeer > POSIX-1003-0.91 > POSIX::1003::FdIO

Download:
POSIX-1003-0.91.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  2
View/Report Bugs
Module Version: 0.91   Source   Latest Release: POSIX-1003-0.98

NAME ^

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

INHERITANCE ^

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

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);
  # Permission bit constants in POSIX::1003::FS

  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.

METHODS ^

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

See "METHODS" in POSIX::1003::Module

$obj->import()

See "METHODS" in POSIX::1003::Module

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
 FH fseek   seek
 FD lseek   sysseek   lseek    seekfd
 FH fopen   open
 FD open    sysopen            openfd   # sysopen is clumpsy
 FD 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 # idem
 FD creat             creat    creatfd
 FD dup                        dupfd

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.

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

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.

The number of bytes written can be less than LENGTH without an error condition: you have to call write again with the remaining bytes. This is quite inconvenient. You may want to use POSIX::Util subroutine readfd_all

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_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        4096
  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        4096
  O_SYNC         4096
  O_TRUNC        512
  O_WRONLY       1
  PIPE_BUF       4096
  SEEK_CUR       1
  SEEK_END       2
  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.91, built on January 04, 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 ^

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

syntax highlighting: