Class FsReq

Synopsis

#include <src/uvw/fs.h>

class FsReq final: public FsRequest<FsReq>

Description

The FsReq request.

Cross-platform sync and async filesystem operations.
All file operations are run on the threadpool.

To create a FsReq through a Loop, no arguments are required.

See the official documentation for further details.

Inheritance

Ancestors: FsRequest

Methods

~FsReq
accessAsync access.
accessSyncSync access.
chmodAsync chmod.
chmodSyncSync chmod.
chownAsync chown.
chownSyncSync chown.
closedirCloses asynchronously a directory stream.
closedirSyncCloses synchronously a directory stream.
copyfileCopies a file asynchronously from a path to a new one.
copyfileSyncCopies a file synchronously from a path to a new one.
lchownAsync lchown.
lchownSyncSync lchown.
linkSyncSync link.
lstatAsync lstat.
lstatSyncSync lstat.
lutimeAsync lutime.
lutimeSyncSync lutime.
mkdirAsync mkdir.
mkdirSyncSync mkdir.
mkdtempAsync mktemp.
mkdtempSyncSync mktemp.
mkstempAsync mkstemp.
mkstempSyncSync mkstemp.
opendirOpens a path asynchronously as a directory stream.
opendirSyncOpens a path synchronously as a directory stream.
readdirIterates asynchronously over a directory stream one entry at a time.
readdirSyncIterates synchronously over a directory stream one entry at a time.
readlinkSyncSync readlink.
realpathAsync realpath.
realpathSyncSync realpath.
renameAsync rename.
renameSyncSync rename.
rmdirAsync rmdir.
rmdirSyncSync rmdir.
scandirAsync scandir.
scandirNextGets entries populated with the next directory entry data.
scandirSyncSync scandir.
statAsync stat.
statfsAsync statfs.
statfsSyncSync statfs.
statSyncSync stat.
symlinkSyncSync symlink.
unlinkSyncSync unlink.
utimeAsync utime.
utimeSyncSync utime.

Source

Lines 787-1424 in src/uvw/fs.h.

class FsReq final: public FsRequest<FsReq> {
    static void fsReadlinkCallback(uv_fs_t *req);
    static void fsReaddirCallback(uv_fs_t *req);

public:
    using CopyFile = details::UVCopyFileFlags;
    using SymLink = details::UVSymLinkFlags;

    using FsRequest::FsRequest;

    ~FsReq() noexcept;

    /**
     * @brief Async [unlink](http://linux.die.net/man/2/unlink).
     *
     * Emit a `FsEvent<FsReq::Type::UNLINK>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void unlink(const std::string &path);

    /**
     * @brief Sync [unlink](http://linux.die.net/man/2/unlink).
     * @param path Path, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool unlinkSync(const std::string &path);

    /**
     * @brief Async [mkdir](http://linux.die.net/man/2/mkdir).
     *
     * Emit a `FsEvent<FsReq::Type::MKDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     */
    void mkdir(const std::string &path, int mode);

    /**
     * @brief Sync [mkdir](http://linux.die.net/man/2/mkdir).
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool mkdirSync(const std::string &path, int mode);

    /**
     * @brief Async [mktemp](http://linux.die.net/man/3/mkdtemp).
     *
     * Emit a `FsEvent<FsReq::Type::MKDTEMP>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param tpl Template, as described in the official documentation.
     */
    void mkdtemp(const std::string &tpl);

    /**
     * @brief Sync [mktemp](http://linux.die.net/man/3/mkdtemp).
     *
     * @param tpl Template, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * The actual path of the newly created directory.
     */
    std::pair<bool, const char *> mkdtempSync(const std::string &tpl);

    /**
     * @brief Async [mkstemp](https://linux.die.net/man/3/mkstemp).
     *
     * Emit a `FsEvent<FsReq::Type::MKSTEMP>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param tpl Template, as described in the official documentation.
     */
    void mkstemp(const std::string &tpl);

    /**
     * @brief Sync [mkstemp](https://linux.die.net/man/3/mkstemp).
     *
     * Returns a composed value where:
     *
     * * The first parameter indicates the created file path.
     * * The second parameter is the file descriptor as an integer.
     *
     * See the official
     * [documentation](http://docs.libuv.org/en/v1.x/fs.html#c.uv_fs_mkstemp)
     * for further details.
     *
     * @param tpl Template, as described in the official documentation.
     *
     * @return A pair where:

     * * The first parameter is a boolean value that is true in case of success,
     * false otherwise.
     * * The second parameter is a composed value (see above).
     */
    std::pair<bool, std::pair<std::string, std::size_t>> mkstempSync(const std::string &tpl);

