/ 
UniEvent-1.2.13
River stage one • 5 direct dependents • 5 total dependents
/ UniEvent::Fs

NAME

UniEvent::Fs - sync and async cross-platform filesystem interface

SYNOPSIS

use UniEvent::Fs;

# synchronous API
my $fd = UniEvent::Fs::open('/tmp/my-file');  # throws on error
copyfile('/tmp/from', '/tmp/to');             # throws on error
my ($stat, $err) = Fs::stat('/tmp/murzilka'); # never throws

# asynchronous API
UniEvent::Fs::open('/tmp/my-file', sub {
    my ($fd, $err) = @_;
});
UniEvent::Loop->default_loop->run;

DESCRIPTION

The package is a collection of filesystem related functions, like creating a directory, touching, copying files etc.

All the functions have dual interface, i.e. synchronous and asynchronous. For convenience they have the same name and parameters, and only differ by the additional trailing parameters: the callback and the optional event loop. If callback is specified then function will behave asynchronously. If loop argument is not specified while callback present, the default loop is used.

The synchronous functions interface returns their result immediately on the stack (if not void), while for asynchronous functions it will be returned in the callback (if not void).

Many functions here duplicate perl builtin functions, with the exception that there are asynchronous variants.

FUNCTIONS

NOTE: All synchronous versions of the functions May return error. Exception from this rule is exists(), is_dir(), is_file(). They always return bool without errors.

NOTE: Async callback receives one (for void functions) or two arguments (for non-void): the return value (as synchronous version would, if not void) and the error object as XS::STL::ErrorCode if any. Exception from this rule is exists(), is_dir(), is_file(). Their callbacks receives single bool without errors.

mkdir($path, [$mode = 0755], [$callback] , [$loop])

mkpath($path, [$mode = 0755], [$callback], [$loop])

mkdir creates single directory with the defined mode. The mkpath recursively creates all non-existing directories within the specified $path.

RETURNS: void

Fs::mkdir($path, sub {
    my $err = shift;
});

rmdir($path, [$callback], [$loop])

Removes single empty directory. This function is non-recursive.

RETURNS: void

Fs::rmdir($path, sub {
    my $err = shift;
});

unlink($path, [$callback], [$loop])

Remove a file.

RETURNS: void

remove($path, [$callback], [$loop])

Remove a file or a directory, non-recursively.

RETURNS: void

remove_all($path, [$callback], [$loop])

If the $path is a file, removes it. Otherwise, it recursively removes the directory.

RETURNS: void

scandir($path, [$callback], [$loop])

Recursively traverses over the directory, specified by $path parameter, and gathers all files and directories inside.

RETURNS: arrayref of filenames and file types

