Blame docs/src/fs.rst

Packit b5b901
Packit b5b901
.. _fs:
Packit b5b901
Packit b5b901
File system operations
Packit b5b901
======================
Packit b5b901
Packit b5b901
libuv provides a wide variety of cross-platform sync and async file system
Packit b5b901
operations. All functions defined in this document take a callback, which is
Packit b5b901
allowed to be NULL. If the callback is NULL the request is completed synchronously,
Packit b5b901
otherwise it will be performed asynchronously.
Packit b5b901
Packit b5b901
All file operations are run on the threadpool. See :ref:`threadpool` for information
Packit b5b901
on the threadpool size.
Packit b5b901
Packit Service e08953
.. note::
Packit Service e08953
     On Windows `uv_fs_*` functions use utf-8 encoding.
Packit b5b901
Packit b5b901
Data types
Packit b5b901
----------
Packit b5b901
Packit b5b901
.. c:type:: uv_fs_t
Packit b5b901
Packit b5b901
    File system request type.
Packit b5b901
Packit b5b901
.. c:type:: uv_timespec_t
Packit b5b901
Packit b5b901
    Portable equivalent of ``struct timespec``.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef struct {
Packit b5b901
            long tv_sec;
Packit b5b901
            long tv_nsec;
Packit b5b901
        } uv_timespec_t;
Packit b5b901
Packit b5b901
.. c:type:: uv_stat_t
Packit b5b901
Packit b5b901
    Portable equivalent of ``struct stat``.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef struct {
Packit b5b901
            uint64_t st_dev;
Packit b5b901
            uint64_t st_mode;
Packit b5b901
            uint64_t st_nlink;
Packit b5b901
            uint64_t st_uid;
Packit b5b901
            uint64_t st_gid;
Packit b5b901
            uint64_t st_rdev;
Packit b5b901
            uint64_t st_ino;
Packit b5b901
            uint64_t st_size;
Packit b5b901
            uint64_t st_blksize;
Packit b5b901
            uint64_t st_blocks;
Packit b5b901
            uint64_t st_flags;
Packit b5b901
            uint64_t st_gen;
Packit b5b901
            uv_timespec_t st_atim;
Packit b5b901
            uv_timespec_t st_mtim;
Packit b5b901
            uv_timespec_t st_ctim;
Packit b5b901
            uv_timespec_t st_birthtim;
Packit b5b901
        } uv_stat_t;
Packit b5b901
Packit b5b901
.. c:type:: uv_fs_type
Packit b5b901
Packit b5b901
    File system request type.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef enum {
Packit b5b901
            UV_FS_UNKNOWN = -1,
Packit b5b901
            UV_FS_CUSTOM,
Packit b5b901
            UV_FS_OPEN,
Packit b5b901
            UV_FS_CLOSE,
Packit b5b901
            UV_FS_READ,
Packit b5b901
            UV_FS_WRITE,
Packit b5b901
            UV_FS_SENDFILE,
Packit b5b901
            UV_FS_STAT,
Packit b5b901
            UV_FS_LSTAT,
Packit b5b901
            UV_FS_FSTAT,
Packit b5b901
            UV_FS_FTRUNCATE,
Packit b5b901
            UV_FS_UTIME,
Packit b5b901
            UV_FS_FUTIME,
Packit b5b901
            UV_FS_ACCESS,
Packit b5b901
            UV_FS_CHMOD,
Packit b5b901
            UV_FS_FCHMOD,
Packit b5b901
            UV_FS_FSYNC,
Packit b5b901
            UV_FS_FDATASYNC,
Packit b5b901
            UV_FS_UNLINK,
Packit b5b901
            UV_FS_RMDIR,
Packit b5b901
            UV_FS_MKDIR,
Packit b5b901
            UV_FS_MKDTEMP,
Packit b5b901
            UV_FS_RENAME,
Packit b5b901
            UV_FS_SCANDIR,
Packit b5b901
            UV_FS_LINK,
Packit b5b901
            UV_FS_SYMLINK,
Packit b5b901
            UV_FS_READLINK,
Packit b5b901
            UV_FS_CHOWN,
Packit b5b901
            UV_FS_FCHOWN,
Packit b5b901
            UV_FS_REALPATH,
Packit b5b901
            UV_FS_COPYFILE,
Packit Service e08953
            UV_FS_LCHOWN,
Packit Service e08953
            UV_FS_OPENDIR,
Packit Service e08953
            UV_FS_READDIR,
Packit Service e08953
            UV_FS_CLOSEDIR,
Packit Service e08953
            UV_FS_MKSTEMP,
Packit Service e08953
            UV_FS_LUTIME
Packit b5b901
        } uv_fs_type;
