UniEvent::Fs - sync and async cross-platform filesystem interface
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;
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.
callback
loop
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.
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.
exists()
is_dir()
is_file()
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 creates single directory with the defined mode. The mkpath recursively creates all non-existing directories within the specified $path.
mkdir
mkpath
RETURNS: void
Fs::mkdir($path, sub { my $err = shift; });
Removes single empty directory. This function is non-recursive.
Fs::rmdir($path, sub { my $err = shift; });
Remove a file.
Remove a file or a directory, non-recursively.
If the $path is a file, removes it. Otherwise, it recursively removes the directory.
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.
stat()
Opens the file on the specified $path with the specified $flags and $mode (i.e. unix file permissions).
$flags
$mode
$flags is a bitmask of the following constants (UE::Fs::*):
RETURNS: file descriptor (aka integer).
Fs::open($file, UE::Fs::OPEN_RDWR | UE::Fs::OPEN_CREAT, 0644, sub { my ($fd, $err) = @_; });
Closes file descriptor $fd.
$fd
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::*):
File type, one of the following constants (UE::Fs::*):
my $stat = Fs::stat($path); say $stat->[UE::Fs::STAT_TYPE] == UE::Fs::FTYPE_FILE; say $stat->[UE::Fs::STAT_SIZE];
stat version for symbolic link (does not follow symbolic links, instead returns info on the link file itself).
stat
Get information about filesystem, like system's statfs().
statfs()
RETURNS: array reference with statfs properties.
Checks whether the path exists.
RETURNS: bool
Checks whether the $path exists and it is a regular file.
$path
Checks whether the $path exists and is a directory.
Determines accessability of the file. The mode is common unix filepath permissions, i.e. 1 for execute, 2 for writing, 4 for reading.
1
2
4
Synchronizes file data and metadata specified by $fd with storage.
Synchronizes file data specified by $fd with storage.
Causes the file to have size exactly $length bytes.
$length
Changes file mode (permissions).
Updates file's mtime, creating the file if it does not exist with mode $mode.
mtime
Changes file access and modification times.
Changes file access and modification times. Does not follow symlinks.
Changes file user and group ownership.
chown variant for symbolic links (does not follow symlinks).
chown
Changes name or location of a file.
Causes OS kernel to transfer bytes between file descriptors.
RETURNS: number of bytes written to $fd_out
$fd_out
Make a new hardlink for a regular file.
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.
Read the contents of a symbolic link, i.e. where the link points to.
RETURNS: string
Return the canonicalized absolute pathname.
Copies old file from $from into new location, determined by $to.
$from
$to
Supported flags are described below (as UE::Fs::* constants):
Copy will fail if the destination path already exists. The default behavior is to overwrite the destination if it exists.
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.
sendfile()
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.
Create a unique temporary directory, using the $template, which must end with six trailing XXXXXX symbols.
XXXXXX
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 from file $fd $size bytes (skipping <$offset>).
$size
RETURNS: string with the file contents
Writes $buffer into file $fd, skipping $offset bytes.
$buffer
$offset
Most of the constants are listed in functions docs where they are used.
0644
0755
To install UniEvent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm UniEvent
CPAN shell
perl -MCPAN -e shell install UniEvent
For more information on module installation, please visit the detailed CPAN module installation guide.