my $list = scandir('/tmp');
say "found" if (grep { $_->[0] eq 'secret.key' && $_->[1] == UE::Fs::FTYPE_DIR);

For the list of file type constants, see stat() docs below.

open($path, $flags, [$mode = 0644], [$callback], [$loop])

Opens the file on the specified $path with the specified $flags and $mode (i.e. unix file permissions).

$flags is a bitmask of the following constants (UE::Fs::*):

OPEN_APPEND
OPEN_CREAT
OPEN_DIRECT
OPEN_DIRECTORY
OPEN_DSYNC
OPEN_EXCL
OPEN_EXLOCK
OPEN_NOATIME
OPEN_NOCTTY
OPEN_NOFOLLOW
OPEN_RANDOM
OPEN_RDONLY
OPEN_RDWR
OPEN_SEQUENTIAL
OPEN_SHORT_LIVED
OPEN_SYNC
OPEN_TEMPORARY
OPEN_TRUNC
OPEN_WRONLY

RETURNS: file descriptor (aka integer).

Fs::open($file, UE::Fs::OPEN_RDWR | UE::Fs::OPEN_CREAT, 0644, sub {
    my ($fd, $err) = @_;
});

close($fd, [$callback], [$loop])

Closes file descriptor $fd.

RETURNS: void

stat($fd_or_path, [$callback], [$loop])

Get information about file, defined by file descriptor or path. The returned information is identical to perl buildin stat function.

RETURNS: array reference with stat properties.

For convenience indexes are defined as constants (UE::Fs::*):

STAT_DEV
STAT_INO
STAT_MODE
STAT_UID
STAT_GID
STAT_RDEV
STAT_SIZE
STAT_ATIME
STAT_MTIME
STAT_CTIME
STAT_BLKSIZE
STAT_BLOCKS
STAT_FLAGS
STAT_GEN
STAT_BIRTHTIME
STAT_TYPE

File type, one of the following constants (UE::Fs::*):

FTYPE_BLOCK
FTYPE_CHAR
FTYPE_DIR
FTYPE_FIFO
FTYPE_FILE
FTYPE_SOCKET
FTYPE_UNKNOWN
STAT_PERMS
my $stat = Fs::stat($path);
say $stat->[UE::Fs::STAT_TYPE] == UE::Fs::FTYPE_FILE;
say $stat->[UE::Fs::STAT_SIZE];

lstat($path, [$callback], [$loop])

stat version for symbolic link (does not follow symbolic links, instead returns info on the link file itself).

statfs($path, [$callback], [$loop])

Get information about filesystem, like system's statfs().

RETURNS: array reference with statfs properties.

For convenience indexes are defined as constants (UE::Fs::*):

STATFS_TYPE
STATFS_BSIZE
STATFS_BLOCKS
STATFS_BFREE
STATFS_BAVAIL
STATFS_FILES
STATFS_FFREE
STATFS_SPARE

exists($path, [$callback], [$loop])

Checks whether the path exists.

RETURNS: bool

is_file($path, [$callback], [$loop])

Checks whether the $path exists and it is a regular file.

RETURNS: bool

is_dir($path)

is_dir($path, [$callback], [$loop])

Checks whether the $path exists and is a directory.

RETURNS: bool

access($path, [$mode = 0], [$callback], [$loop])

Determines accessability of the file. The mode is common unix filepath permissions, i.e. 1 for execute, 2 for writing, 4 for reading.

RETURNS: void

sync($fd, [$callback], [$loop])

Synchronizes file data and metadata specified by $fd with storage.

RETURNS: void

datasync($fd, [$callback], [$loop])

Synchronizes file data specified by $fd with storage.

RETURNS: void

truncate($path_or_fd, [$length = 0], [$callback], [$loop])

Causes the file to have size exactly $length bytes.

RETURNS: void

chmod($path_or_fd, $mode, [$callback], [$loop])

Changes file mode (permissions).

RETURNS: void

touch($path, [$mode = DEFAULT_FILE_MODE], [$callback], [$loop])

Updates file's mtime, creating the file if it does not exist with mode $mode.

RETURNS: void

utime($path_or_fd, $atime, $mtime, [$callback], [$loop])

Changes file access and modification times.

RETURNS: void

lutime($path, $atime, $mtime, [$callback], [$loop])

Changes file access and modification times. Does not follow symlinks.

RETURNS: void

chown($path_or_fd, $uid, $gid, [$callback], [$loop])

Changes file user and group ownership.

RETURNS: void

lchown($path_or_fd, $uid, $gid, [$callback], [$loop])

chown variant for symbolic links (does not follow symlinks).

RETURNS: void

rename($from, $to, [$callback], [$loop])

Changes name or location of a file.

RETURNS: void

sendfile($fd_in, $fd_out, $offset, $length, [$callback], [$loop])

Causes OS kernel to transfer bytes between file descriptors.

RETURNS: number of bytes written to $fd_out

link($from, $to, [$callback], [$loop])

Make a new hardlink for a regular file.

RETURNS: void

symlink($from, $to, [$flags = 0], [$callback], [$loop])

Make a new symbolic link for a file.

On Windows the $flags parameter can be specified to control how the symlink will be created (UE::Fs::*):

Indicates that path points to a directory

request that the symlink is created using junction points.

RETURNS: void

readlink($path, [$callback], [$loop])

Read the contents of a symbolic link, i.e. where the link points to.

RETURNS: string

realpath($path, [$callback], [$loop])

Return the canonicalized absolute pathname.

RETURNS: string

copyfile($from, $to, $flags, [$callback], [$loop])

Copies old file from $from into new location, determined by $to.

Supported flags are described below (as UE::Fs::* constants):

COPYFILE_EXCL

Copy will fail if the destination path already exists. The default behavior is to overwrite the destination if it exists.

COPYFILE_FICLONE

Will attempt to create a copy-on-write reflink. Falls back to sendfile() in case of error or if the underlying OS does not support that feature.

COPYFILE_FICLONE_FORCE

Will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, or an error occurs while attempting to use copy-on-write, then fails.

RETURNS: void

mkdtemp($template, [$callback], [$loop])

Create a unique temporary directory, using the $template, which must end with six trailing XXXXXX symbols.

RETURNS: string

mkstemp($template, [$callback], [$loop])

Create a unique temporary file, using the $template, which must end with six trailing XXXXXX symbols.

RETURNS: arrayref with 2 elements: resulting path and file descriptor.

read($fd, $size, [$offset = -1], [$callback], [$loop])

Read from file $fd $size bytes (skipping <$offset>).

RETURNS: string with the file contents

write($fd, $buffer, [$offset = -1], [$callback], [$loop])

Writes $buffer into file $fd, skipping $offset bytes.

RETURNS: void

CONSTANTS

Most of the constants are listed in functions docs where they are used.

DEFAULT_FILE_MODE

0644

DEFAULT_DIR_MODE

0755