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