Skip to content

Commit 5ecd82d

Browse files
cjihrigtargos
authored andcommitted
fs: expose copy-on-write flags for fs.copyFile()
This commit exposes the UV_FS_COPYFILE_FICLONE and UV_FS_COPYFILE_FICLONE_FORCE flags added in libuv 1.20.0. Fixes: #19152 PR-URL: #19759 Fixes: #19152 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Santiago Gimeno <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 09090e7 commit 5ecd82d

File tree

4 files changed

+96
-7
lines changed

4 files changed

+96
-7
lines changed

doc/api/fs.md

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1159,8 +1159,18 @@ operation. If an error occurs after the destination file has been opened for
11591159
writing, Node.js will attempt to remove the destination.
11601160

11611161
`flags` is an optional integer that specifies the behavior
1162-
of the copy operation. The only supported flag is `fs.constants.COPYFILE_EXCL`,
1163-
which causes the copy operation to fail if `dest` already exists.
1162+
of the copy operation. It is possible to create a mask consisting of the bitwise
1163+
OR of two or more values (e.g.
1164+
`fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`).
1165+
1166+
* `fs.constants.COPYFILE_EXCL` - The copy operation will fail if `dest` already
1167+
exists.
1168+
* `fs.constants.COPYFILE_FICLONE` - The copy operation will attempt to create a
1169+
copy-on-write reflink. If the platform does not support copy-on-write, then a
1170+
fallback copy mechanism is used.
1171+
* `fs.constants.COPYFILE_FICLONE_FORCE` - The copy operation will attempt to
1172+
create a copy-on-write reflink. If the platform does not support copy-on-write,
1173+
then the operation will fail.
11641174

11651175
Example:
11661176

@@ -1200,8 +1210,18 @@ atomicity of the copy operation. If an error occurs after the destination file
12001210
has been opened for writing, Node.js will attempt to remove the destination.
12011211

12021212
`flags` is an optional integer that specifies the behavior
1203-
of the copy operation. The only supported flag is `fs.constants.COPYFILE_EXCL`,
1204-
which causes the copy operation to fail if `dest` already exists.
1213+
of the copy operation. It is possible to create a mask consisting of the bitwise
1214+
OR of two or more values (e.g.
1215+
`fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE`).
1216+
1217+
* `fs.constants.COPYFILE_EXCL` - The copy operation will fail if `dest` already
1218+
exists.
1219+
* `fs.constants.COPYFILE_FICLONE` - The copy operation will attempt to create a
1220+
copy-on-write reflink. If the platform does not support copy-on-write, then a
1221+
fallback copy mechanism is used.
1222+
* `fs.constants.COPYFILE_FICLONE_FORCE` - The copy operation will attempt to
1223+
create a copy-on-write reflink. If the platform does not support copy-on-write,
1224+
then the operation will fail.
12051225

12061226
Example:
12071227

@@ -3336,6 +3356,34 @@ The following constants are meant for use with [`fs.access()`][].
33363356
</tr>
33373357
</table>
33383358

3359+
### File Copy Constants
3360+
3361+
The following constants are meant for use with [`fs.copyFile()`][].
3362+
3363+
<table>
3364+
<tr>
3365+
<th>Constant</th>
3366+
<th>Description</th>
3367+
</tr>
3368+
<tr>
3369+
<td><code>COPYFILE_EXCL</code></td>
3370+
<td>If present, the copy operation will fail with an error if the
3371+
destination path already exists.</td>
3372+
</tr>
3373+
<tr>
3374+
<td><code>COPYFILE_FICLONE</code></td>
3375+
<td>If present, the copy operation will attempt to create a
3376+
copy-on-write reflink. If the underlying platform does not support
3377+
copy-on-write, then a fallback copy mechanism is used.</td>
3378+
</tr>
3379+
<tr>
3380+
<td><code>COPYFILE_FICLONE_FORCE</code></td>
3381+
<td>If present, the copy operation will attempt to create a
3382+
copy-on-write reflink. If the underlying platform does not support
3383+
copy-on-write, then the operation will fail with an error.</td>
3384+
</tr>
3385+
</table>
3386+
33393387
### File Open Constants
33403388

33413389
The following constants are meant for use with `fs.open()`.

