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 ($ok, $err) = is_file('/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 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 they are present that means that a function is asynchronous. If event loop parameter is missing, the default loop is used.
The synchronous functions interface returns their result immediately on the stack, while for asynchronous functions it will be returned in the callback.
In void and scalar contexts for a synchronous function, if an error occurs, it will be thrown. In scalar context it returns either boolean, meaning the success, or the appropriate value (e.g. file descriptor). In the list context in the error case it returns undef and the XS::ErrorCode; otherwise the first value on the stack is the result of an operation, and the second value is undef.
The most of functions here duplicate perl buildin functions, with the exception that there are asynchronous variants (which means they can be executed on different threads by backend, e.g. by libuv, transparently to the call site).
FUNCTIONS
mkdir($path [, $mode = 0755])
mkdir($path, $mode, $callback [, $loop])
mkpath($path [, $mode = 0755])
mkpath($path, $mode, $callback [, $loop])
mkdir creates single directory with the defined mode. The mkpath recursively creates all non-existing directories within the specified $path.
rmdir($path)
rmdir($path, $callback [, $loop])
Removes single empty directory. This function is non-recursive.
unlink($path)
unlink($path, $callback [, $loop])
Remove the file.
remove($path)
remove($path, $callback [, $loop])
Remove a file or a directory, non-recursively.
remove_all($path)
remove_all($path, $callback [, $loop])
If the $path is a file, removes it. Otherwise, it recursively removes the directory.
scandir($path)
scandir($path, $callback [, $loop])
Recursively traverses over the directory, specified by $path parameter, and gathers all files and directories inside. The result is an flat arrayref of filenames and file types, i.e.
my $list = scandir('/tmp');
say "found" if (grep { $_->[0] eq 'secret.key' && $_->[1] == FTYPE_DIR);open($path, $flags, [, $mode = 0644])
open($path, $flags, $mode, $callback [, $loop])
Opens the file on the specified $path with the specified $flags (see "FILE OPEN MODES" below) and $mode (i.e. unix file permissions). The return type is file descriptor (aka integer).
my $fd = Fs::open($file, OPEN_RDWR | OPEN_CREAT);close($fd)
close($fd, $callback [, $loop])
Closes file descriptor $fd. The return type is boolean (success of the operation).
stat($fd_or_path)
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.
lstat($fd_or_path)
lstat($fd_or_path, $callback [, $loop])
stat version for symbolic link.
exists($path)
exists($path, $callback [, $loop])
Checks whether the file exists.
is_file($path)
is_file($path, $callback [, $loop])
Checks whether the file at the $path is regular file or not.
is_dir($path)
is_dir($path, $callback [, $loop])
Checks whether the $path is directory or not.
access($path [, $mode = 0])
access($path, $mode, $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.
sync($fd)
sync($fd, $callback [, $loop])
Synchronizes file data and metadata specified by $fd with storage.
datasync($fd)
datasync($fd, $callback [, $loop])
Synchronizes file data specified by $fd with storage.
truncate($path_or_fd, $length = 0)
truncate($path_or_fd, $length, $callback [, $loop])
Causes the file to have size exactly $length bytes.
chmod($path_or_fd, $mode)
chmod($path_or_fd, $mode, $callback [, $loop])
Changes file mode, e.g. to 0644.
touch($path [, $mode = DEFAULT_FILE_MODE])
touch($path, $mode, $callback [, $fs])
Creates the file if it does not exist, and changes its $mode.
utime($path_or_fd, $atime, $mtime)
utime($path_or_fd, $atime, $mtime, $callback [, $loop])
Changes file access and modification times.
chown($path_or_fd, $uid, $gid)
chown($path_or_fd, $uid, $gid, $callback [, $loop])
Changes file user and group ownership.
lchown($path_or_fd, $uid, $gid)
lchown($path_or_fd, $uid, $gid, $callback [, $loop])
chown variant for symbolic links.
rename($from, $to)
rename($from, $to, $callback [, $loop])
Changes name or location of a file.
sendfile($fd_in, $fd_out, $offset, $length)
sendfile($fd_in, $fd_out, $offset, $length, $callback [, $loop])
Causes OS kernel to transfer bytes between file descriptors.
link($from, $to)
link($from, $to, $callback [, $loop])
Make a new hardlink for a regular file.
symlink($from, $to, $flags = 0)
symlink($from, $to, $flags, $callback [, $loop])
Make a new symbolic link for a file. See description of $flags like SYMLINK_DIR and SYMLINK_JUNCTION.
readlink($path)
readlink($path, $callback [, $loop])
Read the contents of a symbolic link, i.e. where the link points to.
realpath($path)
realpath($path, $callback [, $loop])
Return the canonicalized absolute pathname.
copyfile($from, $to, $flags)
copyfile($from, $to, $flags, $callback [, $loop])
Copies old file from $from into new location, determined by $to. For the $flags see description link "COPY FILE MODES" below.
mkdtemp($template)
mkdtemp($template, $callback [, $loop])
Create a unique temporary directory, using the $template, which must end with six trailing X symbols.
read($fd, $size [, $offset = -1])
read($fd, $size, $offset, $callback [, $loop])
Read from file $fd $size bytes (skipping <$offset>). Return type is buffer string with the file contents.
write($fd, $buffer [, $offset = -1])
write($fd, $buffer, $offset, $callback [, $loop])
Writes $buffer string content into file $fd, skipping $offset bytes.
CONSTANTS
FILE OPEN FLAGS
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_SYMLINK
OPEN_SYNC
OPEN_TEMPORARY
OPEN_TRUNC
OPEN_WRONLY
FILE/DIR MODES
DEFAULT_FILE_MODE
0644
DEFAULT_DIR_MODE
0755
SYMLINK MODES (win32 only)
SYMLINK_DIR
Indicates that path points to a directory
SYMLINK_JUNCTION
request that the symlink is created using junction points.
COPY FILE MODES
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.
FILE TYPES
FTYPE_BLOCK
FTYPE_CHAR
FTYPE_DIR
FTYPE_FIFO
FTYPE_LINK
FTYPE_FILE
FTYPE_SOCKET
FTYPE_UNKNOWN
FILE STAT CONSTANTS
STAT_DEV
STAT_INO
STAT_MODE
STAT_NLINK
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
STAT_PERMS
TYPE
Fs type constant