mirror of
https://github.com/EQEmu/Server.git
synced 2025-12-28 04:41:30 +00:00
327 lines
11 KiB
ReStructuredText
327 lines
11 KiB
ReStructuredText
|
|
.. _fs:
|
|
|
|
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 :ref:`threadpool` for information
|
|
on the threadpool size.
|
|
|
|
|
|
Data types
|
|
----------
|
|
|
|
.. c:type:: uv_fs_t
|
|
|
|
Filesystem request type.
|
|
|
|
.. c:type:: uv_timespec_t
|
|
|
|
Portable equivalent of ``struct timespec``.
|
|
|
|
::
|
|
|
|
typedef struct {
|
|
long tv_sec;
|
|
long tv_nsec;
|
|
} uv_timespec_t;
|
|
|
|
.. c:type:: 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;
|
|
|
|
.. c:type:: 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_REALPATH
|
|
} uv_fs_type;
|
|
|
|
.. c:type:: uv_dirent_t
|
|
|
|
Cross platform (reduced) equivalent of ``struct dirent``.
|
|
Used in :c:func:`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
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. c:member:: uv_loop_t* uv_fs_t.loop
|
|
|
|
Loop that started this request and where completion will be reported.
|
|
Readonly.
|
|
|
|
.. c:member:: uv_fs_type uv_fs_t.fs_type
|
|
|
|
FS request type.
|
|
|
|
.. c:member:: const char* uv_fs_t.path
|
|
|
|
Path affecting the request.
|
|
|
|
.. c:member:: ssize_t uv_fs_t.result
|
|
|
|
Result of the request. < 0 means error, success otherwise. On requests such
|
|
as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of
|
|
data that was read or written, respectively.
|
|
|
|
.. c:member:: uv_stat_t uv_fs_t.statbuf
|
|
|
|
Stores the result of :c:func:`uv_fs_stat` and other stat requests.
|
|
|
|
.. c:member:: void* uv_fs_t.ptr
|
|
|
|
Stores the result of :c:func:`uv_fs_readlink` and serves as an alias to
|
|
`statbuf`.
|
|
|
|
.. seealso:: The :c:type:`uv_req_t` members also apply.
|
|
|
|
|
|
API
|
|
---
|
|
|
|
.. c:function:: 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.
|
|
|
|
.. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`close(2)`.
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`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.
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`preadv(2)`.
|
|
|
|
.. c:function:: int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`unlink(2)`.
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`pwritev(2)`.
|
|
|
|
.. c:function:: int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`mkdir(2)`.
|
|
|
|
.. note::
|
|
`mode` is currently not implemented on Windows.
|
|
|
|
.. c:function:: int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`mkdtemp(3)`.
|
|
|
|
.. note::
|
|
The result can be found as a null terminated string at `req->path`.
|
|
|
|
.. c:function:: int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`rmdir(2)`.
|
|
|
|
.. c:function:: int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb)
|
|
.. c:function:: int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent)
|
|
|
|
Equivalent to :man:`scandir(3)`, with a slightly different API. Once the callback
|
|
for the request is called, the user can use :c:func:`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 filesystems (btrfs, ext2,
|
|
ext3 and ext4 at the time of this writing), check the :man:`getdents(2)` man page.
|
|
|
|
.. c:function:: int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
.. c:function:: int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
|
|
.. c:function:: int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`stat(2)`, :man:`fstat(2)` and :man:`lstat(2)` respectively.
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`rename(2)`.
|
|
|
|
.. c:function:: int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`fsync(2)`.
|
|
|
|
.. c:function:: int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`fdatasync(2)`.
|
|
|
|
.. c:function:: int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`ftruncate(2)`.
|
|
|
|
.. 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)
|
|
|
|
Limited equivalent to :man:`sendfile(2)`.
|
|
|
|
.. c:function:: int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`access(2)` on Unix. Windows uses ``GetFileAttributesW()``.
|
|
|
|
.. c:function:: int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb)
|
|
.. c:function:: int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`chmod(2)` and :man:`fchmod(2)` respectively.
|
|
|
|
.. 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)
|
|
.. 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)
|
|
|
|
Equivalent to :man:`utime(2)` and :man:`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``.
|
|
|
|
.. versionchanged:: 1.10.0 sub-second precission is supported on Windows
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`link(2)`.
|
|
|
|
.. 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)
|
|
|
|
Equivalent to :man:`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.
|
|
|
|
.. c:function:: int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`readlink(2)`.
|
|
|
|
.. c:function:: int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb)
|
|
|
|
Equivalent to :man:`realpath(3)` on Unix. Windows uses `GetFinalPathNameByHandle <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364962(v=vs.85).aspx>`_.
|
|
|
|
.. 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 <https://github.com/nodejs/node/issues/7726>`_.
|
|
|
|
.. note::
|
|
This function is not implemented on Windows XP and Windows Server 2003.
|
|
On these systems, UV_ENOSYS is returned.
|
|
|
|
.. versionadded:: 1.8.0
|
|
|
|
.. 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)
|
|
.. 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)
|
|
|
|
Equivalent to :man:`chown(2)` and :man:`fchown(2)` respectively.
|
|
|
|
.. note::
|
|
These functions are not implemented on Windows.
|
|
|
|
.. seealso:: The :c:type:`uv_req_t` API functions also apply.
|