    /**
     * @brief Async [lutime](http://linux.die.net/man/3/lutimes).
     *
     * Emit a `FsEvent<FsReq::Type::UTIME>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param atime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @param mtime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     */
    void lutime(const std::string &path, Time atime, Time mtime);

    /**
     * @brief Sync [lutime](http://linux.die.net/man/3/lutimes).
     * @param path Path, as described in the official documentation.
     * @param atime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @param mtime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool lutimeSync(const std::string &path, Time atime, Time mtime);

    /**
     * @brief Async [rmdir](http://linux.die.net/man/2/rmdir).
     *
     * Emit a `FsEvent<FsReq::Type::RMDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void rmdir(const std::string &path);

    /**
     * @brief Sync [rmdir](http://linux.die.net/man/2/rmdir).
     * @param path Path, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool rmdirSync(const std::string &path);

    /**
     * @brief Async [scandir](http://linux.die.net/man/3/scandir).
     *
     * Emit a `FsEvent<FsReq::Type::SCANDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param flags Flags, as described in the official documentation.
     */
    void scandir(const std::string &path, int flags);

    /**
     * @brief Sync [scandir](http://linux.die.net/man/3/scandir).
     *
     * @param path Path, as described in the official documentation.
     * @param flags Flags, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * The number of directory entries selected.
     */
    std::pair<bool, std::size_t> scandirSync(const std::string &path, int flags);

    /**
     * @brief Gets entries populated with the next directory entry data.
     *
     * Returns a composed value where:
     *
     * * The first parameter indicates the entry type (see below).
     * * The second parameter is a string that contains the actual value.
     *
     * Available entry types are:
     *
     * * `FsReq::EntryType::UNKNOWN`
     * * `FsReq::EntryType::FILE`
     * * `FsReq::EntryType::DIR`
     * * `FsReq::EntryType::LINK`
     * * `FsReq::EntryType::FIFO`
     * * `FsReq::EntryType::SOCKET`
     * * `FsReq::EntryType::CHAR`
     * * `FsReq::EntryType::BLOCK`
     *
     * See the official
     * [documentation](http://docs.libuv.org/en/v1.x/fs.html#c.uv_dirent_t)
     * for further details.
     *
     * @return A pair where:
     *
     * * The first parameter is a boolean value that indicates if the current
     * entry is still valid.
     * * The second parameter is a composed value (see above).
     */
    std::pair<bool, std::pair<EntryType, const char *>> scandirNext();

    /**
     * @brief Async [stat](http://linux.die.net/man/2/stat).
     *
     * Emit a `FsEvent<FsReq::Type::STAT>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void stat(const std::string &path);

    /**
     * @brief Sync [stat](http://linux.die.net/man/2/stat).
     *
     * @param path Path, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * An initialized instance of Stat.
     */
    std::pair<bool, Stat> statSync(const std::string &path);

    /**
     * @brief Async [lstat](http://linux.die.net/man/2/lstat).
     *
     * Emit a `FsEvent<FsReq::Type::LSTAT>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void lstat(const std::string &path);

    /**
     * @brief Sync [lstat](http://linux.die.net/man/2/lstat).
     *
     * @param path Path, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * An initialized instance of Stat.
     */
    std::pair<bool, Stat> lstatSync(const std::string &path);

    /**
     * @brief Async [statfs](http://linux.die.net/man/2/statfs).
     *
     * Emit a `FsEvent<FsReq::Type::STATFS>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * Any fields in the resulting object that are not supported by the
     * underlying operating system are set to zero.
     *
     * @param path Path, as described in the official documentation.
     */
    void statfs(const std::string &path);

    /**
     * @brief Sync [statfs](http://linux.die.net/man/2/statfs).
     *
     * Any fields in the resulting object that are not supported by the
     * underlying operating system are set to zero.
     *
     * @param path Path, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * An initialized instance of Statfs.
     */
    std::pair<bool, Statfs> statfsSync(const std::string &path);

    /**
     * @brief Async [rename](http://linux.die.net/man/2/rename).
     *
     * Emit a `FsEvent<FsReq::Type::RENAME>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     */
    void rename(const std::string &old, const std::string &path);

