diff --git a/doc/api/fs.md b/doc/api/fs.md index 2613419df17f9b..ce05469881bf42 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -750,6 +750,88 @@ Returns an object containing commonly used constants for file system operations. The specific constants currently defined are described in [FS Constants][]. +## fs.copyFile(src, dest[, flags], callback) + + +* `src` {string|Buffer|URL} source filename to copy +* `dest` {string|Buffer|URL} destination filename of the copy operation +* `flags` {number} modifiers for copy operation. **Default:** `0` +* `callback` {Function} + +Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it +already exists. No arguments other than a possible exception are given to the +callback function. Node.js makes no guarantees about the atomicity of the copy +operation. If an error occurs after the destination file has been opened for +writing, Node.js will attempt to remove the destination. + +`flags` is an optional integer that specifies the behavior +of the copy operation. The only supported flag is `fs.constants.COPYFILE_EXCL`, +which causes the copy operation to fail if `dest` already exists. + +Example: + +```js +const fs = require('fs'); + +// destination.txt will be created or overwritten by default. +fs.copyFile('source.txt', 'destination.txt', (err) => { + if (err) throw err; + console.log('source.txt was copied to destination.txt'); +}); +``` + +If the third argument is a number, then it specifies `flags`, as shown in the +following example. + +```js +const fs = require('fs'); +const { COPYFILE_EXCL } = fs.constants; + +// By using COPYFILE_EXCL, the operation will fail if destination.txt exists. +fs.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL, callback); +``` + +## fs.copyFileSync(src, dest[, flags]) + + +* `src` {string|Buffer|URL} source filename to copy +* `dest` {string|Buffer|URL} destination filename of the copy operation +* `flags` {number} modifiers for copy operation. **Default:** `0` + +Synchronously copies `src` to `dest`. By default, `dest` is overwritten if it +already exists. Returns `undefined`. Node.js makes no guarantees about the +atomicity of the copy operation. If an error occurs after the destination file +has been opened for writing, Node.js will attempt to remove the destination. + +`flags` is an optional integer that specifies the behavior +of the copy operation. The only supported flag is `fs.constants.COPYFILE_EXCL`, +which causes the copy operation to fail if `dest` already exists. + +Example: + +```js +const fs = require('fs'); + +// destination.txt will be created or overwritten by default. +fs.copyFileSync('source.txt', 'destination.txt'); +console.log('source.txt was copied to destination.txt'); +``` + +If the third argument is a number, then it specifies `flags`, as shown in the +following example. + +```js +const fs = require('fs'); +const { COPYFILE_EXCL } = fs.constants; + +// By using COPYFILE_EXCL, the operation will fail if destination.txt exists. +fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL); +``` + ## fs.createReadStream(path[, options])