File system operations

libuv provides a wide variety of cross-platform sync and async file system operations. All functions defined in this document take a callback, which is allowed to be NULL. If the callback is NULL the request is completed synchronously, otherwise it will be performed asynchronously.

All file operations are run on the threadpool. See Thread pool work scheduling for information on the threadpool size.

Data types

uv_fs_t

File system request type.

uv_timespec_t

Portable equivalent of struct timespec.

typedef struct {
    long tv_sec;
    long tv_nsec;
} uv_timespec_t;
uv_stat_t

Portable equivalent of struct stat.

typedef struct {
    uint64_t st_dev;
    uint64_t st_mode;
    uint64_t st_nlink;
    uint64_t st_uid;
    uint64_t st_gid;
    uint64_t st_rdev;
    uint64_t st_ino;
    uint64_t st_size;
    uint64_t st_blksize;
    uint64_t st_blocks;
    uint64_t st_flags;
    uint64_t st_gen;
    uv_timespec_t st_atim;
    uv_timespec_t st_mtim;
    uv_timespec_t st_ctim;
    uv_timespec_t st_birthtim;
} uv_stat_t;
uv_fs_type

File system request type.

typedef enum {
    UV_FS_UNKNOWN = -1,
    UV_FS_CUSTOM,
    UV_FS_OPEN,
    UV_FS_CLOSE,
    UV_FS_READ,
    UV_FS_WRITE,
    UV_FS_SENDFILE,
    UV_FS_STAT,
    UV_FS_LSTAT,
    UV_FS_FSTAT,
    UV_FS_FTRUNCATE,
    UV_FS_UTIME,
    UV_FS_FUTIME,
    UV_FS_ACCESS,
    UV_FS_CHMOD,
    UV_FS_FCHMOD,
    UV_FS_FSYNC,
    UV_FS_FDATASYNC,
    UV_FS_UNLINK,
    UV_FS_RMDIR,
    UV_FS_MKDIR,
    UV_FS_MKDTEMP,
    UV_FS_RENAME,
    UV_FS_SCANDIR,
    UV_FS_LINK,
    UV_FS_SYMLINK,
    UV_FS_READLINK,
    UV_FS_CHOWN,
    UV_FS_FCHOWN,
    UV_FS_REALPATH,
    UV_FS_COPYFILE
} uv_fs_type;
uv_dirent_t

Cross platform (reduced) equivalent of struct dirent. Used in uv_fs_scandir_next().

typedef enum {
    UV_DIRENT_UNKNOWN,
    UV_DIRENT_FILE,
    UV_DIRENT_DIR,
    UV_DIRENT_LINK,
    UV_DIRENT_FIFO,
    UV_DIRENT_SOCKET,
    UV_DIRENT_CHAR,
    UV_DIRENT_BLOCK
} uv_dirent_type_t;

typedef struct uv_dirent_s {
    const char* name;
    uv_dirent_type_t type;
} uv_dirent_t;

Public members

uv_loop_t* uv_fs_t.loop

Loop that started this request and where completion will be reported. Readonly.

uv_fs_type uv_fs_t.fs_type

FS request type.

const char* uv_fs_t.path

Path affecting the request.

ssize_t uv_fs_t.result

Result of the request. < 0 means error, success otherwise. On requests such as uv_fs_read() or uv_fs_write() it indicates the amount of data that was read or written, respectively.

uv_stat_t uv_fs_t.statbuf

Stores the result of uv_fs_stat() and other stat requests.

void* uv_fs_t.ptr

Stores the result of uv_fs_readlink() and serves as an alias to statbuf.

See also

The uv_req_t members also apply.

API

void uv_fs_req_cleanup(uv_fs_t* req)

Cleanup request. Must be called after a request is finished to deallocate any memory libuv might have allocated.

int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)

Equivalent to close(2).

int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb)

Equivalent to open(2).

Note

On Windows libuv uses CreateFileW and thus the file is always opened in binary mode. Because of this the O_BINARY and O_TEXT flags are not supported.

int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb)

Equivalent to preadv(2).

Equivalent to unlink(2).

int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb)

Equivalent to pwritev(2).

int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)

Equivalent to mkdir(2).

Note

mode is currently not implemented on Windows.

int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb)

Equivalent to mkdtemp(3).

Note

The result can be found as a null terminated string at req->path.

int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)

Equivalent to rmdir(2).

int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb)
int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent)

Equivalent to scandir(3), with a slightly different API. Once the callback for the request is called, the user can use uv_fs_scandir_next() to get ent populated with the next directory entry data. When there are no more entries UV_EOF will be returned.

Note

Unlike scandir(3), this function does not return the “.” and “..” entries.

Note

On Linux, getting the type of an entry is only supported by some file systems (btrfs, ext2, ext3 and ext4 at the time of this writing), check the getdents(2) man page.

int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)

Equivalent to stat(2), fstat(2) and lstat(2) respectively.

int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb)

Equivalent to rename(2).

int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)

Equivalent to fsync(2).

int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)

Equivalent to fdatasync(2).

int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb)

Equivalent to ftruncate(2).

int uv_fs_copyfile(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb)

Copies a file from path to new_path. Supported flags are described below.

  • UV_FS_COPYFILE_EXCL: If present, uv_fs_copyfile() will fail with UV_EEXIST if the destination path already exists. The default behavior is to overwrite the destination if it exists.

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.

New in version 1.14.0.

int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb)

Limited equivalent to sendfile(2).

int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)

Equivalent to access(2) on Unix. Windows uses GetFileAttributesW().

int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb)

Equivalent to chmod(2) and fchmod(2) respectively.

int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb)
int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb)

Equivalent to utime(2) and futime(2) respectively.

Note

AIX: This function only works for AIX 7.1 and newer. It can still be called on older versions but will return UV_ENOSYS.

Changed in version 1.10.0: sub-second precission is supported on Windows

Equivalent to link(2).

Equivalent to symlink(2).

Note

On Windows the flags parameter can be specified to control how the symlink will be created:

  • UV_FS_SYMLINK_DIR: indicates that path points to a directory.
  • UV_FS_SYMLINK_JUNCTION: request that the symlink is created using junction points.

Equivalent to readlink(2).

int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)

Equivalent to realpath(3) on Unix. Windows uses GetFinalPathNameByHandle.

Warning

This function has certain platform-specific caveats that were discovered when used in Node.

  • macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are found while resolving the given path. This limit is hardcoded and cannot be sidestepped.
  • Windows: while this function works in the common case, there are a number of corner cases where it doesn’t:
    • Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) cannot be resolved.
    • Inconsistent casing when using drive letters.
    • Resolved path bypasses subst’d drives.

While this function can still be used, it’s not recommended if scenarios such as the above need to be supported.

The background story and some more details on these issues can be checked here.

Note

This function is not implemented on Windows XP and Windows Server 2003. On these systems, UV_ENOSYS is returned.

New in version 1.8.0.

int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb)
int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb)

Equivalent to chown(2) and fchown(2) respectively.

Note

These functions are not implemented on Windows.

See also

The uv_req_t API functions also apply.

Helper functions

uv_os_fd_t uv_get_osfhandle(int fd)

For a file descriptor in the C runtime, get the OS-dependent handle. On UNIX, returns the fd intact. On Windows, this calls _get_osfhandle. Note that the return value is still owned by the C runtime, any attempts to close it or to use it after closing the fd may lead to malfunction.

New in version 1.12.0.