Filesys::POSIX::IO - Provides file I/O calls for Filesys::POSIX
Filesys::POSIX::IO is a mixin imported into the Filesys::POSIX namespace by the Filesys::POSIX module itself. This module provides the standard file I/O routines.
Filesys::POSIX::IO
$fs->open($path, $flags)
$fs->open($path, $flags, $mode)
Open a file descriptor for an inode specified by $path. This operation can be modified by usage of the following flags which can be specified together using logical OR (|). The flags as follows are exported by Filesys::POSIX::Bits:
$O_CREAT
If an inode at the specified path does not exist, attempt to create one.
When a mode is specified, the value is split into the format ($S_IFMT), permission ($S_IPERM), and protection ($S_IPROT) bitfields. If no value was specified for the format, then the default value of $S_IFREG (regular file) is substituted.
$S_IFMT
$S_IPERM
$S_IPROT
$S_IFREG
When no mode is specified whatsoever, the default values of an $S_IFREG format, and a mode of 0666 are used, modified by the current umask value.
In either case, the permissions to be used are modified with an exclusive OR operation by the current umask value.
$O_EXCL
When specified in the presence of $O_CREAT, the call will only succeed when the path lists a nonexisting inode. A "File exists" exception will be thrown if this is not the case.
$O_TRUNC
When specified, any existing file data will be truncated, and the file handle position will start at offset 0 (zero).
$O_APPEND
When specified, the file handle position will start at the offset value equal to the size of the file.
$O_RDONLY
The default flag field value. When neither $O_WRONLY nor $O_RDWR are specified, any write operations will be prohibited on the newly issued file descriptor.
$O_WRONLY
$O_RDWR
When specified, any read operations will be prohibited on the newly issued file descriptor.
When specified, both read and write operations will be allowed on the newly issued file descriptor.
The following exceptions may be thrown.
EINVAL (Invalid argument)
No flags were specified in $flags.
EEXIST (File exists)
When the $O_CREAT flag is passed, this error may occur if a file located at $path already exists.
$fs->read($fd, $buf, $len)
Perform a read on the file descriptor passed, storing at maximum the number of bytes specified in $len, into $buf. Returns the number of bytes actually read; fewer bytes may be read than requested if the expected amount of data from the current file handle position, plus the requested length, does not match the requested length, such as when the length exceeds the end of the file stream. Returns zero if no more data is available to be read.
$len
$buf
Exceptions are thrown for the following:
A read was attempted on a write-only file descriptor.
$fs->write($fd, $buf, $len)
Perform a write on the file descriptor passed, writing at maximum the number of bytes specified in $len from $buf to the open file. Returns the number of bytes actually written; fewer bytes may be written than requested if the buffer does not contain enough, or if the underlying file handle implementation was not able to write the full amount in the case of a Filesys::POSIX::IO::Handle object issued for an open Filesys::POSIX::Real::Inode object.
The following exceptions may be thrown:
A write was attempted on a read-only file descriptor.
$fs->print($fd, @args)
Works similarly to $fs->write. Each argument is concatenated using the current value of $/ (see perlvar), and passed with the amalgamated value's length to the underlying file handle's $handle->write call.
$fs->write
$/
$handle->write
Exceptions may be thrown for the following:
Issued when called on a read-only file descriptor.
$fs->printf($fd, $format, @args)
Similar to $fs->print, this call allows writes formatted by sprintf() to be made to the given file descriptor.
$fs->print
Exceptions are thrown for:
$fs->tell($fd)
Returns the byte offset of the file descriptor's file handle.
$fs->seek($fd, $pos, $whence)
Sets the byte offset of the file descriptor's file handle, relative to the current offset as modified by the value specified in $whence. $whence can be used to specify how the new position will be set relative to the current offset with the following values (in Filesys::POSIX::Bits):
$SEEK_SET
The new offset of the file handle will be set to 0 + $pos bytes, or, relative to the beginning of the file. This sets the file handle to an absolute offset.
0 + $pos
$SEEK_CUR
The new offset of the file handle will be set to $cur + $pos bytes, or, relative to the current file handle offset.
$cur + $pos
$SEEK_END
The new offset of the file will be set to $size + $pos bytes, or, relative to the end of the file.
$size + $pos
$fs->close($fd)
Close the file handle issued for the given file descriptor, and deallocate said file descriptor. The file descriptor will then be freed for subsequent use and issue by $fs->open.
$fs->open
$fs->fdopen($fd)
Returns the underlying file handle opened for the file descriptor passed.
Written by Xan Tronix <xan@cpan.org>
Copyright (c) 2014, cPanel, Inc. Distributed under the terms of the Perl Artistic license.
To install Filesys::POSIX, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Filesys::POSIX
CPAN shell
perl -MCPAN -e shell install Filesys::POSIX
For more information on module installation, please visit the detailed CPAN module installation guide.