view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    Create a new filesystem environment, specifying a reference to an
    uninitialized instance of a filesystem type object to be mounted at the root
    of the virtual filesystem.  Options passed will be passed to the filesystem
    initialization method `$rootfs->init()` in flat hash form, and passed on
    again to the VFS, where the options will be stored for later retrieval.

# ERROR HANDLING

Errors are emitted in the form of exceptions thrown by
[`Carp::confess()`](https://metacpan.org/pod/Carp#confess), with full stack traces.  Where possible,
[`$!`](https://metacpan.org/pod/perlvar#pod) is set with an appropriate error code from [Errno](https://metacpan.org/pod/Errno), and a
stringified [`$!`](https://metacpan.org/pod/perlvar#pod) is thrown.

# SYSTEM CALLS

- `$fs->umask()`
- `$fs->umask($mode)`

    When called without an argument, the current umask value is returned.  When a
    value is specified, the current umask is modified to that value, and is
    returned once set.

- `$fs->stat($path)`

    Resolve the given path for an inode in the filesystem.  If the inode found is
    a symlink, the path of that symlink will be resolved in turn until the desired
    inode is located.

    Paths will be resolved relative to the current working directory when not
    prefixed with a slash ('`/`'), and will be resolved relative to the root
    directory when prefixed with a slash ('`/`').

- `$fs->lstat($path)`

    Resolve the given path for an inode in the filesystem.  Unlinke
    `$fs->stat()`, the inode found will be returned literally in the case of a
    symlink.

- `$fs->fstat($fd)`

    Return the inode corresponding to the open file descriptor passed.  An
    exception will be thrown by the file descriptor lookup module if the file
    descriptor passed does not correspond to an open file.

- `$fs->chdir($path)`

    Change the current working directory to the path specified.  An
    `$fs->stat()` call will be used internally to lookup the inode for that
    path; an ENOTDIR will be thrown unless the inode found is a directory.  The
    internal current working directory pointer will be updated with the directory
    inode found; this same inode will also be returned.

- `$fs->fchdir($fd)`

    When passed a file descriptor for a directory, update the internal pointer to
    the current working directory to that directory resolved from the file
    descriptor table, and return the same directory inode.  If the inode is not a
    directory, an ENOTDIR will be thrown.

- `$fs->chown($path, $uid, $gid)`

    Using `$fs->stat()` to locate the inode of the path specified, update that
    inode object's 'uid' and 'gid' fields with the values specified.  The inode of
    the file modified will be returned.

- `$fs->fchown($fd, $uid, $gid)`

    Using `$fs->fstat()` to locate the inode of the file descriptor specified,
    update that inode object's 'uid' and 'gid' fields with the values specified.  A
    reference to the affected inode will be returned.

- `$fs->chmod($path, $mode)`

    Using `$fs->stat()` to locate the inode of the path specified, update that
    inode object's 'mode' field with the value specified.  A reference to the
    affected inode will be returned.

- `$fs->fchmod($fd, $mode)`

    Using `$fs->fstat()` to locate the inode of the file descriptor specified,
    update that inode object's 'mode' field with the value specified.  A reference
    to that inode will be returned.

- `$fs->mkdir($path)`
- `$fs->mkdir($path, $mode)`

    Create a new directory at the path specified, applying the permissions field in
    the mode value specified.  If no mode is specified, the default permissions of
    _0777_ will be modified by the current umask value.  An ENOTDIR exception will
    be thrown in case the intended parent of the directory to be created is not
    actually a directory itself.

    A reference to the newly-created directory inode will be returned.

- `$fs->link($src, $dest)`

    Using `$fs->stat()` to resolve the path of the link source, and the parent
    of the link destination, `$fs->link()` place a reference to the source
    inode in the location specified by the destination.

    If a destination inode already exists, it will only be able to be replaced by
    the source if both are either directories or non-directories.  If the source
    and destination are both directories, the destination will only be replaced if
    the directory entry for the destination is empty.

    Links traversing filesystem mount points are not allowed.  This functionality
    is provided in the `alias()` call provided by the [Filesys::POSIX::Extensions](https://metacpan.org/pod/Filesys::POSIX::Extensions)
    module.  Upon success, a reference to the inode for which a new link is to be
    created will be returned.

    Exceptions thrown:

    - EXDEV (Cross-device link)

        The inode resolved for the link source is not associated with the same device
        as the inode of the destination's parent directory.

    - EISDIR (Is a directory)

        Thrown if the source inode is a directory.  Hard links can only be made for
        non-directory inodes.

    - EEXIST (File exists)

        Thrown if an entry at the destination path already exists.