1 2.. _fs: 3 4File system operations 5====================== 6 7libuv provides a wide variety of cross-platform sync and async file system 8operations. All functions defined in this document take a callback, which is 9allowed to be NULL. If the callback is NULL the request is completed synchronously, 10otherwise it will be performed asynchronously. 11 12All file operations are run on the threadpool. See :ref:`threadpool` for information 13on the threadpool size. 14 15Starting with libuv v1.45.0, some file operations on Linux are handed off to 16`io_uring <https://en.wikipedia.org/wiki/Io_uring>` when possible. Apart from 17a (sometimes significant) increase in throughput there should be no change in 18observable behavior. Libuv reverts to using its threadpool when the necessary 19kernel features are unavailable or unsuitable. 20 21.. note:: 22 On Windows `uv_fs_*` functions use utf-8 encoding. 23 24Data types 25---------- 26 27.. c:type:: uv_fs_t 28 29 File system request type. 30 31.. c:type:: uv_timespec_t 32 33 Y2K38-unsafe data type for storing times with nanosecond resolution. 34 Will be replaced with :c:type:`uv_timespec64_t` in libuv v2.0. 35 36 :: 37 38 typedef struct { 39 long tv_sec; 40 long tv_nsec; 41 } uv_timespec_t; 42 43.. c:type:: uv_stat_t 44 45 Portable equivalent of ``struct stat``. 46 47 :: 48 49 typedef struct { 50 uint64_t st_dev; 51 uint64_t st_mode; 52 uint64_t st_nlink; 53 uint64_t st_uid; 54 uint64_t st_gid; 55 uint64_t st_rdev; 56 uint64_t st_ino; 57 uint64_t st_size; 58 uint64_t st_blksize; 59 uint64_t st_blocks; 60 uint64_t st_flags; 61 uint64_t st_gen; 62 uv_timespec_t st_atim; 63 uv_timespec_t st_mtim; 64 uv_timespec_t st_ctim; 65 uv_timespec_t st_birthtim; 66 } uv_stat_t; 67 68.. c:enum:: uv_fs_type 69 70 File system request type. 71 72 :: 73 74 typedef enum { 75 UV_FS_UNKNOWN = -1, 76 UV_FS_CUSTOM, 77 UV_FS_OPEN, 78 UV_FS_CLOSE, 79 UV_FS_READ, 80 UV_FS_WRITE, 81 UV_FS_SENDFILE, 82 UV_FS_STAT, 83 UV_FS_LSTAT, 84 UV_FS_FSTAT, 85 UV_FS_FTRUNCATE, 86 UV_FS_UTIME, 87 UV_FS_FUTIME, 88 UV_FS_ACCESS, 89 UV_FS_CHMOD, 90 UV_FS_FCHMOD, 91 UV_FS_FSYNC, 92 UV_FS_FDATASYNC, 93 UV_FS_UNLINK, 94 UV_FS_RMDIR, 95 UV_FS_MKDIR, 96 UV_FS_MKDTEMP, 97 UV_FS_RENAME, 98 UV_FS_SCANDIR, 99 UV_FS_LINK, 100 UV_FS_SYMLINK, 101 UV_FS_READLINK, 102 UV_FS_CHOWN, 103 UV_FS_FCHOWN, 104 UV_FS_REALPATH, 105 UV_FS_COPYFILE, 106 UV_FS_LCHOWN, 107 UV_FS_OPENDIR, 108 UV_FS_READDIR, 109 UV_FS_CLOSEDIR, 110 UV_FS_MKSTEMP, 111 UV_FS_LUTIME 112 } uv_fs_type; 113 114.. c:type:: uv_statfs_t 115 116 Reduced cross platform equivalent of ``struct statfs``. 117 Used in :c:func:`uv_fs_statfs`. 118 119 :: 120 121 typedef struct uv_statfs_s { 122 uint64_t f_type; 123 uint64_t f_bsize; 124 uint64_t f_blocks; 125 uint64_t f_bfree; 126 uint64_t f_bavail; 127 uint64_t f_files; 128 uint64_t f_ffree; 129 uint64_t f_spare[4]; 130 } uv_statfs_t; 131 132.. c:enum:: uv_dirent_t 133 134 Cross platform (reduced) equivalent of ``struct dirent``. 135 Used in :c:func:`uv_fs_scandir_next`. 136 137 :: 138 139 typedef enum { 140 UV_DIRENT_UNKNOWN, 141 UV_DIRENT_FILE, 142 UV_DIRENT_DIR, 143 UV_DIRENT_LINK, 144 UV_DIRENT_FIFO, 145 UV_DIRENT_SOCKET, 146 UV_DIRENT_CHAR, 147 UV_DIRENT_BLOCK 148 } uv_dirent_type_t; 149 150 typedef struct uv_dirent_s { 151 const char* name; 152 uv_dirent_type_t type; 153 } uv_dirent_t; 154 155.. c:type:: uv_dir_t 156 157 Data type used for streaming directory iteration. 158 Used by :c:func:`uv_fs_opendir()`, :c:func:`uv_fs_readdir()`, and 159 :c:func:`uv_fs_closedir()`. `dirents` represents a user provided array of 160 `uv_dirent_t`s used to hold results. `nentries` is the user provided maximum 161 array size of `dirents`. 162 163 :: 164 165 typedef struct uv_dir_s { 166 uv_dirent_t* dirents; 167 size_t nentries; 168 } uv_dir_t; 169 170.. c:type:: void (*uv_fs_cb)(uv_fs_t* req) 171 172 Callback called when a request is completed asynchronously. 173 174 175Public members 176^^^^^^^^^^^^^^ 177 178.. c:member:: uv_loop_t* uv_fs_t.loop 179 180 Loop that started this request and where completion will be reported. 181 Readonly. 182 183.. c:member:: uv_fs_type uv_fs_t.fs_type 184 185 FS request type. 186 187.. c:member:: const char* uv_fs_t.path 188 189 Path affecting the request. 190 191.. c:member:: ssize_t uv_fs_t.result 192 193 Result of the request. < 0 means error, success otherwise. On requests such 194 as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of 195 data that was read or written, respectively. 196 197.. c:member:: uv_stat_t uv_fs_t.statbuf 198 199 Stores the result of :c:func:`uv_fs_stat` and other stat requests. 200 201.. c:member:: void* uv_fs_t.ptr 202 203 Stores the result of :c:func:`uv_fs_readlink` and 204 :c:func:`uv_fs_realpath` and serves as an alias to `statbuf`. 205 206.. seealso:: The :c:type:`uv_req_t` members also apply. 207 208 209API 210--- 211 212.. c:function:: void uv_fs_req_cleanup(uv_fs_t* req) 213 214 Cleanup request. Must be called after a request is finished to deallocate 215 any memory libuv might have allocated. 216 217.. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) 218 219 Equivalent to :man:`close(2)`. 220 221.. 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) 222 223 Equivalent to :man:`open(2)`. 224 225 .. note:: 226 On Windows libuv uses `CreateFileW` and thus the file is always opened 227 in binary mode. Because of this the O_BINARY and O_TEXT flags are not 228 supported. 229 230.. 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) 231 232 Equivalent to :man:`preadv(2)`. If the `offset` argument is `-1`, then 233 the current file offset is used and updated. 234 235 .. warning:: 236 On Windows, under non-MSVC environments (e.g. when GCC or Clang is used 237 to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal 238 crash if the memory mapped read operation fails. 239 240.. c:function:: int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 241 242 Equivalent to :man:`unlink(2)`. 243 244.. 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) 245 246 Equivalent to :man:`pwritev(2)`. If the `offset` argument is `-1`, then 247 the current file offset is used and updated. 248 249 .. warning:: 250 On Windows, under non-MSVC environments (e.g. when GCC or Clang is used 251 to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal 252 crash if the memory mapped write operation fails. 253 254.. c:function:: int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb) 255 256 Equivalent to :man:`mkdir(2)`. 257 258 .. note:: 259 `mode` is currently not implemented on Windows. 260 261.. c:function:: int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb) 262 263 Equivalent to :man:`mkdtemp(3)`. The result can be found as a null terminated string at `req->path`. 264 265.. c:function:: int uv_fs_mkstemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb) 266 267 Equivalent to :man:`mkstemp(3)`. The created file path can be found as a null terminated string at `req->path`. 268 The file descriptor can be found as an integer at `req->result`. 269 270 .. versionadded:: 1.34.0 271 272.. c:function:: int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 273 274 Equivalent to :man:`rmdir(2)`. 275 276.. c:function:: int uv_fs_opendir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 277 278 Opens `path` as a directory stream. On success, a `uv_dir_t` is allocated 279 and returned via `req->ptr`. This memory is not freed by 280 `uv_fs_req_cleanup()`, although `req->ptr` is set to `NULL`. The allocated 281 memory must be freed by calling `uv_fs_closedir()`. On failure, no memory 282 is allocated. 283 284 The contents of the directory can be iterated over by passing the resulting 285 `uv_dir_t` to `uv_fs_readdir()`. 286 287 .. versionadded:: 1.28.0 288 289.. c:function:: int uv_fs_closedir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb) 290 291 Closes the directory stream represented by `dir` and frees the memory 292 allocated by `uv_fs_opendir()`. 293 294 .. versionadded:: 1.28.0 295 296.. c:function:: int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb) 297 298 Iterates over the directory stream, `dir`, returned by a successful 299 `uv_fs_opendir()` call. Prior to invoking `uv_fs_readdir()`, the caller 300 must set `dir->dirents` and `dir->nentries`, representing the array of 301 :c:type:`uv_dirent_t` elements used to hold the read directory entries and 302 its size. 303 304 On success, the result is an integer >= 0 representing the number of entries 305 read from the stream. 306 307 .. versionadded:: 1.28.0 308 309 .. warning:: 310 `uv_fs_readdir()` is not thread safe. 311 312 .. note:: 313 This function does not return the "." and ".." entries. 314 315 .. note:: 316 On success this function allocates memory that must be freed using 317 `uv_fs_req_cleanup()`. `uv_fs_req_cleanup()` must be called before 318 closing the directory with `uv_fs_closedir()`. 319 320.. c:function:: int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb) 321.. c:function:: int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent) 322 323 Equivalent to :man:`scandir(3)`, with a slightly different API. Once the callback 324 for the request is called, the user can use :c:func:`uv_fs_scandir_next` to 325 get `ent` populated with the next directory entry data. When there are no 326 more entries ``UV_EOF`` will be returned. 327 328 .. note:: 329 Unlike `scandir(3)`, this function does not return the "." and ".." entries. 330 331 .. note:: 332 On Linux, getting the type of an entry is only supported by some file systems (btrfs, ext2, 333 ext3 and ext4 at the time of this writing), check the :man:`getdents(2)` man page. 334 335.. c:function:: int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 336.. c:function:: int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) 337.. c:function:: int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 338 339 Equivalent to :man:`stat(2)`, :man:`fstat(2)` and :man:`lstat(2)` respectively. 340 341.. c:function:: int uv_fs_statfs(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 342 343 Equivalent to :man:`statfs(2)`. On success, a `uv_statfs_t` is allocated 344 and returned via `req->ptr`. This memory is freed by `uv_fs_req_cleanup()`. 345 346 .. note:: 347 Any fields in the resulting `uv_statfs_t` that are not supported by the 348 underlying operating system are set to zero. 349 350 .. versionadded:: 1.31.0 351 352.. 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) 353 354 Equivalent to :man:`rename(2)`. 355 356.. c:function:: int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) 357 358 Equivalent to :man:`fsync(2)`. 359 360 .. note:: 361 For AIX, `uv_fs_fsync` returns `UV_EBADF` on file descriptors referencing 362 non regular files. 363 364.. c:function:: int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) 365 366 Equivalent to :man:`fdatasync(2)`. 367 368.. c:function:: int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb) 369 370 Equivalent to :man:`ftruncate(2)`. 371 372.. 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) 373 374 Copies a file from `path` to `new_path`. Supported `flags` are described below. 375 376 - `UV_FS_COPYFILE_EXCL`: If present, `uv_fs_copyfile()` will fail with 377 `UV_EEXIST` if the destination path already exists. The default behavior 378 is to overwrite the destination if it exists. 379 - `UV_FS_COPYFILE_FICLONE`: If present, `uv_fs_copyfile()` will attempt to 380 create a copy-on-write reflink. If the underlying platform does not 381 support copy-on-write, or an error occurs while attempting to use 382 copy-on-write, a fallback copy mechanism based on 383 :c:func:`uv_fs_sendfile()` is used. 384 - `UV_FS_COPYFILE_FICLONE_FORCE`: If present, `uv_fs_copyfile()` will 385 attempt to create a copy-on-write reflink. If the underlying platform does 386 not support copy-on-write, or an error occurs while attempting to use 387 copy-on-write, then an error is returned. 388 389 .. warning:: 390 If the destination path is created, but an error occurs while copying 391 the data, then the destination path is removed. There is a brief window 392 of time between closing and removing the file where another process 393 could access the file. 394 395 .. versionadded:: 1.14.0 396 397 .. versionchanged:: 1.20.0 `UV_FS_COPYFILE_FICLONE` and 398 `UV_FS_COPYFILE_FICLONE_FORCE` are supported. 399 400 .. versionchanged:: 1.33.0 If an error occurs while using 401 `UV_FS_COPYFILE_FICLONE_FORCE`, that error is returned. Previously, 402 all errors were mapped to `UV_ENOTSUP`. 403 404.. 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) 405 406 Limited equivalent to :man:`sendfile(2)`. 407 408.. c:function:: int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb) 409 410 Equivalent to :man:`access(2)` on Unix. Windows uses ``GetFileAttributesW()``. 411 412.. c:function:: int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb) 413.. c:function:: int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb) 414 415 Equivalent to :man:`chmod(2)` and :man:`fchmod(2)` respectively. 416 417.. 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) 418.. 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) 419.. 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) 420 421 Equivalent to :man:`utime(2)`, :man:`futimes(3)` and :man:`lutimes(3)` respectively. 422 423 .. note:: 424 z/OS: `uv_fs_lutime()` is not implemented for z/OS. It can still be called but will return 425 ``UV_ENOSYS``. 426 427 .. note:: 428 AIX: `uv_fs_futime()` and `uv_fs_lutime()` functions only work for AIX 7.1 and newer. 429 They can still be called on older versions but will return ``UV_ENOSYS``. 430 431 .. versionchanged:: 1.10.0 sub-second precission is supported on Windows 432 433.. 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) 434 435 Equivalent to :man:`link(2)`. 436 437.. 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) 438 439 Equivalent to :man:`symlink(2)`. 440 441 .. note:: 442 On Windows the `flags` parameter can be specified to control how the symlink will 443 be created: 444 445 * ``UV_FS_SYMLINK_DIR``: indicates that `path` points to a directory. 446 447 * ``UV_FS_SYMLINK_JUNCTION``: request that the symlink is created 448 using junction points. 449 450.. c:function:: int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 451 452 Equivalent to :man:`readlink(2)`. 453 The resulting string is stored in `req->ptr`. 454 455.. c:function:: int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb) 456 457 Equivalent to :man:`realpath(3)` on Unix. Windows uses `GetFinalPathNameByHandle <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlea>`_. 458 The resulting string is stored in `req->ptr`. 459 460 .. warning:: 461 This function has certain platform-specific caveats that were discovered when used in Node. 462 463 * macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are 464 found while resolving the given path. This limit is hardcoded and cannot be sidestepped. 465 * Windows: while this function works in the common case, there are a number of corner cases 466 where it doesn't: 467 468 - Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) 469 cannot be resolved. 470 - Inconsistent casing when using drive letters. 471 - Resolved path bypasses subst'd drives. 472 473 While this function can still be used, it's not recommended if scenarios such as the 474 above need to be supported. 475 476 The background story and some more details on these issues can be checked 477 `here <https://github.com/nodejs/node/issues/7726>`_. 478 479 .. versionadded:: 1.8.0 480 481.. 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) 482.. 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) 483.. 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) 484 485 Equivalent to :man:`chown(2)`, :man:`fchown(2)` and :man:`lchown(2)` respectively. 486 487 .. note:: 488 These functions are not implemented on Windows. 489 490 .. versionchanged:: 1.21.0 implemented uv_fs_lchown 491 492.. c:function:: uv_fs_type uv_fs_get_type(const uv_fs_t* req) 493 494 Returns `req->fs_type`. 495 496 .. versionadded:: 1.19.0 497 498.. c:function:: ssize_t uv_fs_get_result(const uv_fs_t* req) 499 500 Returns `req->result`. 501 502 .. versionadded:: 1.19.0 503 504.. c:function:: int uv_fs_get_system_error(const uv_fs_t* req) 505 506 Returns the platform specific error code - `GetLastError()` value on Windows 507 and `-(req->result)` on other platforms. 508 509 .. versionadded:: 1.38.0 510 511.. c:function:: void* uv_fs_get_ptr(const uv_fs_t* req) 512 513 Returns `req->ptr`. 514 515 .. versionadded:: 1.19.0 516 517.. c:function:: const char* uv_fs_get_path(const uv_fs_t* req) 518 519 Returns `req->path`. 520 521 .. versionadded:: 1.19.0 522 523.. c:function:: uv_stat_t* uv_fs_get_statbuf(uv_fs_t* req) 524 525 Returns `&req->statbuf`. 526 527 .. versionadded:: 1.19.0 528 529.. seealso:: The :c:type:`uv_req_t` API functions also apply. 530 531Helper functions 532---------------- 533 534.. c:function:: uv_os_fd_t uv_get_osfhandle(int fd) 535 536 For a file descriptor in the C runtime, get the OS-dependent handle. 537 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>`_. 538 Note that the return value is still owned by the C runtime, 539 any attempts to close it or to use it after closing the fd may lead to malfunction. 540 541 .. versionadded:: 1.12.0 542 543.. c:function:: int uv_open_osfhandle(uv_os_fd_t os_fd) 544 545 For a OS-dependent handle, get the file descriptor in the C runtime. 546 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>`_. 547 Note that this consumes the argument, any attempts to close it or to use it 548 after closing the return value may lead to malfunction. 549 550 .. versionadded:: 1.23.0 551 552File open constants 553------------------- 554 555.. c:macro:: UV_FS_O_APPEND 556 557 The file is opened in append mode. Before each write, the file offset is 558 positioned at the end of the file. 559 560.. c:macro:: UV_FS_O_CREAT 561 562 The file is created if it does not already exist. 563 564.. c:macro:: UV_FS_O_DIRECT 565 566 File I/O is done directly to and from user-space buffers, which must be 567 aligned. Buffer size and address should be a multiple of the physical sector 568 size of the block device. 569 570 .. note:: 571 `UV_FS_O_DIRECT` is supported on Linux, and on Windows via 572 `FILE_FLAG_NO_BUFFERING <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_. 573 `UV_FS_O_DIRECT` is not supported on macOS. 574 575.. c:macro:: UV_FS_O_DIRECTORY 576 577 If the path is not a directory, fail the open. 578 579 .. note:: 580 `UV_FS_O_DIRECTORY` is not supported on Windows. 581 582.. c:macro:: UV_FS_O_DSYNC 583 584 The file is opened for synchronous I/O. Write operations will complete once 585 all data and a minimum of metadata are flushed to disk. 586 587 .. note:: 588 `UV_FS_O_DSYNC` is supported on Windows via 589 `FILE_FLAG_WRITE_THROUGH <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_. 590 591.. c:macro:: UV_FS_O_EXCL 592 593 If the `O_CREAT` flag is set and the file already exists, fail the open. 594 595 .. note:: 596 In general, the behavior of `O_EXCL` is undefined if it is used without 597 `O_CREAT`. There is one exception: on Linux 2.6 and later, `O_EXCL` can 598 be used without `O_CREAT` if pathname refers to a block device. If the 599 block device is in use by the system (e.g., mounted), the open will fail 600 with the error `EBUSY`. 601 602.. c:macro:: UV_FS_O_EXLOCK 603 604 Atomically obtain an exclusive lock. 605 606 .. note:: 607 `UV_FS_O_EXLOCK` is only supported on macOS and Windows. 608 609 .. versionchanged:: 1.17.0 support is added for Windows. 610 611.. c:macro:: UV_FS_O_FILEMAP 612 613 Use a memory file mapping to access the file. When using this flag, the 614 file cannot be open multiple times concurrently. 615 616 .. note:: 617 `UV_FS_O_FILEMAP` is only supported on Windows. 618 619.. c:macro:: UV_FS_O_NOATIME 620 621 Do not update the file access time when the file is read. 622 623 .. note:: 624 `UV_FS_O_NOATIME` is not supported on Windows. 625 626.. c:macro:: UV_FS_O_NOCTTY 627 628 If the path identifies a terminal device, opening the path will not cause 629 that terminal to become the controlling terminal for the process (if the 630 process does not already have one). 631 632 .. note:: 633 `UV_FS_O_NOCTTY` is not supported on Windows. 634 635.. c:macro:: UV_FS_O_NOFOLLOW 636 637 If the path is a symbolic link, fail the open. 638 639 .. note:: 640 `UV_FS_O_NOFOLLOW` is not supported on Windows. 641 642.. c:macro:: UV_FS_O_NONBLOCK 643 644 Open the file in nonblocking mode if possible. 645 646 .. note:: 647 `UV_FS_O_NONBLOCK` is not supported on Windows. 648 649.. c:macro:: UV_FS_O_RANDOM 650 651 Access is intended to be random. The system can use this as a hint to 652 optimize file caching. 653 654 .. note:: 655 `UV_FS_O_RANDOM` is only supported on Windows via 656 `FILE_FLAG_RANDOM_ACCESS <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_. 657 658.. c:macro:: UV_FS_O_RDONLY 659 660 Open the file for read-only access. 661 662.. c:macro:: UV_FS_O_RDWR 663 664 Open the file for read-write access. 665 666.. c:macro:: UV_FS_O_SEQUENTIAL 667 668 Access is intended to be sequential from beginning to end. The system can 669 use this as a hint to optimize file caching. 670 671 .. note:: 672 `UV_FS_O_SEQUENTIAL` is only supported on Windows via 673 `FILE_FLAG_SEQUENTIAL_SCAN <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_. 674 675.. c:macro:: UV_FS_O_SHORT_LIVED 676 677 The file is temporary and should not be flushed to disk if possible. 678 679 .. note:: 680 `UV_FS_O_SHORT_LIVED` is only supported on Windows via 681 `FILE_ATTRIBUTE_TEMPORARY <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_. 682 683.. c:macro:: UV_FS_O_SYMLINK 684 685 Open the symbolic link itself rather than the resource it points to. 686 687.. c:macro:: UV_FS_O_SYNC 688 689 The file is opened for synchronous I/O. Write operations will complete once 690 all data and all metadata are flushed to disk. 691 692 .. note:: 693 `UV_FS_O_SYNC` is supported on Windows via 694 `FILE_FLAG_WRITE_THROUGH <https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering>`_. 695 696.. c:macro:: UV_FS_O_TEMPORARY 697 698 The file is temporary and should not be flushed to disk if possible. 699 700 .. note:: 701 `UV_FS_O_TEMPORARY` is only supported on Windows via 702 `FILE_ATTRIBUTE_TEMPORARY <https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea>`_. 703 704.. c:macro:: UV_FS_O_TRUNC 705 706 If the file exists and is a regular file, and the file is opened 707 successfully for write access, its length shall be truncated to zero. 708 709.. c:macro:: UV_FS_O_WRONLY 710 711 Open the file for write-only access. 712