    /**
     * @brief Sync [rename](http://linux.die.net/man/2/rename).
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool renameSync(const std::string &old, const std::string &path);

    /**
     * @brief Copies a file asynchronously from a path to a new one.
     *
     * Emit a `FsEvent<FsReq::Type::UV_FS_COPYFILE>` event when
     * completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * Available flags are:
     *
     * * `FsReq::CopyFile::EXCL`: it fails if the destination path
     * already exists (the default behavior is to overwrite the destination if
     * it exists).
     * * `FsReq::CopyFile::FICLONE`: If present, it will attempt to create a
     * copy-on-write reflink. If the underlying platform does not support
     * copy-on-write, then a fallback copy mechanism is used.
     * * `FsReq::CopyFile::FICLONE_FORCE`: If present, it will attempt to create
     * a copy-on-write reflink. If the underlying platform does not support
     * copy-on-write, then an error is returned.
     *
     * @warning
     * If the destination path is created, but an error occurs while copying the
     * data, then the destination path is removed. There is a brief window of
     * time between closing and removing the file where another process could
     * access the file.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @param flags Optional additional flags.
     */
    void copyfile(const std::string &old, const std::string &path, Flags<CopyFile> flags = Flags<CopyFile>{});

    /**
     * @brief Copies a file synchronously from a path to a new one.
     *
     * Available flags are:
     *
     * * `FsReq::CopyFile::EXCL`: it fails if the destination path
     * already exists (the default behavior is to overwrite the destination if
     * it exists).
     *
     * If the destination path is created, but an error occurs while copying the
     * data, then the destination path is removed. There is a brief window of
     * time between closing and removing the file where another process could
     * access the file.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @param flags Optional additional flags.
     * @return True in case of success, false otherwise.
     */
    bool copyfileSync(const std::string &old, const std::string &path, Flags<CopyFile> flags = Flags<CopyFile>{});

    /**
     * @brief Async [access](http://linux.die.net/man/2/access).
     *
     * Emit a `FsEvent<FsReq::Type::ACCESS>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     */
    void access(const std::string &path, int mode);

    /**
     * @brief Sync [access](http://linux.die.net/man/2/access).
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool accessSync(const std::string &path, int mode);

    /**
     * @brief Async [chmod](http://linux.die.net/man/2/chmod).
     *
     * Emit a `FsEvent<FsReq::Type::CHMOD>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     */
    void chmod(const std::string &path, int mode);

    /**
     * @brief Sync [chmod](http://linux.die.net/man/2/chmod).
     * @param path Path, as described in the official documentation.
     * @param mode Mode, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool chmodSync(const std::string &path, int mode);

    /**
     * @brief Async [utime](http://linux.die.net/man/2/utime).
     *
     * Emit a `FsEvent<FsReq::Type::UTIME>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param atime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @param mtime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     */
    void utime(const std::string &path, Time atime, Time mtime);

    /**
     * @brief Sync [utime](http://linux.die.net/man/2/utime).
     * @param path Path, as described in the official documentation.
     * @param atime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @param mtime `std::chrono::duration<double>`, having the same meaning as
     * described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool utimeSync(const std::string &path, Time atime, Time mtime);

    /**
     * @brief Async [link](http://linux.die.net/man/2/link).
     *
     * Emit a `FsEvent<FsReq::Type::LINK>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     */
    void link(const std::string &old, const std::string &path);

    /**
     * @brief Sync [link](http://linux.die.net/man/2/link).
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool linkSync(const std::string &old, const std::string &path);

    /**
     * @brief Async [symlink](http://linux.die.net/man/2/symlink).
     *
     * Emit a `FsEvent<FsReq::Type::SYMLINK>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * Available flags are:
     *
     * * `FsReq::SymLink::DIR`: it indicates that the old path points to a
     * directory.
     * * `FsReq::SymLink::JUNCTION`: it requests that the symlink is created
     * using junction points.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @param flags Optional additional flags.
     */
    void symlink(const std::string &old, const std::string &path, Flags<SymLink> flags = Flags<SymLink>{});

    /**
     * @brief Sync [symlink](http://linux.die.net/man/2/symlink).
     *
     * Available flags are:
     *
     * * `FsReq::SymLink::DIR`: it indicates that the old path points to a
     * directory.
     * * `FsReq::SymLink::JUNCTION`: it requests that the symlink is created
     * using junction points.
     *
     * @param old Old path, as described in the official documentation.
     * @param path New path, as described in the official documentation.
     * @param flags Flags, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool symlinkSync(const std::string &old, const std::string &path, Flags<SymLink> flags = Flags<SymLink>{});

    /**
     * @brief Async [readlink](http://linux.die.net/man/2/readlink).
     *
     * Emit a `FsEvent<FsReq::Type::READLINK>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void readlink(const std::string &path);

    /**
     * @brief Sync [readlink](http://linux.die.net/man/2/readlink).
     *
     * @param path Path, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * A `std::pair` composed as it follows:
     *   * A bunch of data read from the given path.
     *   * The amount of data read from the given path.
     */
    std::pair<bool, std::pair<const char *, std::size_t>> readlinkSync(const std::string &path);

    /**
     * @brief Async [realpath](http://linux.die.net/man/3/realpath).
     *
     * Emit a `FsEvent<FsReq::Type::REALPATH>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     */
    void realpath(const std::string &path);

