Filesystem operations¶
libuv provides a wide variety of cross-platform sync and async filesystem 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
¶ Filesystem 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
¶ Filesystem 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_type;
-
uv_dirent_t
¶ Cross platform (reduced) equivalent of
struct dirent
. Used inuv_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()
oruv_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_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).
-
int
uv_fs_unlink
(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)¶ 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_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 entriesUV_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 filesystems (btrfs, ext2, ext3 and ext4 at the time of this writing), check the getdents(2) man page.
-
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_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_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_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)¶
-
int
uv_fs_link
(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb)¶ Equivalent to link(2).
-
int
uv_fs_symlink
(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb)¶ 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.
-
int
uv_fs_readlink
(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)¶ Equivalent to readlink(2).
-
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.