Packit b5b901
Packit Service e08953
.. c:type:: uv_statfs_t
Packit Service e08953
Packit Service e08953
    Reduced cross platform equivalent of ``struct statfs``.
Packit Service e08953
    Used in :c:func:`uv_fs_statfs`.
Packit Service e08953
Packit Service e08953
    ::
Packit Service e08953
Packit Service e08953
        typedef struct uv_statfs_s {
Packit Service e08953
            uint64_t f_type;
Packit Service e08953
            uint64_t f_bsize;
Packit Service e08953
            uint64_t f_blocks;
Packit Service e08953
            uint64_t f_bfree;
Packit Service e08953
            uint64_t f_bavail;
Packit Service e08953
            uint64_t f_files;
Packit Service e08953
            uint64_t f_ffree;
Packit Service e08953
            uint64_t f_spare[4];
Packit Service e08953
        } uv_statfs_t;
Packit Service e08953
Packit b5b901
.. c:type:: uv_dirent_t
Packit b5b901
Packit b5b901
    Cross platform (reduced) equivalent of ``struct dirent``.
Packit b5b901
    Used in :c:func:`uv_fs_scandir_next`.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef enum {
Packit b5b901
            UV_DIRENT_UNKNOWN,
Packit b5b901
            UV_DIRENT_FILE,
Packit b5b901
            UV_DIRENT_DIR,
Packit b5b901
            UV_DIRENT_LINK,
Packit b5b901
            UV_DIRENT_FIFO,
Packit b5b901
            UV_DIRENT_SOCKET,
Packit b5b901
            UV_DIRENT_CHAR,
Packit b5b901
            UV_DIRENT_BLOCK
Packit b5b901
        } uv_dirent_type_t;
Packit b5b901
Packit b5b901
        typedef struct uv_dirent_s {
Packit b5b901
            const char* name;
Packit b5b901
            uv_dirent_type_t type;
Packit b5b901
        } uv_dirent_t;
Packit b5b901
Packit Service e08953
.. c:type:: uv_dir_t
Packit Service e08953
Packit Service e08953
    Data type used for streaming directory iteration.
Packit Service e08953
    Used by :c:func:`uv_fs_opendir()`, :c:func:`uv_fs_readdir()`, and
Packit Service e08953
    :c:func:`uv_fs_closedir()`. `dirents` represents a user provided array of
Packit Service e08953
    `uv_dirent_t`s used to hold results. `nentries` is the user provided maximum
Packit Service e08953
    array size of `dirents`.
Packit Service e08953
Packit Service e08953
    ::
Packit Service e08953
Packit Service e08953
        typedef struct uv_dir_s {
Packit Service e08953
            uv_dirent_t* dirents;
Packit Service e08953
            size_t nentries;
Packit Service e08953
        } uv_dir_t;
Packit Service e08953
Packit b5b901
Packit b5b901
Public members
Packit b5b901
^^^^^^^^^^^^^^
Packit b5b901
Packit b5b901
.. c:member:: uv_loop_t* uv_fs_t.loop
Packit b5b901
Packit b5b901
    Loop that started this request and where completion will be reported.
Packit b5b901
    Readonly.
Packit b5b901
Packit b5b901
.. c:member:: uv_fs_type uv_fs_t.fs_type
Packit b5b901
Packit b5b901
    FS request type.
Packit b5b901
Packit b5b901
.. c:member:: const char* uv_fs_t.path
Packit b5b901
Packit b5b901
    Path affecting the request.
Packit b5b901
Packit b5b901
.. c:member:: ssize_t uv_fs_t.result
Packit b5b901
Packit b5b901
    Result of the request. < 0 means error, success otherwise. On requests such
Packit b5b901
    as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of