lib/fs.js

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1920,7 +1920,15 @@ fs.mkdtempSync = function(prefix, options) {
19201920

19211921
// Define copyFile() flags.
19221922
Object.defineProperties(fs.constants, {
1923-
COPYFILE_EXCL: { enumerable: true, value: constants.UV_FS_COPYFILE_EXCL }
1923+
COPYFILE_EXCL: { enumerable: true, value: constants.UV_FS_COPYFILE_EXCL },
1924+
COPYFILE_FICLONE: {
1925+
enumerable: true,
1926+
value: constants.UV_FS_COPYFILE_FICLONE
1927+
},
1928+
COPYFILE_FICLONE_FORCE: {
1929+
enumerable: true,
1930+
value: constants.UV_FS_COPYFILE_FICLONE_FORCE
1931+
}
19241932
});
19251933

19261934

src/node_constants.cc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1317,6 +1317,8 @@ void DefineConstants(v8::Isolate* isolate, Local<Object> target) {
13171317
// Define libuv constants.
13181318
NODE_DEFINE_CONSTANT(os_constants, UV_UDP_REUSEADDR);
13191319
NODE_DEFINE_CONSTANT(fs_constants, UV_FS_COPYFILE_EXCL);
1320+
NODE_DEFINE_CONSTANT(fs_constants, UV_FS_COPYFILE_FICLONE);
1321+
NODE_DEFINE_CONSTANT(fs_constants, UV_FS_COPYFILE_FICLONE_FORCE);
13201322

13211323
os_constants->Set(OneByteString(isolate, "dlopen"), dlopen_constants);
13221324
os_constants->Set(OneByteString(isolate, "errno"), err_constants);

test/parallel/test-fs-copyfile.js

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,14 @@ const fs = require('fs');
77
const path = require('path');
88
const src = fixtures.path('a.js');
99
const dest = path.join(tmpdir.path, 'copyfile.out');
10-
const { COPYFILE_EXCL, UV_FS_COPYFILE_EXCL } = fs.constants;
10+
const {
11+
COPYFILE_EXCL,
12+
COPYFILE_FICLONE,
13+
COPYFILE_FICLONE_FORCE,
14+
UV_FS_COPYFILE_EXCL,
15+
UV_FS_COPYFILE_FICLONE,
16+
UV_FS_COPYFILE_FICLONE_FORCE
17+
} = fs.constants;
1118

1219
function verify(src, dest) {
1320
const srcData = fs.readFileSync(src, 'utf8');
@@ -24,8 +31,14 @@ tmpdir.refresh();
2431

2532
// Verify that flags are defined.
2633
assert.strictEqual(typeof COPYFILE_EXCL, 'number');
34+
assert.strictEqual(typeof COPYFILE_FICLONE, 'number');
35+
assert.strictEqual(typeof COPYFILE_FICLONE_FORCE, 'number');
2736
assert.strictEqual(typeof UV_FS_COPYFILE_EXCL, 'number');
37+
assert.strictEqual(typeof UV_FS_COPYFILE_FICLONE, 'number');
38+
assert.strictEqual(typeof UV_FS_COPYFILE_FICLONE_FORCE, 'number');
2839
assert.strictEqual(COPYFILE_EXCL, UV_FS_COPYFILE_EXCL);
40+
assert.strictEqual(COPYFILE_FICLONE, UV_FS_COPYFILE_FICLONE);
41+
assert.strictEqual(COPYFILE_FICLONE_FORCE, UV_FS_COPYFILE_FICLONE_FORCE);
2942

3043
// Verify that files are overwritten when no flags are provided.
3144
fs.writeFileSync(dest, '', 'utf8');
@@ -47,8 +60,26 @@ assert.throws(() => {
4760
fs.copyFileSync(`${src}__does_not_exist`, dest, COPYFILE_EXCL);
4861
}, /^Error: ENOENT: no such file or directory, copyfile/);
4962

50-
// Copies asynchronously.
63+
// Verify that UV_FS_COPYFILE_FICLONE can be used.
5164
fs.unlinkSync(dest);
65+
fs.copyFileSync(src, dest, UV_FS_COPYFILE_FICLONE);
66+
verify(src, dest);
67+
68+
// Verify that COPYFILE_FICLONE_FORCE can be used.
69+
try {
70+
fs.unlinkSync(dest);
71+
fs.copyFileSync(src, dest, COPYFILE_FICLONE_FORCE);
72+
verify(src, dest);
73+
} catch (err) {
74+
assert.strictEqual(err.syscall, 'copyfile');
75+
assert(err.code === 'ENOTSUP' || err.code === 'ENOTTY' ||
76+
err.code === 'ENOSYS');
77+
assert.strictEqual(err.path, src);
78+
assert.strictEqual(err.dest, dest);
79+
}
80+
81+
// Copies asynchronously.
82+
tmpdir.refresh(); // Don't use unlinkSync() since the last test may fail.
5283
fs.copyFile(src, dest, common.mustCall((err) => {
5384
assert.ifError(err);
5485
verify(src, dest);

0 commit comments

Comments
 (0)