NAME

Filesys::POSIX::Extensions - Provides features not found in a POSIX environment environment

SYNOPSIS

use Filesys::POSIX;
use Filesys::POSIX::Mem;

my $fs = Filesys::POSIX->new(Filesys::POSIX::Mem->new,
    'noatime' => 1
);

$fs->import_module('Filesys::POSIX::Extensions');

DESCRIPTION

This module of extensions provides system calls that would be considered nonstandard in a POSIX environment, but nonetheless provide their functionality with standard filesystem semantics. These extensions provide novel means of performing efficient filesystem manipulation, allowing the developer to attach arbitrary inodes in specified locations, detach, replace, and perform cross- device symlinks.

SYSTEM CALLS

$fs->attach($inode, $dest)

Attaches the given inode object to the filesystem in the specified location. Exceptions will be thrown for the following:

File exists

An inode at the destination path already exists.

Upon success, the inode provided will be returned to the caller.

$fs->map($real_src, $dest)

Manifests a Filesys::POSIX::Real::Inode object corresponding to the actual inode from the underlying filesystem whose path is specified by $real_src, and attaches it to the virtual filesystem in the location specified by $dest.

Any inodes mapped from the real filesystem into a virtual filesystem have the sticky update flag set, meaning, only certain operations made on the in-memory inode affect the real inode. See Filesys::POSIX::Real for further details.

Exceptions will be thrown in the following conditions:

File exists

An inode at the destination path already exists.

Other exceptions may be thrown, based on the availability and permissions of the actual inode referred to by $real_src.

Upon success, a reference to the Filesys::POSIX::Real::Inode object created will be returned to the caller.

$fs->alias($src, $dest)

Very similar to $fs->link, however this system call allows inode aliases to be made across filesystem mount points. It is also possible to alias directories, unlike $fs->link. Exceptions will be thrown for the following:

File exists

An inode at the destination path was found.

Upon success, a reference to the source inode will be returned to the caller.

$fs->detach($path)

Detaches the inode of the given path from the virtual filesystem. This call is similar to $fs->unlink, except a different underlying, filesystem- dependent method is used to detach an inode from the path's parent directory in the case of $fs->unlink. Both directories and non-directories alike can be detached from any point in the filesystem using this call; directories do not have to be empty.

Given a directory object, the $directory->detach call is used, which only removes the inode from the directory itself; whereas $directory->delete, as used by $fs->unlink, would perform an unlink() at the system level in the case of a Filesys::POSIX::Real::Directory. object. This way, it is possible to only perform logical deletes of inodes, without affecting the underlying filesystem when managing inodes brought into existence using other system calls in this extensions module.

Exceptions are thrown for the following:

No such file or directory

Thrown when the parent directory of the item in $path does not contain an item named in the final component of the path.

Upon success, a reference to the inode detached from the filesystem will be returned.

$fs->replace($path, $inode)

Replaces an existent inode specified by $path with the inode object passed in the $inode argument. The existing and specified inodes can be of any type.

Exceptions will be thrown for the following:

No such file or directory

No inode was found at the path specified.

Upon success, a reference to the inode passed to this method will be returned to the caller.