Packit b5b901
    data that was read or written, respectively.
Packit b5b901
Packit b5b901
.. c:member:: uv_stat_t uv_fs_t.statbuf
Packit b5b901
Packit b5b901
    Stores the result of :c:func:`uv_fs_stat` and other stat requests.
Packit b5b901
Packit b5b901
.. c:member:: void* uv_fs_t.ptr
Packit b5b901
Packit b5b901
    Stores the result of :c:func:`uv_fs_readlink` and
Packit b5b901
    :c:func:`uv_fs_realpath` and serves as an alias to `statbuf`.
Packit b5b901
Packit b5b901
.. seealso:: The :c:type:`uv_req_t` members also apply.
Packit b5b901
Packit b5b901
Packit b5b901
API
Packit b5b901
---
Packit b5b901
Packit b5b901
.. c:function:: void uv_fs_req_cleanup(uv_fs_t* req)
Packit b5b901
Packit b5b901
    Cleanup request. Must be called after a request is finished to deallocate
Packit b5b901
    any memory libuv might have allocated.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`close(2)`.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`open(2)`.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        On Windows libuv uses `CreateFileW` and thus the file is always opened
Packit b5b901
        in binary mode. Because of this the O_BINARY and O_TEXT flags are not
Packit b5b901
        supported.
Packit b5b901
Packit b5b901
.. c:function:: 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)
Packit b5b901
Packit b5b901
    Equivalent to :man:`preadv(2)`.
Packit b5b901
Packit Service e08953
    .. warning::
Packit Service e08953
        On Windows, under non-MSVC environments (e.g. when GCC or Clang is used
Packit Service e08953
        to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal
Packit Service e08953
        crash if the memory mapped read operation fails.
Packit Service e08953
Packit b5b901
.. c:function:: int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`unlink(2)`.
Packit b5b901
Packit b5b901
.. c:function:: 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)
Packit b5b901
Packit b5b901
    Equivalent to :man:`pwritev(2)`.
Packit b5b901
Packit Service e08953
    .. warning::
Packit Service e08953
        On Windows, under non-MSVC environments (e.g. when GCC or Clang is used
Packit Service e08953
        to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal
Packit Service e08953
        crash if the memory mapped write operation fails.
Packit Service e08953
Packit b5b901
.. c:function:: int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`mkdir(2)`.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `mode` is currently not implemented on Windows.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb)
Packit b5b901
Packit Service e08953
    Equivalent to :man:`mkdtemp(3)`. The result can be found as a null terminated string at `req->path`.
Packit b5b901
Packit Service e08953
.. c:function:: int uv_fs_mkstemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb)
Packit Service e08953
Packit Service e08953
    Equivalent to :man:`mkstemp(3)`. The created file path can be found as a null terminated string at `req->path`.
Packit Service e08953
    The file descriptor can be found as an integer at `req->result`.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.34.0
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`rmdir(2)`.
Packit b5b901
Packit Service e08953
.. c:function:: int uv_fs_opendir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit Service e08953
Packit Service e08953
    Opens `path` as a directory stream. On success, a `uv_dir_t` is allocated
Packit Service e08953
    and returned via `req->ptr`. This memory is not freed by
Packit Service e08953
    `uv_fs_req_cleanup()`, although `req->ptr` is set to `NULL`. The allocated
Packit Service e08953
    memory must be freed by calling `uv_fs_closedir()`. On failure, no memory
Packit Service e08953
    is allocated.
Packit Service e08953
Packit Service e08953
    The contents of the directory can be iterated over by passing the resulting
Packit Service e08953
    `uv_dir_t` to `uv_fs_readdir()`.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.28.0
Packit Service e08953
Packit Service e08953
.. c:function:: int uv_fs_closedir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb)
Packit Service e08953
Packit Service e08953
    Closes the directory stream represented by `dir` and frees the memory
Packit Service e08953
    allocated by `uv_fs_opendir()`.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.28.0
Packit Service e08953
Packit Service e08953
.. c:function:: int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb)
Packit Service e08953
Packit Service e08953
    Iterates over the directory stream, `dir`, returned by a successful
Packit Service e08953
    `uv_fs_opendir()` call. Prior to invoking `uv_fs_readdir()`, the caller