    /**
     * @brief Sync [realpath](http://linux.die.net/man/3/realpath).
     *
     * @param path Path, as described in the official documentation.
     *
     * @return A `std::pair` composed as it follows:
     * * A boolean value that is true in case of success, false otherwise.
     * * The canonicalized absolute pathname.
     */
    std::pair<bool, const char *> realpathSync(const std::string &path);

    /**
     * @brief Async [chown](http://linux.die.net/man/2/chown).
     *
     * Emit a `FsEvent<FsReq::Type::CHOWN>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param uid UID, as described in the official documentation.
     * @param gid GID, as described in the official documentation.
     */
    void chown(const std::string &path, Uid uid, Gid gid);

    /**
     * @brief Sync [chown](http://linux.die.net/man/2/chown).
     * @param path Path, as described in the official documentation.
     * @param uid UID, as described in the official documentation.
     * @param gid GID, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool chownSync(const std::string &path, Uid uid, Gid gid);

    /**
     * @brief Async [lchown](https://linux.die.net/man/2/lchown).
     *
     * Emit a `FsEvent<FsReq::Type::LCHOWN>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * @param path Path, as described in the official documentation.
     * @param uid UID, as described in the official documentation.
     * @param gid GID, as described in the official documentation.
     */
    void lchown(const std::string &path, Uid uid, Gid gid);

    /**
     * @brief Sync [lchown](https://linux.die.net/man/2/lchown).
     * @param path Path, as described in the official documentation.
     * @param uid UID, as described in the official documentation.
     * @param gid GID, as described in the official documentation.
     * @return True in case of success, false otherwise.
     */
    bool lchownSync(const std::string &path, Uid uid, Gid gid);

    /**
     * @brief Opens a path asynchronously as a directory stream.
     *
     * Emit a `FsEvent<FsReq::Type::OPENDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * The contents of the directory can be iterated over by means of the
     * `readdir` od `readdirSync` member functions. The memory allocated by this
     * function must be freed by calling `closedir` or `closedirSync`.
     *
     * @param path The path to open as a directory stream.
     */
    void opendir(const std::string &path);

    /**
     * @brief Opens a path synchronously as a directory stream.
     *
     * The contents of the directory can be iterated over by means of the
     * `readdir` od `readdirSync` member functions. The memory allocated by this
     * function must be freed by calling `closedir` or `closedirSync`.
     *
     * @param path The path to open as a directory stream.
     * @return True in case of success, false otherwise.
     */
    bool opendirSync(const std::string &path);

    /**
     * @brief Closes asynchronously a directory stream.
     *
     * Emit a `FsEvent<FsReq::Type::CLOSEDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * It frees also the memory allocated internally when a path has been opened
     * as a directory stream.
     */
    void closedir();

    /**
     * @brief Closes synchronously a directory stream.
     *
     * It frees also the memory allocated internally when a path has been opened
     * as a directory stream.
     *
     * @return True in case of success, false otherwise.
     */
    bool closedirSync();

    /**
     * @brief Iterates asynchronously over a directory stream one entry at a
     * time.
     *
     * Emit a `FsEvent<FsReq::Type::READDIR>` event when completed.<br/>
     * Emit an ErrorEvent event in case of errors.
     *
     * This function isn't thread safe. Moreover, it doesn't return the `.` and
     * `..` entries.
     */
    void readdir();

    /**
     * @brief Iterates synchronously over a directory stream one entry at a
     * time.
     *
     * Returns a composed value where:
     *
     * * The first parameter indicates the entry type (see below).
     * * The second parameter is a string that contains the actual value.
     *
     * Available entry types are:
     *
     * * `FsReq::EntryType::UNKNOWN`
     * * `FsReq::EntryType::FILE`
     * * `FsReq::EntryType::DIR`
     * * `FsReq::EntryType::LINK`
     * * `FsReq::EntryType::FIFO`
     * * `FsReq::EntryType::SOCKET`
     * * `FsReq::EntryType::CHAR`
     * * `FsReq::EntryType::BLOCK`
     *
     * See the official
     * [documentation](http://docs.libuv.org/en/v1.x/fs.html#c.uv_dirent_t)
     * for further details.
     *
     * This function isn't thread safe. Moreover, it doesn't return the `.` and
     * `..` entries.
     *
     * @return A pair where:
     *
     * * The first parameter is a boolean value that indicates if the current
     * entry is still valid.
     * * The second parameter is a composed value (see above).
     */
    std::pair<bool, std::pair<EntryType, const char *>> readdirSync();

private:
    uv_dirent_t dirents[1];
};





Add Discussion as Guest

Log in