Packit Service e08953
    must set `dir->dirents` and `dir->nentries`, representing the array of
Packit Service e08953
    :c:type:`uv_dirent_t` elements used to hold the read directory entries and
Packit Service e08953
    its size.
Packit Service e08953
Packit Service e08953
    On success, the result is an integer >= 0 representing the number of entries
Packit Service e08953
    read from the stream.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.28.0
Packit Service e08953
Packit Service e08953
    .. warning::
Packit Service e08953
        `uv_fs_readdir()` is not thread safe.
Packit Service e08953
Packit Service e08953
    .. note::
Packit Service e08953
        This function does not return the "." and ".." entries.
Packit Service e08953
Packit Service e08953
    .. note::
Packit Service e08953
        On success this function allocates memory that must be freed using
Packit Service e08953
        `uv_fs_req_cleanup()`. `uv_fs_req_cleanup()` must be called before
Packit Service e08953
        closing the directory with `uv_fs_closedir()`.
Packit Service e08953
Packit b5b901
.. c:function:: int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb)
Packit b5b901
.. c:function:: int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent)
Packit b5b901
Packit b5b901
    Equivalent to :man:`scandir(3)`, with a slightly different API. Once the callback
Packit b5b901
    for the request is called, the user can use :c:func:`uv_fs_scandir_next` to
Packit b5b901
    get `ent` populated with the next directory entry data. When there are no
Packit b5b901
    more entries ``UV_EOF`` will be returned.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        Unlike `scandir(3)`, this function does not return the "." and ".." entries.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        On Linux, getting the type of an entry is only supported by some file systems (btrfs, ext2,
Packit b5b901
        ext3 and ext4 at the time of this writing), check the :man:`getdents(2)` man page.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
.. c:function:: int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
Packit b5b901
.. c:function:: int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`stat(2)`, :man:`fstat(2)` and :man:`lstat(2)` respectively.
Packit b5b901
Packit Service e08953
.. c:function:: int uv_fs_statfs(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit Service e08953
Packit Service e08953
    Equivalent to :man:`statfs(2)`. On success, a `uv_statfs_t` is allocated
Packit Service e08953
    and returned via `req->ptr`. This memory is freed by `uv_fs_req_cleanup()`.
Packit Service e08953
Packit Service e08953
    .. note::
Packit Service e08953
        Any fields in the resulting `uv_statfs_t` that are not supported by the
Packit Service e08953
        underlying operating system are set to zero.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.31.0
Packit Service e08953
Packit b5b901
.. c:function:: int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`rename(2)`.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`fsync(2)`.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        For AIX, `uv_fs_fsync` returns `UV_EBADF` on file descriptors referencing
Packit b5b901
        non regular files.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`fdatasync(2)`.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`ftruncate(2)`.
Packit b5b901
Packit b5b901
.. c:function:: 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)
Packit b5b901
Packit b5b901
    Copies a file from `path` to `new_path`. Supported `flags` are described below.
Packit b5b901
Packit b5b901
    - `UV_FS_COPYFILE_EXCL`: If present, `uv_fs_copyfile()` will fail with
Packit b5b901
      `UV_EEXIST` if the destination path already exists. The default behavior
Packit b5b901
      is to overwrite the destination if it exists.
Packit b5b901
    - `UV_FS_COPYFILE_FICLONE`: If present, `uv_fs_copyfile()` will attempt to
Packit b5b901
      create a copy-on-write reflink. If the underlying platform does not
Packit Service e08953
      support copy-on-write, or an error occurs while attempting to use
Packit Service e08953
      copy-on-write, a fallback copy mechanism based on
Packit Service e08953
      :c:func:`uv_fs_sendfile()` is used.
Packit b5b901
    - `UV_FS_COPYFILE_FICLONE_FORCE`: If present, `uv_fs_copyfile()` will
Packit b5b901
      attempt to create a copy-on-write reflink. If the underlying platform does
Packit Service e08953
      not support copy-on-write, or an error occurs while attempting to use
Packit Service e08953
      copy-on-write, then an error is returned.
Packit b5b901
Packit b5b901
    .. warning::
Packit b5b901
        If the destination path is created, but an error occurs while copying
Packit b5b901
        the data, then the destination path is removed. There is a brief window
Packit b5b901
        of time between closing and removing the file where another process
Packit b5b901
        could access the file.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.14.0
Packit b5b901
Packit b5b901
    .. versionchanged:: 1.20.0 `UV_FS_COPYFILE_FICLONE` and
Packit b5b901
        `UV_FS_COPYFILE_FICLONE_FORCE` are supported.
Packit b5b901
Packit Service e08953
    .. versionchanged:: 1.33.0 If an error occurs while using
Packit Service e08953
        `UV_FS_COPYFILE_FICLONE_FORCE`, that error is returned. Previously,
Packit Service e08953
        all errors were mapped to `UV_ENOTSUP`.
Packit Service e08953
Packit b5b901
.. c:function:: 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)
Packit b5b901
Packit b5b901
    Limited equivalent to :man:`sendfile(2)`.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`access(2)` on Unix. Windows uses ``GetFileAttributesW()``.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
Packit b5b901
.. c:function:: int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`chmod(2)` and :man:`fchmod(2)` respectively.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb)
Packit b5b901
.. c:function:: int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb)
Packit Service e08953
.. c:function:: int uv_fs_lutime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb)
Packit b5b901
Packit Service e08953
    Equivalent to :man:`utime(2)`, :man:`futimes(3)` and :man:`lutimes(3)` respectively.
Packit b5b901
Packit b5b901
    .. note::
Packit Service e08953
      z/OS: `uv_fs_lutime()` is not implemented for z/OS. It can still be called but will return
Packit Service e08953
      ``UV_ENOSYS``.
Packit Service e08953
Packit Service e08953
    .. note::
Packit Service e08953
      AIX: `uv_fs_futime()` and `uv_fs_lutime()` functions only work for AIX 7.1 and newer.
Packit Service e08953
      They can still be called on older versions but will return ``UV_ENOSYS``.
Packit b5b901
Packit b5b901
    .. versionchanged:: 1.10.0 sub-second precission is supported on Windows
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`link(2)`.
Packit b5b901
Packit b5b901
.. c:function:: 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)
Packit b5b901
Packit b5b901
    Equivalent to :man:`symlink(2)`.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        On Windows the `flags` parameter can be specified to control how the symlink will
Packit b5b901
        be created:
Packit b5b901
Packit b5b901
            * ``UV_FS_SYMLINK_DIR``: indicates that `path` points to a directory.
Packit b5b901
Packit b5b901
            * ``UV_FS_SYMLINK_JUNCTION``: request that the symlink is created
Packit b5b901
              using junction points.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`readlink(2)`.
Packit b5b901
    The resulting string is stored in `req->ptr`.
Packit b5b901
Packit b5b901
.. c:function:: int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
Packit b5b901
Packit Service e08953
    Equivalent to :man:`realpath(3)` on Unix. Windows uses `GetFinalPathNameByHandle <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlea>`_.
Packit b5b901
    The resulting string is stored in `req->ptr`.
Packit b5b901
Packit b5b901
    .. warning::
Packit b5b901
        This function has certain platform-specific caveats that were discovered when used in Node.
Packit b5b901
Packit b5b901
        * macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are
Packit b5b901
          found while resolving the given path.  This limit is hardcoded and cannot be sidestepped.
Packit b5b901
        * Windows: while this function works in the common case, there are a number of corner cases
Packit b5b901
          where it doesn't:
Packit b5b901
Packit b5b901
          - Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk)
Packit b5b901
            cannot be resolved.
Packit b5b901
          - Inconsistent casing when using drive letters.
Packit b5b901
          - Resolved path bypasses subst'd drives.
Packit b5b901
Packit b5b901
        While this function can still be used, it's not recommended if scenarios such as the
Packit b5b901
        above need to be supported.
Packit b5b901
Packit b5b901
        The background story and some more details on these issues can be checked
Packit b5b901
        `here <https://github.com/nodejs/node/issues/7726>`_.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
      This function is not implemented on Windows XP and Windows Server 2003.
Packit b5b901
      On these systems, UV_ENOSYS is returned.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.8.0
Packit b5b901
Packit b5b901
.. c:function:: 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)
Packit b5b901
.. c:function:: 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)
Packit b5b901
.. c:function:: int uv_fs_lchown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb)
Packit b5b901
Packit b5b901
    Equivalent to :man:`chown(2)`, :man:`fchown(2)` and :man:`lchown(2)` respectively.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        These functions are not implemented on Windows.
Packit b5b901
Packit b5b901
    .. versionchanged:: 1.21.0 implemented uv_fs_lchown
Packit b5b901
Packit b5b901
.. c:function:: uv_fs_type uv_fs_get_type(const uv_fs_t* req)
Packit b5b901
Packit b5b901
    Returns `req->fs_type`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit b5b901
.. c:function:: ssize_t uv_fs_get_result(const uv_fs_t* req)
Packit b5b901
Packit b5b901
    Returns `req->result`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit Service e08953
.. c:function:: int uv_fs_get_system_error(const uv_fs_t* req)
Packit Service e08953
Packit Service e08953
    Returns the platform specific error code - `GetLastError()` value on Windows
Packit Service e08953
    and `-(req->result)` on other platforms.
Packit Service e08953
Packit Service e08953
    .. versionadded:: 1.38.0
Packit Service e08953
Packit b5b901
.. c:function:: void* uv_fs_get_ptr(const uv_fs_t* req)
Packit b5b901
Packit b5b901
    Returns `req->ptr`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit b5b901
.. c:function:: const char* uv_fs_get_path(const uv_fs_t* req)
Packit b5b901
Packit b5b901
    Returns `req->path`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit b5b901
.. c:function:: uv_stat_t* uv_fs_get_statbuf(uv_fs_t* req)
Packit b5b901
Packit b5b901
    Returns `&req->statbuf`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit b5b901
.. seealso:: The :c:type:`uv_req_t` API functions also apply.
Packit b5b901
Packit b5b901
Helper functions
Packit b5b901
----------------
Packit b5b901
Packit b5b901
.. c:function:: uv_os_fd_t uv_get_osfhandle(int fd)
Packit b5b901
Packit b5b901
   For a file descriptor in the C runtime, get the OS-dependent handle.
Packit Service e08953
   On UNIX, returns the ``fd`` intact. On Windows, this calls `_get_osfhandle <https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/get-osfhandle?view=vs-2019>`_.
Packit b5b901
   Note that the return value is still owned by the C runtime,
Packit b5b901
   any attempts to close it or to use it after closing the fd may lead to malfunction.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.12.0
Packit b5b901
Packit b5b901
.. c:function:: int uv_open_osfhandle(uv_os_fd_t os_fd)
Packit b5b901
Packit b5b901
   For a OS-dependent handle, get the file descriptor in the C runtime.
Packit Service e08953
   On UNIX, returns the ``os_fd`` intact. On Windows, this calls `_open_osfhandle <https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/open-osfhandle?view=vs-2019>`_.
Packit b5b901
   Note that the return value is still owned by the CRT,
Packit b5b901
   any attempts to close it or to use it after closing the handle may lead to malfunction.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.23.0
Packit b5b901
Packit b5b901
File open constants
Packit b5b901
-------------------
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_APPEND
Packit b5b901
Packit b5b901
    The file is opened in append mode. Before each write, the file offset is
Packit b5b901
    positioned at the end of the file.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_CREAT
Packit b5b901
Packit b5b901
    The file is created if it does not already exist.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_DIRECT
Packit b5b901
Packit b5b901
    File I/O is done directly to and from user-space buffers, which must be
Packit b5b901
    aligned. Buffer size and address should be a multiple of the physical sector
Packit b5b901
    size of the block device.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_DIRECT` is supported on Linux, and on Windows via
Packit Service e08953
        `FILE_FLAG_NO_BUFFERING <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_.
Packit b5b901
        `UV_FS_O_DIRECT` is not supported on macOS.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_DIRECTORY
Packit b5b901
Packit b5b901
    If the path is not a directory, fail the open.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_DIRECTORY` is not supported on Windows.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_DSYNC
Packit b5b901
Packit b5b901
    The file is opened for synchronous I/O. Write operations will complete once
Packit b5b901
    all data and a minimum of metadata are flushed to disk.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_DSYNC` is supported on Windows via
Packit Service e08953
        `FILE_FLAG_WRITE_THROUGH <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_EXCL
Packit b5b901
Packit b5b901
    If the `O_CREAT` flag is set and the file already exists, fail the open.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        In general, the behavior of `O_EXCL` is undefined if it is used without
Packit b5b901
        `O_CREAT`. There is one exception: on Linux 2.6 and later, `O_EXCL` can
Packit b5b901
        be used without `O_CREAT` if pathname refers to a block device. If the
Packit b5b901
        block device is in use by the system (e.g., mounted), the open will fail
Packit b5b901
        with the error `EBUSY`.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_EXLOCK
Packit b5b901
Packit b5b901
    Atomically obtain an exclusive lock.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_EXLOCK` is only supported on macOS and Windows.
Packit b5b901
Packit b5b901
    .. versionchanged:: 1.17.0 support is added for Windows.
Packit b5b901
Packit Service e08953
.. c:macro:: UV_FS_O_FILEMAP
Packit Service e08953
Packit Service e08953
    Use a memory file mapping to access the file. When using this flag, the
Packit Service e08953
    file cannot be open multiple times concurrently.
Packit Service e08953
Packit Service e08953
    .. note::
Packit Service e08953
        `UV_FS_O_FILEMAP` is only supported on Windows.
Packit Service e08953
Packit b5b901
.. c:macro:: UV_FS_O_NOATIME
Packit b5b901
Packit b5b901
    Do not update the file access time when the file is read.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_NOATIME` is not supported on Windows.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_NOCTTY
Packit b5b901
Packit b5b901
    If the path identifies a terminal device, opening the path will not cause
Packit b5b901
    that terminal to become the controlling terminal for the process (if the
Packit b5b901
    process does not already have one).
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_NOCTTY` is not supported on Windows.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_NOFOLLOW
Packit b5b901
Packit b5b901
    If the path is a symbolic link, fail the open.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_NOFOLLOW` is not supported on Windows.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_NONBLOCK
Packit b5b901
Packit b5b901
    Open the file in nonblocking mode if possible.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_NONBLOCK` is not supported on Windows.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_RANDOM
Packit b5b901
Packit b5b901
    Access is intended to be random. The system can use this as a hint to
Packit b5b901
    optimize file caching.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_RANDOM` is only supported on Windows via
Packit Service e08953
        `FILE_FLAG_RANDOM_ACCESS <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_RDONLY
Packit b5b901
Packit b5b901
    Open the file for read-only access.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_RDWR
Packit b5b901
Packit b5b901
    Open the file for read-write access.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_SEQUENTIAL
Packit b5b901
Packit b5b901
    Access is intended to be sequential from beginning to end. The system can
Packit b5b901
    use this as a hint to optimize file caching.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_SEQUENTIAL` is only supported on Windows via
Packit Service e08953
        `FILE_FLAG_SEQUENTIAL_SCAN <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_SHORT_LIVED
Packit b5b901
Packit b5b901
    The file is temporary and should not be flushed to disk if possible.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_SHORT_LIVED` is only supported on Windows via
Packit Service e08953
        `FILE_ATTRIBUTE_TEMPORARY <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_SYMLINK
Packit b5b901
Packit b5b901
    Open the symbolic link itself rather than the resource it points to.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_SYNC
Packit b5b901
Packit b5b901
    The file is opened for synchronous I/O. Write operations will complete once
Packit b5b901
    all data and all metadata are flushed to disk.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_SYNC` is supported on Windows via
Packit Service e08953
        `FILE_FLAG_WRITE_THROUGH <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_TEMPORARY
Packit b5b901
Packit b5b901
    The file is temporary and should not be flushed to disk if possible.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        `UV_FS_O_TEMPORARY` is only supported on Windows via
Packit Service e08953
        `FILE_ATTRIBUTE_TEMPORARY <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_TRUNC
Packit b5b901
Packit b5b901
    If the file exists and is a regular file, and the file is opened
Packit b5b901
    successfully for write access, its length shall be truncated to zero.
Packit b5b901
Packit b5b901
.. c:macro:: UV_FS_O_WRONLY
Packit b5b901
Packit b5b901
    Open the file for write-only access.