5883 lines
427 KiB
HTML
5883 lines
427 KiB
HTML
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width">
|
||
<meta name="nodejs.org:node-version" content="v12.22.12">
|
||
<title>File system | Node.js v12.22.12 Documentation</title>
|
||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
|
||
<link rel="stylesheet" href="assets/style.css">
|
||
<link rel="stylesheet" href="assets/hljs.css">
|
||
<link rel="canonical" href="https://nodejs.org/api/fs.html">
|
||
</head>
|
||
<body class="alt apidoc" id="api-section-fs">
|
||
<div id="content" class="clearfix">
|
||
<div id="column2" class="interior">
|
||
<div id="intro" class="interior">
|
||
<a href="/" title="Go back to the home page">
|
||
Node.js
|
||
</a>
|
||
</div>
|
||
<ul>
|
||
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
|
||
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
|
||
</ul>
|
||
<hr class="line">
|
||
<ul>
|
||
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
|
||
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
|
||
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
|
||
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
|
||
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
|
||
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
|
||
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
|
||
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
|
||
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
|
||
<li><a href="console.html" class="nav-console">Console</a></li>
|
||
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
|
||
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
|
||
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
|
||
<li><a href="dns.html" class="nav-dns">DNS</a></li>
|
||
<li><a href="domain.html" class="nav-domain">Domain</a></li>
|
||
<li><a href="errors.html" class="nav-errors">Errors</a></li>
|
||
<li><a href="events.html" class="nav-events">Events</a></li>
|
||
<li><a href="fs.html" class="nav-fs active">File system</a></li>
|
||
<li><a href="globals.html" class="nav-globals">Globals</a></li>
|
||
<li><a href="http.html" class="nav-http">HTTP</a></li>
|
||
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
|
||
<li><a href="https.html" class="nav-https">HTTPS</a></li>
|
||
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
|
||
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
|
||
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
|
||
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
|
||
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
|
||
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
|
||
<li><a href="net.html" class="nav-net">Net</a></li>
|
||
<li><a href="os.html" class="nav-os">OS</a></li>
|
||
<li><a href="path.html" class="nav-path">Path</a></li>
|
||
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
|
||
<li><a href="policy.html" class="nav-policy">Policies</a></li>
|
||
<li><a href="process.html" class="nav-process">Process</a></li>
|
||
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
|
||
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
|
||
<li><a href="readline.html" class="nav-readline">Readline</a></li>
|
||
<li><a href="repl.html" class="nav-repl">REPL</a></li>
|
||
<li><a href="report.html" class="nav-report">Report</a></li>
|
||
<li><a href="stream.html" class="nav-stream">Stream</a></li>
|
||
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
|
||
<li><a href="timers.html" class="nav-timers">Timers</a></li>
|
||
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
|
||
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
|
||
<li><a href="tty.html" class="nav-tty">TTY</a></li>
|
||
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
|
||
<li><a href="url.html" class="nav-url">URL</a></li>
|
||
<li><a href="util.html" class="nav-util">Utilities</a></li>
|
||
<li><a href="v8.html" class="nav-v8">V8</a></li>
|
||
<li><a href="vm.html" class="nav-vm">VM</a></li>
|
||
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
|
||
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
|
||
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
|
||
</ul>
|
||
<hr class="line">
|
||
<ul>
|
||
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div id="column1" data-id="fs" class="interior">
|
||
<header>
|
||
<h1>Node.js v12.22.12 Documentation</h1>
|
||
<div id="gtoc">
|
||
<ul>
|
||
<li>
|
||
<a href="index.html">Index</a>
|
||
</li>
|
||
<li>
|
||
<a href="all.html">View on single page</a>
|
||
</li>
|
||
<li>
|
||
<a href="fs.json">View as JSON</a>
|
||
</li>
|
||
|
||
<li class="version-picker">
|
||
<a href="#">View another version <span>▼</span></a>
|
||
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/fs.html">17.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v16.x/api/fs.html">16.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v15.x/api/fs.html">15.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v14.x/api/fs.html">14.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v13.x/api/fs.html">13.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v12.x/api/fs.html">12.x <b>LTS</b></a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v11.x/api/fs.html">11.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v10.x/api/fs.html">10.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v9.x/api/fs.html">9.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v8.x/api/fs.html">8.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v7.x/api/fs.html">7.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v6.x/api/fs.html">6.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v5.x/api/fs.html">5.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v4.x/api/fs.html">4.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/fs.html">0.12.x</a></li>
|
||
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/fs.html">0.10.x</a></li></ol>
|
||
</li>
|
||
|
||
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/fs.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
|
||
</ul>
|
||
</div>
|
||
<hr>
|
||
</header>
|
||
|
||
<div id="toc">
|
||
<h2>Table of Contents</h2>
|
||
<ul>
|
||
<li><span class="stability_2"><a href="#fs_file_system">File system</a></span>
|
||
<ul>
|
||
<li><a href="#fs_synchronous_example">Synchronous example</a></li>
|
||
<li><a href="#fs_callback_example">Callback example</a></li>
|
||
<li><a href="#fs_promise_example">Promise example</a></li>
|
||
<li><a href="#fs_ordering_of_callback_and_promise_based_operations">Ordering of callback and promise-based operations</a></li>
|
||
<li><a href="#fs_file_paths">File paths</a>
|
||
<ul>
|
||
<li><a href="#fs_url_object_support">URL object support</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_file_descriptors">File descriptors</a></li>
|
||
<li><a href="#fs_threadpool_usage">Threadpool usage</a></li>
|
||
<li><a href="#fs_class_fs_dir">Class: <code>fs.Dir</code></a>
|
||
<ul>
|
||
<li><a href="#fs_dir_close"><code>dir.close()</code></a></li>
|
||
<li><a href="#fs_dir_close_callback"><code>dir.close(callback)</code></a></li>
|
||
<li><a href="#fs_dir_closesync"><code>dir.closeSync()</code></a></li>
|
||
<li><a href="#fs_dir_path"><code>dir.path</code></a></li>
|
||
<li><a href="#fs_dir_read"><code>dir.read()</code></a></li>
|
||
<li><a href="#fs_dir_read_callback"><code>dir.read(callback)</code></a></li>
|
||
<li><a href="#fs_dir_readsync"><code>dir.readSync()</code></a></li>
|
||
<li><a href="#fs_dir_symbol_asynciterator"><code>dir[Symbol.asyncIterator]()</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_dirent">Class: <code>fs.Dirent</code></a>
|
||
<ul>
|
||
<li><a href="#fs_dirent_isblockdevice"><code>dirent.isBlockDevice()</code></a></li>
|
||
<li><a href="#fs_dirent_ischaracterdevice"><code>dirent.isCharacterDevice()</code></a></li>
|
||
<li><a href="#fs_dirent_isdirectory"><code>dirent.isDirectory()</code></a></li>
|
||
<li><a href="#fs_dirent_isfifo"><code>dirent.isFIFO()</code></a></li>
|
||
<li><a href="#fs_dirent_isfile"><code>dirent.isFile()</code></a></li>
|
||
<li><a href="#fs_dirent_issocket"><code>dirent.isSocket()</code></a></li>
|
||
<li><a href="#fs_dirent_issymboliclink"><code>dirent.isSymbolicLink()</code></a></li>
|
||
<li><a href="#fs_dirent_name"><code>dirent.name</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_fswatcher">Class: <code>fs.FSWatcher</code></a>
|
||
<ul>
|
||
<li><a href="#fs_event_change">Event: <code>'change'</code></a></li>
|
||
<li><a href="#fs_event_close">Event: <code>'close'</code></a></li>
|
||
<li><a href="#fs_event_error">Event: <code>'error'</code></a></li>
|
||
<li><a href="#fs_watcher_close"><code>watcher.close()</code></a></li>
|
||
<li><a href="#fs_watcher_ref"><code>watcher.ref()</code></a></li>
|
||
<li><a href="#fs_watcher_unref"><code>watcher.unref()</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_statwatcher">Class: <code>fs.StatWatcher</code></a>
|
||
<ul>
|
||
<li><a href="#fs_watcher_ref_1"><code>watcher.ref()</code></a></li>
|
||
<li><a href="#fs_watcher_unref_1"><code>watcher.unref()</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_readstream">Class: <code>fs.ReadStream</code></a>
|
||
<ul>
|
||
<li><a href="#fs_event_close_1">Event: <code>'close'</code></a></li>
|
||
<li><a href="#fs_event_open">Event: <code>'open'</code></a></li>
|
||
<li><a href="#fs_event_ready">Event: <code>'ready'</code></a></li>
|
||
<li><a href="#fs_readstream_bytesread"><code>readStream.bytesRead</code></a></li>
|
||
<li><a href="#fs_readstream_path"><code>readStream.path</code></a></li>
|
||
<li><a href="#fs_readstream_pending"><code>readStream.pending</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_stats">Class: <code>fs.Stats</code></a>
|
||
<ul>
|
||
<li><a href="#fs_stats_isblockdevice"><code>stats.isBlockDevice()</code></a></li>
|
||
<li><a href="#fs_stats_ischaracterdevice"><code>stats.isCharacterDevice()</code></a></li>
|
||
<li><a href="#fs_stats_isdirectory"><code>stats.isDirectory()</code></a></li>
|
||
<li><a href="#fs_stats_isfifo"><code>stats.isFIFO()</code></a></li>
|
||
<li><a href="#fs_stats_isfile"><code>stats.isFile()</code></a></li>
|
||
<li><a href="#fs_stats_issocket"><code>stats.isSocket()</code></a></li>
|
||
<li><a href="#fs_stats_issymboliclink"><code>stats.isSymbolicLink()</code></a></li>
|
||
<li><a href="#fs_stats_dev"><code>stats.dev</code></a></li>
|
||
<li><a href="#fs_stats_ino"><code>stats.ino</code></a></li>
|
||
<li><a href="#fs_stats_mode"><code>stats.mode</code></a></li>
|
||
<li><a href="#fs_stats_nlink"><code>stats.nlink</code></a></li>
|
||
<li><a href="#fs_stats_uid"><code>stats.uid</code></a></li>
|
||
<li><a href="#fs_stats_gid"><code>stats.gid</code></a></li>
|
||
<li><a href="#fs_stats_rdev"><code>stats.rdev</code></a></li>
|
||
<li><a href="#fs_stats_size"><code>stats.size</code></a></li>
|
||
<li><a href="#fs_stats_blksize"><code>stats.blksize</code></a></li>
|
||
<li><a href="#fs_stats_blocks"><code>stats.blocks</code></a></li>
|
||
<li><a href="#fs_stats_atimems"><code>stats.atimeMs</code></a></li>
|
||
<li><a href="#fs_stats_mtimems"><code>stats.mtimeMs</code></a></li>
|
||
<li><a href="#fs_stats_ctimems"><code>stats.ctimeMs</code></a></li>
|
||
<li><a href="#fs_stats_birthtimems"><code>stats.birthtimeMs</code></a></li>
|
||
<li><a href="#fs_stats_atimens"><code>stats.atimeNs</code></a></li>
|
||
<li><a href="#fs_stats_mtimens"><code>stats.mtimeNs</code></a></li>
|
||
<li><a href="#fs_stats_ctimens"><code>stats.ctimeNs</code></a></li>
|
||
<li><a href="#fs_stats_birthtimens"><code>stats.birthtimeNs</code></a></li>
|
||
<li><a href="#fs_stats_atime"><code>stats.atime</code></a></li>
|
||
<li><a href="#fs_stats_mtime"><code>stats.mtime</code></a></li>
|
||
<li><a href="#fs_stats_ctime"><code>stats.ctime</code></a></li>
|
||
<li><a href="#fs_stats_birthtime"><code>stats.birthtime</code></a></li>
|
||
<li><a href="#fs_stat_time_values">Stat time values</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_class_fs_writestream">Class: <code>fs.WriteStream</code></a>
|
||
<ul>
|
||
<li><a href="#fs_event_close_2">Event: <code>'close'</code></a></li>
|
||
<li><a href="#fs_event_open_1">Event: <code>'open'</code></a></li>
|
||
<li><a href="#fs_event_ready_1">Event: <code>'ready'</code></a></li>
|
||
<li><a href="#fs_writestream_byteswritten"><code>writeStream.bytesWritten</code></a></li>
|
||
<li><a href="#fs_writestream_path"><code>writeStream.path</code></a></li>
|
||
<li><a href="#fs_writestream_pending"><code>writeStream.pending</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_access_path_mode_callback"><code>fs.access(path[, mode], callback)</code></a></li>
|
||
<li><a href="#fs_fs_accesssync_path_mode"><code>fs.accessSync(path[, mode])</code></a></li>
|
||
<li><a href="#fs_fs_appendfile_path_data_options_callback"><code>fs.appendFile(path, data[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_appendfilesync_path_data_options"><code>fs.appendFileSync(path, data[, options])</code></a></li>
|
||
<li><a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod(path, mode, callback)</code></a>
|
||
<ul>
|
||
<li><a href="#fs_file_modes">File modes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_chmodsync_path_mode"><code>fs.chmodSync(path, mode)</code></a></li>
|
||
<li><a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown(path, uid, gid, callback)</code></a></li>
|
||
<li><a href="#fs_fs_chownsync_path_uid_gid"><code>fs.chownSync(path, uid, gid)</code></a></li>
|
||
<li><a href="#fs_fs_close_fd_callback"><code>fs.close(fd, callback)</code></a></li>
|
||
<li><a href="#fs_fs_closesync_fd"><code>fs.closeSync(fd)</code></a></li>
|
||
<li><a href="#fs_fs_constants"><code>fs.constants</code></a></li>
|
||
<li><a href="#fs_fs_copyfile_src_dest_flags_callback"><code>fs.copyFile(src, dest[, flags], callback)</code></a></li>
|
||
<li><a href="#fs_fs_copyfilesync_src_dest_flags"><code>fs.copyFileSync(src, dest[, flags])</code></a></li>
|
||
<li><a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream(path[, options])</code></a></li>
|
||
<li><span class="stability_0"><a href="#fs_fs_exists_path_callback"><code>fs.exists(path, callback)</code></a></span></li>
|
||
<li><a href="#fs_fs_existssync_path"><code>fs.existsSync(path)</code></a></li>
|
||
<li><a href="#fs_fs_fchmod_fd_mode_callback"><code>fs.fchmod(fd, mode, callback)</code></a></li>
|
||
<li><a href="#fs_fs_fchmodsync_fd_mode"><code>fs.fchmodSync(fd, mode)</code></a></li>
|
||
<li><a href="#fs_fs_fchown_fd_uid_gid_callback"><code>fs.fchown(fd, uid, gid, callback)</code></a></li>
|
||
<li><a href="#fs_fs_fchownsync_fd_uid_gid"><code>fs.fchownSync(fd, uid, gid)</code></a></li>
|
||
<li><a href="#fs_fs_fdatasync_fd_callback"><code>fs.fdatasync(fd, callback)</code></a></li>
|
||
<li><a href="#fs_fs_fdatasyncsync_fd"><code>fs.fdatasyncSync(fd)</code></a></li>
|
||
<li><a href="#fs_fs_fstat_fd_options_callback"><code>fs.fstat(fd[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_fstatsync_fd_options"><code>fs.fstatSync(fd[, options])</code></a></li>
|
||
<li><a href="#fs_fs_fsync_fd_callback"><code>fs.fsync(fd, callback)</code></a></li>
|
||
<li><a href="#fs_fs_fsyncsync_fd"><code>fs.fsyncSync(fd)</code></a></li>
|
||
<li><a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate(fd[, len], callback)</code></a></li>
|
||
<li><a href="#fs_fs_ftruncatesync_fd_len"><code>fs.ftruncateSync(fd[, len])</code></a></li>
|
||
<li><a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes(fd, atime, mtime, callback)</code></a></li>
|
||
<li><a href="#fs_fs_futimessync_fd_atime_mtime"><code>fs.futimesSync(fd, atime, mtime)</code></a></li>
|
||
<li><a href="#fs_fs_lchmod_path_mode_callback"><code>fs.lchmod(path, mode, callback)</code></a></li>
|
||
<li><a href="#fs_fs_lchmodsync_path_mode"><code>fs.lchmodSync(path, mode)</code></a></li>
|
||
<li><a href="#fs_fs_lchown_path_uid_gid_callback"><code>fs.lchown(path, uid, gid, callback)</code></a></li>
|
||
<li><a href="#fs_fs_lchownsync_path_uid_gid"><code>fs.lchownSync(path, uid, gid)</code></a></li>
|
||
<li><a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes(path, atime, mtime, callback)</code></a></li>
|
||
<li><a href="#fs_fs_lutimessync_path_atime_mtime"><code>fs.lutimesSync(path, atime, mtime)</code></a></li>
|
||
<li><a href="#fs_fs_link_existingpath_newpath_callback"><code>fs.link(existingPath, newPath, callback)</code></a></li>
|
||
<li><a href="#fs_fs_linksync_existingpath_newpath"><code>fs.linkSync(existingPath, newPath)</code></a></li>
|
||
<li><a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_lstatsync_path_options"><code>fs.lstatSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_mkdirsync_path_options"><code>fs.mkdirSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp(prefix[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_mkdtempsync_prefix_options"><code>fs.mkdtempSync(prefix[, options])</code></a></li>
|
||
<li><a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open(path[, flags[, mode]], callback)</code></a></li>
|
||
<li><a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_opensync_path_flags_mode"><code>fs.openSync(path[, flags, mode])</code></a></li>
|
||
<li><a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read(fd, buffer, offset, length, position, callback)</code></a></li>
|
||
<li><a href="#fs_fs_read_fd_options_callback"><code>fs.read(fd, [options,] callback)</code></a></li>
|
||
<li><a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile(path[, options], callback)</code></a>
|
||
<ul>
|
||
<li><a href="#fs_file_descriptors_1">File descriptors</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_readlink_path_options_callback"><code>fs.readlink(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_readlinksync_path_options"><code>fs.readlinkSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_readsync_fd_buffer_offset_length_position"><code>fs.readSync(fd, buffer, offset, length, position)</code></a></li>
|
||
<li><a href="#fs_fs_readsync_fd_buffer_options"><code>fs.readSync(fd, buffer, [options])</code></a></li>
|
||
<li><a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv(fd, buffers[, position], callback)</code></a></li>
|
||
<li><a href="#fs_fs_readvsync_fd_buffers_position"><code>fs.readvSync(fd, buffers[, position])</code></a></li>
|
||
<li><a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_realpath_native_path_options_callback"><code>fs.realpath.native(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_realpathsync_path_options"><code>fs.realpathSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_realpathsync_native_path_options"><code>fs.realpathSync.native(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_rename_oldpath_newpath_callback"><code>fs.rename(oldPath, newPath, callback)</code></a></li>
|
||
<li><a href="#fs_fs_renamesync_oldpath_newpath"><code>fs.renameSync(oldPath, newPath)</code></a></li>
|
||
<li><span class="stability_1"><a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir(path[, options], callback)</code></a></span></li>
|
||
<li><span class="stability_1"><a href="#fs_fs_rmdirsync_path_options"><code>fs.rmdirSync(path[, options])</code></a></span></li>
|
||
<li><a href="#fs_fs_stat_path_options_callback"><code>fs.stat(path[, options], callback)</code></a></li>
|
||
<li><a href="#fs_fs_statsync_path_options"><code>fs.statSync(path[, options])</code></a></li>
|
||
<li><a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink(target, path[, type], callback)</code></a></li>
|
||
<li><a href="#fs_fs_symlinksync_target_path_type"><code>fs.symlinkSync(target, path[, type])</code></a></li>
|
||
<li><a href="#fs_fs_truncate_path_len_callback"><code>fs.truncate(path[, len], callback)</code></a></li>
|
||
<li><a href="#fs_fs_truncatesync_path_len"><code>fs.truncateSync(path[, len])</code></a></li>
|
||
<li><a href="#fs_fs_unlink_path_callback"><code>fs.unlink(path, callback)</code></a></li>
|
||
<li><a href="#fs_fs_unlinksync_path"><code>fs.unlinkSync(path)</code></a></li>
|
||
<li><a href="#fs_fs_unwatchfile_filename_listener"><code>fs.unwatchFile(filename[, listener])</code></a></li>
|
||
<li><a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes(path, atime, mtime, callback)</code></a></li>
|
||
<li><a href="#fs_fs_utimessync_path_atime_mtime"><code>fs.utimesSync(path, atime, mtime)</code></a></li>
|
||
<li><a href="#fs_fs_watch_filename_options_listener"><code>fs.watch(filename[, options][, listener])</code></a>
|
||
<ul>
|
||
<li><a href="#fs_caveats">Caveats</a>
|
||
<ul>
|
||
<li><a href="#fs_availability">Availability</a></li>
|
||
<li><a href="#fs_inodes">Inodes</a></li>
|
||
<li><a href="#fs_filename_argument">Filename argument</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_watchfile_filename_options_listener"><code>fs.watchFile(filename[, options], listener)</code></a></li>
|
||
<li><a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer[, offset[, length[, position]]], callback)</code></a></li>
|
||
<li><a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string[, position[, encoding]], callback)</code></a></li>
|
||
<li><a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile(file, data[, options], callback)</code></a>
|
||
<ul>
|
||
<li><a href="#fs_using_fs_writefile_with_file_descriptors">Using <code>fs.writeFile()</code> with file descriptors</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_writefilesync_file_data_options"><code>fs.writeFileSync(file, data[, options])</code></a></li>
|
||
<li><a href="#fs_fs_writesync_fd_buffer_offset_length_position"><code>fs.writeSync(fd, buffer[, offset[, length[, position]]])</code></a></li>
|
||
<li><a href="#fs_fs_writesync_fd_string_position_encoding"><code>fs.writeSync(fd, string[, position[, encoding]])</code></a></li>
|
||
<li><a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev(fd, buffers[, position], callback)</code></a></li>
|
||
<li><a href="#fs_fs_writevsync_fd_buffers_position"><code>fs.writevSync(fd, buffers[, position])</code></a></li>
|
||
<li><a href="#fs_fs_promises_api"><code>fs</code> Promises API</a>
|
||
<ul>
|
||
<li><a href="#fs_class_filehandle">Class: <code>FileHandle</code></a>
|
||
<ul>
|
||
<li><a href="#fs_filehandle_appendfile_data_options"><code>filehandle.appendFile(data, options)</code></a></li>
|
||
<li><a href="#fs_filehandle_chmod_mode"><code>filehandle.chmod(mode)</code></a></li>
|
||
<li><a href="#fs_filehandle_chown_uid_gid"><code>filehandle.chown(uid, gid)</code></a></li>
|
||
<li><a href="#fs_filehandle_close"><code>filehandle.close()</code></a></li>
|
||
<li><a href="#fs_filehandle_datasync"><code>filehandle.datasync()</code></a></li>
|
||
<li><a href="#fs_filehandle_fd"><code>filehandle.fd</code></a></li>
|
||
<li><a href="#fs_filehandle_read_buffer_offset_length_position"><code>filehandle.read(buffer, offset, length, position)</code></a></li>
|
||
<li><a href="#fs_filehandle_read_options"><code>filehandle.read(options)</code></a></li>
|
||
<li><a href="#fs_filehandle_readfile_options"><code>filehandle.readFile(options)</code></a></li>
|
||
<li><a href="#fs_filehandle_readv_buffers_position"><code>filehandle.readv(buffers[, position])</code></a></li>
|
||
<li><a href="#fs_filehandle_stat_options"><code>filehandle.stat([options])</code></a></li>
|
||
<li><a href="#fs_filehandle_sync"><code>filehandle.sync()</code></a></li>
|
||
<li><a href="#fs_filehandle_truncate_len"><code>filehandle.truncate(len)</code></a></li>
|
||
<li><a href="#fs_filehandle_utimes_atime_mtime"><code>filehandle.utimes(atime, mtime)</code></a></li>
|
||
<li><a href="#fs_filehandle_write_buffer_offset_length_position"><code>filehandle.write(buffer[, offset[, length[, position]]])</code></a></li>
|
||
<li><a href="#fs_filehandle_write_string_position_encoding"><code>filehandle.write(string[, position[, encoding]])</code></a></li>
|
||
<li><a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile(data, options)</code></a></li>
|
||
<li><a href="#fs_filehandle_writev_buffers_position"><code>filehandle.writev(buffers[, position])</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fspromises_access_path_mode"><code>fsPromises.access(path[, mode])</code></a></li>
|
||
<li><a href="#fs_fspromises_appendfile_path_data_options"><code>fsPromises.appendFile(path, data[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_chmod_path_mode"><code>fsPromises.chmod(path, mode)</code></a></li>
|
||
<li><a href="#fs_fspromises_chown_path_uid_gid"><code>fsPromises.chown(path, uid, gid)</code></a></li>
|
||
<li><a href="#fs_fspromises_copyfile_src_dest_flags"><code>fsPromises.copyFile(src, dest[, flags])</code></a></li>
|
||
<li><a href="#fs_fspromises_lchmod_path_mode"><code>fsPromises.lchmod(path, mode)</code></a></li>
|
||
<li><a href="#fs_fspromises_lchown_path_uid_gid"><code>fsPromises.lchown(path, uid, gid)</code></a></li>
|
||
<li><a href="#fs_fspromises_lutimes_path_atime_mtime"><code>fsPromises.lutimes(path, atime, mtime)</code></a></li>
|
||
<li><a href="#fs_fspromises_link_existingpath_newpath"><code>fsPromises.link(existingPath, newPath)</code></a></li>
|
||
<li><a href="#fs_fspromises_lstat_path_options"><code>fsPromises.lstat(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_mkdir_path_options"><code>fsPromises.mkdir(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_mkdtemp_prefix_options"><code>fsPromises.mkdtemp(prefix[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open(path, flags[, mode])</code></a></li>
|
||
<li><a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_readdir_path_options"><code>fsPromises.readdir(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_readfile_path_options"><code>fsPromises.readFile(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_readlink_path_options"><code>fsPromises.readlink(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_realpath_path_options"><code>fsPromises.realpath(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_rename_oldpath_newpath"><code>fsPromises.rename(oldPath, newPath)</code></a></li>
|
||
<li><span class="stability_1"><a href="#fs_fspromises_rmdir_path_options"><code>fsPromises.rmdir(path[, options])</code></a></span></li>
|
||
<li><a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat(path[, options])</code></a></li>
|
||
<li><a href="#fs_fspromises_symlink_target_path_type"><code>fsPromises.symlink(target, path[, type])</code></a></li>
|
||
<li><a href="#fs_fspromises_truncate_path_len"><code>fsPromises.truncate(path[, len])</code></a></li>
|
||
<li><a href="#fs_fspromises_unlink_path"><code>fsPromises.unlink(path)</code></a></li>
|
||
<li><a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes(path, atime, mtime)</code></a></li>
|
||
<li><a href="#fs_fspromises_writefile_file_data_options"><code>fsPromises.writeFile(file, data[, options])</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_fs_constants_1">FS constants</a>
|
||
<ul>
|
||
<li><a href="#fs_file_access_constants">File access constants</a></li>
|
||
<li><a href="#fs_file_copy_constants">File copy constants</a></li>
|
||
<li><a href="#fs_file_open_constants">File open constants</a></li>
|
||
<li><a href="#fs_file_type_constants">File type constants</a></li>
|
||
<li><a href="#fs_file_mode_constants">File mode constants</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#fs_file_system_flags">File system flags</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div id="apicontent">
|
||
<h1>File system<span><a class="mark" href="#fs_file_system" id="fs_file_system">#</a></span></h1>
|
||
|
||
<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p>
|
||
|
||
<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v12.22.12/lib/fs.js">lib/fs.js</a></p>
|
||
<p>The <code>fs</code> module enables interacting with the file system in a
|
||
way modeled on standard POSIX functions.</p>
|
||
<p>To use this module:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);</code></pre>
|
||
<p>All file system operations have synchronous, callback, and promise-based
|
||
forms.</p>
|
||
<h2>Synchronous example<span><a class="mark" href="#fs_synchronous_example" id="fs_synchronous_example">#</a></span></h2>
|
||
<p>The synchronous form blocks the Node.js event loop and further JavaScript
|
||
execution until the operation is complete. Exceptions are thrown immediately
|
||
and can be handled using <code>try…catch</code>, or can be allowed to bubble up.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">try</span> {
|
||
fs.unlinkSync(<span class="hljs-string">'/tmp/hello'</span>);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'successfully deleted /tmp/hello'</span>);
|
||
} <span class="hljs-keyword">catch</span> (err) {
|
||
<span class="hljs-comment">// handle the error</span>
|
||
}</code></pre>
|
||
<h2>Callback example<span><a class="mark" href="#fs_callback_example" id="fs_callback_example">#</a></span></h2>
|
||
<p>The callback form takes a completion callback function as its last
|
||
argument and invokes the operation asynchronously. The arguments passed to
|
||
the completion callback depend on the method, but the first argument is always
|
||
reserved for an exception. If the operation is completed successfully, then
|
||
the first argument is <code>null</code> or <code>undefined</code>.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
fs.unlink(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'successfully deleted /tmp/hello'</span>);
|
||
});</code></pre>
|
||
<h2>Promise example<span><a class="mark" href="#fs_promise_example" id="fs_promise_example">#</a></span></h2>
|
||
<p>Promise-based operations return a <code>Promise</code> that is resolved when the
|
||
asynchronous operation is complete.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>).promises;
|
||
|
||
(<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">path</span>) </span>{
|
||
<span class="hljs-keyword">try</span> {
|
||
<span class="hljs-keyword">await</span> fs.unlink(path);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`successfully deleted <span class="hljs-subst">${path}</span>`</span>);
|
||
} <span class="hljs-keyword">catch</span> (error) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'there was an error:'</span>, error.message);
|
||
}
|
||
})(<span class="hljs-string">'/tmp/hello'</span>);</code></pre>
|
||
<h2>Ordering of callback and promise-based operations<span><a class="mark" href="#fs_ordering_of_callback_and_promise_based_operations" id="fs_ordering_of_callback_and_promise_based_operations">#</a></span></h2>
|
||
<p>There is no guaranteed ordering when using either the callback or
|
||
promise-based methods. For example, the following is prone to error
|
||
because the <code>fs.stat()</code> operation might complete before the <code>fs.rename()</code>
|
||
operation:</p>
|
||
<pre><code class="language-js">fs.rename(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'renamed complete'</span>);
|
||
});
|
||
fs.stat(<span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>);
|
||
});</code></pre>
|
||
<p>To correctly order the operations, move the <code>fs.stat()</code> call into the callback
|
||
of the <code>fs.rename()</code> operation:</p>
|
||
<pre><code class="language-js">fs.rename(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.stat(<span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>);
|
||
});
|
||
});</code></pre>
|
||
<p>Or, use the promise-based API:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>).promises;
|
||
|
||
(<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">from, to</span>) </span>{
|
||
<span class="hljs-keyword">try</span> {
|
||
<span class="hljs-keyword">await</span> fs.rename(<span class="hljs-keyword">from</span>, to);
|
||
<span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> fs.stat(to);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>);
|
||
} <span class="hljs-keyword">catch</span> (error) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'there was an error:'</span>, error.message);
|
||
}
|
||
})(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>);</code></pre>
|
||
<h2>File paths<span><a class="mark" href="#fs_file_paths" id="fs_file_paths">#</a></span></h2>
|
||
<p>Most <code>fs</code> operations accept filepaths that may be specified in the form of
|
||
a string, a <a href="buffer.html#buffer_buffer"><code>Buffer</code></a>, or a <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> object using the <code>file:</code> protocol.</p>
|
||
<p>String form paths are interpreted as UTF-8 character sequences identifying
|
||
the absolute or relative filename. Relative paths will be resolved relative
|
||
to the current working directory as determined by calling <code>process.cwd()</code>.</p>
|
||
<p>Example using an absolute path on POSIX:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
fs.open(<span class="hljs-string">'/open/some/file.txt'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.close(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
});</code></pre>
|
||
<p>Example using a relative path on POSIX (relative to <code>process.cwd()</code>):</p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'file.txt'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.close(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
});</code></pre>
|
||
<p>Paths specified using a <a href="buffer.html#buffer_buffer"><code>Buffer</code></a> are useful primarily on certain POSIX
|
||
operating systems that treat file paths as opaque byte sequences. On such
|
||
systems, it is possible for a single file path to contain sub-sequences that
|
||
use multiple character encodings. As with string paths, <code>Buffer</code> paths may
|
||
be relative or absolute:</p>
|
||
<p>Example using an absolute path on POSIX:</p>
|
||
<pre><code class="language-js">fs.open(Buffer.from(<span class="hljs-string">'/open/some/file.txt'</span>), <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.close(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
});</code></pre>
|
||
<p>On Windows, Node.js follows the concept of per-drive working directory. This
|
||
behavior can be observed when using a drive path without a backslash. For
|
||
example <code>fs.readdirSync('C:\\')</code> can potentially return a different result than
|
||
<code>fs.readdirSync('C:')</code>. For more information, see
|
||
<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths">this MSDN page</a>.</p>
|
||
<h3>URL object support<span><a class="mark" href="#fs_url_object_support" id="fs_url_object_support">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v7.6.0</span>
|
||
</div>
|
||
<p>For most <code>fs</code> module functions, the <code>path</code> or <code>filename</code> argument may be passed
|
||
as a WHATWG <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> object. Only <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> objects using the <code>file:</code> protocol
|
||
are supported.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> fileUrl = <span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///tmp/hello'</span>);
|
||
|
||
fs.readFileSync(fileUrl);</code></pre>
|
||
<p><code>file:</code> URLs are always absolute paths.</p>
|
||
<p>Using WHATWG <a href="url.html#url_the_whatwg_url_api"><code>URL</code></a> objects might introduce platform-specific behaviors.</p>
|
||
<p>On Windows, <code>file:</code> URLs with a host name convert to UNC paths, while <code>file:</code>
|
||
URLs with drive letters convert to local absolute paths. <code>file:</code> URLs without a
|
||
host name nor a drive letter will result in a throw:</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// On Windows :</span>
|
||
|
||
<span class="hljs-comment">// - WHATWG file URLs with hostname convert to UNC path</span>
|
||
<span class="hljs-comment">// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file://hostname/p/a/t/h/file'</span>));
|
||
|
||
<span class="hljs-comment">// - WHATWG file URLs with drive letters convert to absolute path</span>
|
||
<span class="hljs-comment">// file:///C:/tmp/hello => C:\tmp\hello</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///C:/tmp/hello'</span>));
|
||
|
||
<span class="hljs-comment">// - WHATWG file URLs without hostname must have a drive letters</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///notdriveletter/p/a/t/h/file'</span>));
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///c/p/a/t/h/file'</span>));
|
||
<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute</span></code></pre>
|
||
<p><code>file:</code> URLs with drive letters must use <code>:</code> as a separator just after
|
||
the drive letter. Using another separator will result in a throw.</p>
|
||
<p>On all other platforms, <code>file:</code> URLs with a host name are unsupported and will
|
||
result in a throw:</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// On other platforms:</span>
|
||
|
||
<span class="hljs-comment">// - WHATWG file URLs with hostname are unsupported</span>
|
||
<span class="hljs-comment">// file://hostname/p/a/t/h/file => throw!</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file://hostname/p/a/t/h/file'</span>));
|
||
<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute</span>
|
||
|
||
<span class="hljs-comment">// - WHATWG file URLs convert to absolute path</span>
|
||
<span class="hljs-comment">// file:///tmp/hello => /tmp/hello</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///tmp/hello'</span>));</code></pre>
|
||
<p>A <code>file:</code> URL having encoded slash characters will result in a throw on all
|
||
platforms:</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// On Windows</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///C:/p/a/t/h/%2F'</span>));
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///C:/p/a/t/h/%2f'</span>));
|
||
<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
|
||
\ or / characters */</span>
|
||
|
||
<span class="hljs-comment">// On POSIX</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///p/a/t/h/%2F'</span>));
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///p/a/t/h/%2f'</span>));
|
||
<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
|
||
/ characters */</span></code></pre>
|
||
<p>On Windows, <code>file:</code> URLs having encoded backslash will result in a throw:</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// On Windows</span>
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///C:/path/%5C'</span>));
|
||
fs.readFileSync(<span class="hljs-keyword">new</span> URL(<span class="hljs-string">'file:///C:/path/%5c'</span>));
|
||
<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
|
||
\ or / characters */</span></code></pre>
|
||
<h2>File descriptors<span><a class="mark" href="#fs_file_descriptors" id="fs_file_descriptors">#</a></span></h2>
|
||
<p>On POSIX systems, for every process, the kernel maintains a table of currently
|
||
open files and resources. Each open file is assigned a simple numeric
|
||
identifier called a <em>file descriptor</em>. At the system-level, all file system
|
||
operations use these file descriptors to identify and track each specific
|
||
file. Windows systems use a different but conceptually similar mechanism for
|
||
tracking resources. To simplify things for users, Node.js abstracts away the
|
||
specific differences between operating systems and assigns all open files a
|
||
numeric file descriptor.</p>
|
||
<p>The <code>fs.open()</code> method is used to allocate a new file descriptor. Once
|
||
allocated, the file descriptor may be used to read data from, write data to,
|
||
or request information about the file.</p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'/open/some/file.txt'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.fstat(fd, <span class="hljs-function">(<span class="hljs-params">err, stat</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-comment">// use stat</span>
|
||
|
||
<span class="hljs-comment">// always close the file descriptor!</span>
|
||
fs.close(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
});
|
||
});</code></pre>
|
||
<p>Most operating systems limit the number of file descriptors that may be open
|
||
at any given time so it is critical to close the descriptor when operations
|
||
are completed. Failure to do so will result in a memory leak that will
|
||
eventually cause an application to crash.</p>
|
||
<h2>Threadpool usage<span><a class="mark" href="#fs_threadpool_usage" id="fs_threadpool_usage">#</a></span></h2>
|
||
<p>All file system APIs except <code>fs.FSWatcher()</code> and those that are explicitly
|
||
synchronous use libuv's threadpool, which can have surprising and negative
|
||
performance implications for some applications. See the
|
||
<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p>
|
||
<h2>Class: <code>fs.Dir</code><span><a class="mark" href="#fs_class_fs_dir" id="fs_class_fs_dir">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<p>A class representing a directory stream.</p>
|
||
<p>Created by <a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir()</code></a>, <a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync()</code></a>, or
|
||
<a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir()</code></a>.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">print</span>(<span class="hljs-params">path</span>) </span>{
|
||
<span class="hljs-keyword">const</span> dir = <span class="hljs-keyword">await</span> fs.promises.opendir(path);
|
||
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> dirent <span class="hljs-keyword">of</span> dir) {
|
||
<span class="hljs-built_in">console</span>.log(dirent.name);
|
||
}
|
||
}
|
||
print(<span class="hljs-string">'./'</span>).catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<h3><code>dir.close()</code><span><a class="mark" href="#fs_dir_close" id="fs_dir_close">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously close the directory's underlying resource handle.
|
||
Subsequent reads will result in errors.</p>
|
||
<p>A <code>Promise</code> is returned that will be resolved after the resource has been
|
||
closed.</p>
|
||
<h3><code>dir.close(callback)</code><span><a class="mark" href="#fs_dir_close_callback" id="fs_dir_close_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously close the directory's underlying resource handle.
|
||
Subsequent reads will result in errors.</p>
|
||
<p>The <code>callback</code> will be called after the resource handle has been closed.</p>
|
||
<h3><code>dir.closeSync()</code><span><a class="mark" href="#fs_dir_closesync" id="fs_dir_closesync">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<p>Synchronously close the directory's underlying resource handle.
|
||
Subsequent reads will result in errors.</p>
|
||
<h3><code>dir.path</code><span><a class="mark" href="#fs_dir_path" id="fs_dir_path">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>The read-only path of this directory as was provided to <a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir()</code></a>,
|
||
<a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync()</code></a>, or <a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir()</code></a>.</p>
|
||
<h3><code>dir.read()</code><span><a class="mark" href="#fs_dir_read" id="fs_dir_read">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> containing <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
||
</ul>
|
||
<p>Asynchronously read the next directory entry via <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> as an
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>.</p>
|
||
<p>After the read is completed, a <code>Promise</code> is returned that will be resolved with
|
||
an <a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>, or <code>null</code> if there are no more directory entries to read.</p>
|
||
<p>Directory entries returned by this function are in no particular order as
|
||
provided by the operating system's underlying directory mechanisms.
|
||
Entries added or removed while iterating over the directory may or may not be
|
||
included in the iteration results.</p>
|
||
<h3><code>dir.read(callback)</code><span><a class="mark" href="#fs_dir_read_callback" id="fs_dir_read_callback">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>dirent</code> <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously read the next directory entry via <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> as an
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>.</p>
|
||
<p>After the read is completed, the <code>callback</code> will be called with an
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>, or <code>null</code> if there are no more directory entries to read.</p>
|
||
<p>Directory entries returned by this function are in no particular order as
|
||
provided by the operating system's underlying directory mechanisms.
|
||
Entries added or removed while iterating over the directory may or may not be
|
||
included in the iteration results.</p>
|
||
<h3><code>dir.readSync()</code><span><a class="mark" href="#fs_dir_readsync" id="fs_dir_readsync">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a></li>
|
||
</ul>
|
||
<p>Synchronously read the next directory entry via <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> as an
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>.</p>
|
||
<p>If there are no more directory entries to read, <code>null</code> will be returned.</p>
|
||
<p>Directory entries returned by this function are in no particular order as
|
||
provided by the operating system's underlying directory mechanisms.
|
||
Entries added or removed while iterating over the directory may or may not be
|
||
included in the iteration results.</p>
|
||
<h3><code>dir[Symbol.asyncIterator]()</code><span><a class="mark" href="#fs_dir_symbol_asynciterator" id="fs_dir_symbol_asynciterator">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.12.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> of <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a></li>
|
||
</ul>
|
||
<p>Asynchronously iterates over the directory via <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> until all entries have
|
||
been read.</p>
|
||
<p>Entries returned by the async iterator are always an <a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a>.
|
||
The <code>null</code> case from <code>dir.read()</code> is handled internally.</p>
|
||
<p>See <a href="#fs_class_fs_dir"><code>fs.Dir</code></a> for an example.</p>
|
||
<p>Directory entries returned by this iterator are in no particular order as
|
||
provided by the operating system's underlying directory mechanisms.
|
||
Entries added or removed while iterating over the directory may or may not be
|
||
included in the iteration results.</p>
|
||
<h2>Class: <code>fs.Dirent</code><span><a class="mark" href="#fs_class_fs_dirent" id="fs_class_fs_dirent">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<p>A representation of a directory entry, which can be a file or a subdirectory
|
||
within the directory, as returned by reading from an <a href="#fs_class_fs_dir"><code>fs.Dir</code></a>. The
|
||
directory entry is a combination of the file name and file type pairs.</p>
|
||
<p>Additionally, when <a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir()</code></a> or <a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync()</code></a> is called with
|
||
the <code>withFileTypes</code> option set to <code>true</code>, the resulting array is filled with
|
||
<code>fs.Dirent</code> objects, rather than strings or <code>Buffers</code>.</p>
|
||
<h3><code>dirent.isBlockDevice()</code><span><a class="mark" href="#fs_dirent_isblockdevice" id="fs_dirent_isblockdevice">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a block device.</p>
|
||
<h3><code>dirent.isCharacterDevice()</code><span><a class="mark" href="#fs_dirent_ischaracterdevice" id="fs_dirent_ischaracterdevice">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a character device.</p>
|
||
<h3><code>dirent.isDirectory()</code><span><a class="mark" href="#fs_dirent_isdirectory" id="fs_dirent_isdirectory">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a file system
|
||
directory.</p>
|
||
<h3><code>dirent.isFIFO()</code><span><a class="mark" href="#fs_dirent_isfifo" id="fs_dirent_isfifo">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a first-in-first-out
|
||
(FIFO) pipe.</p>
|
||
<h3><code>dirent.isFile()</code><span><a class="mark" href="#fs_dirent_isfile" id="fs_dirent_isfile">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a regular file.</p>
|
||
<h3><code>dirent.isSocket()</code><span><a class="mark" href="#fs_dirent_issocket" id="fs_dirent_issocket">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a socket.</p>
|
||
<h3><code>dirent.isSymbolicLink()</code><span><a class="mark" href="#fs_dirent_issymboliclink" id="fs_dirent_issymboliclink">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Dirent</code> object describes a symbolic link.</p>
|
||
<h3><code>dirent.name</code><span><a class="mark" href="#fs_dirent_name" id="fs_dirent_name">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>The file name that this <code>fs.Dirent</code> object refers to. The type of this
|
||
value is determined by the <code>options.encoding</code> passed to <a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir()</code></a> or
|
||
<a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync()</code></a>.</p>
|
||
<h2>Class: <code>fs.FSWatcher</code><span><a class="mark" href="#fs_class_fs_fswatcher" id="fs_class_fs_fswatcher">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.5.8</span>
|
||
</div>
|
||
<ul>
|
||
<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li>
|
||
</ul>
|
||
<p>A successful call to <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> method will return a new <code>fs.FSWatcher</code>
|
||
object.</p>
|
||
<p>All <code>fs.FSWatcher</code> objects emit a <code>'change'</code> event whenever a specific watched
|
||
file is modified.</p>
|
||
<h3>Event: <code>'change'</code><span><a class="mark" href="#fs_event_change" id="fs_event_change">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.5.8</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>eventType</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The type of change event that has occurred</li>
|
||
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> The filename that changed (if relevant/available)</li>
|
||
</ul>
|
||
<p>Emitted when something changes in a watched directory or file.
|
||
See more details in <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a>.</p>
|
||
<p>The <code>filename</code> argument may not be provided depending on operating system
|
||
support. If <code>filename</code> is provided, it will be provided as a <code>Buffer</code> if
|
||
<code>fs.watch()</code> is called with its <code>encoding</code> option set to <code>'buffer'</code>, otherwise
|
||
<code>filename</code> will be a UTF-8 string.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// Example when handled through fs.watch() listener</span>
|
||
fs.watch(<span class="hljs-string">'./tmp'</span>, { <span class="hljs-attr">encoding</span>: <span class="hljs-string">'buffer'</span> }, <span class="hljs-function">(<span class="hljs-params">eventType, filename</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (filename) {
|
||
<span class="hljs-built_in">console</span>.log(filename);
|
||
<span class="hljs-comment">// Prints: <Buffer ...></span>
|
||
}
|
||
});</code></pre>
|
||
<h3>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close" id="fs_event_close">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<p>Emitted when the watcher stops watching for changes. The closed
|
||
<code>fs.FSWatcher</code> object is no longer usable in the event handler.</p>
|
||
<h3>Event: <code>'error'</code><span><a class="mark" href="#fs_event_error" id="fs_event_error">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.5.8</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
<p>Emitted when an error occurs while watching the file. The errored
|
||
<code>fs.FSWatcher</code> object is no longer usable in the event handler.</p>
|
||
<h3><code>watcher.close()</code><span><a class="mark" href="#fs_watcher_close" id="fs_watcher_close">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.5.8</span>
|
||
</div>
|
||
<p>Stop watching for changes on the given <code>fs.FSWatcher</code>. Once stopped, the
|
||
<code>fs.FSWatcher</code> object is no longer usable.</p>
|
||
<h3><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref" id="fs_watcher_ref">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.20.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li>
|
||
</ul>
|
||
<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the
|
||
<code>FSWatcher</code> is active. Calling <code>watcher.ref()</code> multiple times will have
|
||
no effect.</p>
|
||
<p>By default, all <code>FSWatcher</code> objects are "ref'ed", making it normally
|
||
unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been
|
||
called previously.</p>
|
||
<h3><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref" id="fs_watcher_unref">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.20.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li>
|
||
</ul>
|
||
<p>When called, the active <code>FSWatcher</code> object will not require the Node.js
|
||
event loop to remain active. If there is no other activity keeping the
|
||
event loop running, the process may exit before the <code>FSWatcher</code> object's
|
||
callback is invoked. Calling <code>watcher.unref()</code> multiple times will have
|
||
no effect.</p>
|
||
<h2>Class: <code>fs.StatWatcher</code><span><a class="mark" href="#fs_class_fs_statwatcher" id="fs_class_fs_statwatcher">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.20.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li>
|
||
</ul>
|
||
<p>A successful call to <code>fs.watchFile()</code> method will return a new <code>fs.StatWatcher</code>
|
||
object.</p>
|
||
<h3><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref_1" id="fs_watcher_ref_1">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.20.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li>
|
||
</ul>
|
||
<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the
|
||
<code>StatWatcher</code> is active. Calling <code>watcher.ref()</code> multiple times will have
|
||
no effect.</p>
|
||
<p>By default, all <code>StatWatcher</code> objects are "ref'ed", making it normally
|
||
unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been
|
||
called previously.</p>
|
||
<h3><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref_1" id="fs_watcher_unref_1">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.20.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li>
|
||
</ul>
|
||
<p>When called, the active <code>StatWatcher</code> object will not require the Node.js
|
||
event loop to remain active. If there is no other activity keeping the
|
||
event loop running, the process may exit before the <code>StatWatcher</code> object's
|
||
callback is invoked. Calling <code>watcher.unref()</code> multiple times will have
|
||
no effect.</p>
|
||
<h2>Class: <code>fs.ReadStream</code><span><a class="mark" href="#fs_class_fs_readstream" id="fs_class_fs_readstream">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<ul>
|
||
<li>Extends: <a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li>
|
||
</ul>
|
||
<p>Instances of <code>fs.ReadStream</code> are created and returned using the
|
||
<a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream()</code></a> function.</p>
|
||
<h3>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_1" id="fs_event_close_1">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<p>Emitted when the <code>fs.ReadStream</code>'s underlying file descriptor has been closed.</p>
|
||
<h3>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open" id="fs_event_open">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Integer file descriptor used by the <code>ReadStream</code>.</li>
|
||
</ul>
|
||
<p>Emitted when the <code>fs.ReadStream</code>'s file descriptor has been opened.</p>
|
||
<h3>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready" id="fs_event_ready">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v9.11.0</span>
|
||
</div>
|
||
<p>Emitted when the <code>fs.ReadStream</code> is ready to be used.</p>
|
||
<p>Fires immediately after <code>'open'</code>.</p>
|
||
<h3><code>readStream.bytesRead</code><span><a class="mark" href="#fs_readstream_bytesread" id="fs_readstream_bytesread">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v6.4.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
||
</ul>
|
||
<p>The number of bytes that have been read so far.</p>
|
||
<h3><code>readStream.path</code><span><a class="mark" href="#fs_readstream_path" id="fs_readstream_path">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>The path to the file the stream is reading from as specified in the first
|
||
argument to <code>fs.createReadStream()</code>. If <code>path</code> is passed as a string, then
|
||
<code>readStream.path</code> will be a string. If <code>path</code> is passed as a <code>Buffer</code>, then
|
||
<code>readStream.path</code> will be a <code>Buffer</code>.</p>
|
||
<h3><code>readStream.pending</code><span><a class="mark" href="#fs_readstream_pending" id="fs_readstream_pending">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v11.2.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>This property is <code>true</code> if the underlying file has not been opened yet,
|
||
i.e. before the <code>'ready'</code> event is emitted.</p>
|
||
<h2>Class: <code>fs.Stats</code><span><a class="mark" href="#fs_class_fs_stats" id="fs_class_fs_stats">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v8.1.0</td>
|
||
<td><p>Added times as numbers.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<p>A <code>fs.Stats</code> object provides information about a file.</p>
|
||
<p>Objects returned from <a href="#fs_fs_stat_path_options_callback"><code>fs.stat()</code></a>, <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a> and <a href="#fs_fs_fstat_fd_options_callback"><code>fs.fstat()</code></a> and
|
||
their synchronous counterparts are of this type.
|
||
If <code>bigint</code> in the <code>options</code> passed to those methods is true, the numeric values
|
||
will be <code>bigint</code> instead of <code>number</code>, and the object will contain additional
|
||
nanosecond-precision properties suffixed with <code>Ns</code>.</p>
|
||
<pre><code class="language-console">Stats {
|
||
dev: 2114,
|
||
ino: 48064969,
|
||
mode: 33188,
|
||
nlink: 1,
|
||
uid: 85,
|
||
gid: 100,
|
||
rdev: 0,
|
||
size: 527,
|
||
blksize: 4096,
|
||
blocks: 8,
|
||
atimeMs: 1318289051000.1,
|
||
mtimeMs: 1318289051000.1,
|
||
ctimeMs: 1318289051000.1,
|
||
birthtimeMs: 1318289051000.1,
|
||
atime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre>
|
||
<p><code>bigint</code> version:</p>
|
||
<pre><code class="language-console">BigIntStats {
|
||
dev: 2114n,
|
||
ino: 48064969n,
|
||
mode: 33188n,
|
||
nlink: 1n,
|
||
uid: 85n,
|
||
gid: 100n,
|
||
rdev: 0n,
|
||
size: 527n,
|
||
blksize: 4096n,
|
||
blocks: 8n,
|
||
atimeMs: 1318289051000n,
|
||
mtimeMs: 1318289051000n,
|
||
ctimeMs: 1318289051000n,
|
||
birthtimeMs: 1318289051000n,
|
||
atimeNs: 1318289051000000000n,
|
||
mtimeNs: 1318289051000000000n,
|
||
ctimeNs: 1318289051000000000n,
|
||
birthtimeNs: 1318289051000000000n,
|
||
atime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
|
||
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre>
|
||
<h3><code>stats.isBlockDevice()</code><span><a class="mark" href="#fs_stats_isblockdevice" id="fs_stats_isblockdevice">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a block device.</p>
|
||
<h3><code>stats.isCharacterDevice()</code><span><a class="mark" href="#fs_stats_ischaracterdevice" id="fs_stats_ischaracterdevice">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a character device.</p>
|
||
<h3><code>stats.isDirectory()</code><span><a class="mark" href="#fs_stats_isdirectory" id="fs_stats_isdirectory">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a file system directory.</p>
|
||
<h3><code>stats.isFIFO()</code><span><a class="mark" href="#fs_stats_isfifo" id="fs_stats_isfifo">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a first-in-first-out (FIFO)
|
||
pipe.</p>
|
||
<h3><code>stats.isFile()</code><span><a class="mark" href="#fs_stats_isfile" id="fs_stats_isfile">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a regular file.</p>
|
||
<h3><code>stats.isSocket()</code><span><a class="mark" href="#fs_stats_issocket" id="fs_stats_issocket">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a socket.</p>
|
||
<h3><code>stats.isSymbolicLink()</code><span><a class="mark" href="#fs_stats_issymboliclink" id="fs_stats_issymboliclink">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.10</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the <code>fs.Stats</code> object describes a symbolic link.</p>
|
||
<p>This method is only valid when using <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a>.</p>
|
||
<h3><code>stats.dev</code><span><a class="mark" href="#fs_stats_dev" id="fs_stats_dev">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The numeric identifier of the device containing the file.</p>
|
||
<h3><code>stats.ino</code><span><a class="mark" href="#fs_stats_ino" id="fs_stats_ino">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The file system specific "Inode" number for the file.</p>
|
||
<h3><code>stats.mode</code><span><a class="mark" href="#fs_stats_mode" id="fs_stats_mode">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>A bit-field describing the file type and mode.</p>
|
||
<h3><code>stats.nlink</code><span><a class="mark" href="#fs_stats_nlink" id="fs_stats_nlink">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The number of hard-links that exist for the file.</p>
|
||
<h3><code>stats.uid</code><span><a class="mark" href="#fs_stats_uid" id="fs_stats_uid">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The numeric user identifier of the user that owns the file (POSIX).</p>
|
||
<h3><code>stats.gid</code><span><a class="mark" href="#fs_stats_gid" id="fs_stats_gid">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The numeric group identifier of the group that owns the file (POSIX).</p>
|
||
<h3><code>stats.rdev</code><span><a class="mark" href="#fs_stats_rdev" id="fs_stats_rdev">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>A numeric device identifier if the file represents a device.</p>
|
||
<h3><code>stats.size</code><span><a class="mark" href="#fs_stats_size" id="fs_stats_size">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The size of the file in bytes.</p>
|
||
<h3><code>stats.blksize</code><span><a class="mark" href="#fs_stats_blksize" id="fs_stats_blksize">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The file system block size for i/o operations.</p>
|
||
<h3><code>stats.blocks</code><span><a class="mark" href="#fs_stats_blocks" id="fs_stats_blocks">#</a></span></h3>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The number of blocks allocated for this file.</p>
|
||
<h3><code>stats.atimeMs</code><span><a class="mark" href="#fs_stats_atimems" id="fs_stats_atimems">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.1.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time this file was accessed expressed in
|
||
milliseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.mtimeMs</code><span><a class="mark" href="#fs_stats_mtimems" id="fs_stats_mtimems">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.1.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time this file was modified expressed in
|
||
milliseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.ctimeMs</code><span><a class="mark" href="#fs_stats_ctimems" id="fs_stats_ctimems">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.1.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time the file status was changed expressed
|
||
in milliseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.birthtimeMs</code><span><a class="mark" href="#fs_stats_birthtimems" id="fs_stats_birthtimems">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v8.1.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the creation time of this file expressed in
|
||
milliseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.atimeNs</code><span><a class="mark" href="#fs_stats_atimens" id="fs_stats_atimens">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>Only present when <code>bigint: true</code> is passed into the method that generates
|
||
the object.
|
||
The timestamp indicating the last time this file was accessed expressed in
|
||
nanoseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.mtimeNs</code><span><a class="mark" href="#fs_stats_mtimens" id="fs_stats_mtimens">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>Only present when <code>bigint: true</code> is passed into the method that generates
|
||
the object.
|
||
The timestamp indicating the last time this file was modified expressed in
|
||
nanoseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.ctimeNs</code><span><a class="mark" href="#fs_stats_ctimens" id="fs_stats_ctimens">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>Only present when <code>bigint: true</code> is passed into the method that generates
|
||
the object.
|
||
The timestamp indicating the last time the file status was changed expressed
|
||
in nanoseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.birthtimeNs</code><span><a class="mark" href="#fs_stats_birthtimens" id="fs_stats_birthtimens">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li>
|
||
</ul>
|
||
<p>Only present when <code>bigint: true</code> is passed into the method that generates
|
||
the object.
|
||
The timestamp indicating the creation time of this file expressed in
|
||
nanoseconds since the POSIX Epoch.</p>
|
||
<h3><code>stats.atime</code><span><a class="mark" href="#fs_stats_atime" id="fs_stats_atime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.11.13</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time this file was accessed.</p>
|
||
<h3><code>stats.mtime</code><span><a class="mark" href="#fs_stats_mtime" id="fs_stats_mtime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.11.13</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time this file was modified.</p>
|
||
<h3><code>stats.ctime</code><span><a class="mark" href="#fs_stats_ctime" id="fs_stats_ctime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.11.13</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the last time the file status was changed.</p>
|
||
<h3><code>stats.birthtime</code><span><a class="mark" href="#fs_stats_birthtime" id="fs_stats_birthtime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.11.13</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>The timestamp indicating the creation time of this file.</p>
|
||
<h3>Stat time values<span><a class="mark" href="#fs_stat_time_values" id="fs_stat_time_values">#</a></span></h3>
|
||
<p>The <code>atimeMs</code>, <code>mtimeMs</code>, <code>ctimeMs</code>, <code>birthtimeMs</code> properties are
|
||
numeric values that hold the corresponding times in milliseconds. Their
|
||
precision is platform specific. When <code>bigint: true</code> is passed into the
|
||
method that generates the object, the properties will be <a href="https://tc39.github.io/proposal-bigint">bigints</a>,
|
||
otherwise they will be <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type">numbers</a>.</p>
|
||
<p>The <code>atimeNs</code>, <code>mtimeNs</code>, <code>ctimeNs</code>, <code>birthtimeNs</code> properties are
|
||
<a href="https://tc39.github.io/proposal-bigint">bigints</a> that hold the corresponding times in nanoseconds. They are
|
||
only present when <code>bigint: true</code> is passed into the method that generates
|
||
the object. Their precision is platform specific.</p>
|
||
<p><code>atime</code>, <code>mtime</code>, <code>ctime</code>, and <code>birthtime</code> are
|
||
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date"><code>Date</code></a> object alternate representations of the various times. The
|
||
<code>Date</code> and number values are not connected. Assigning a new number value, or
|
||
mutating the <code>Date</code> value, will not be reflected in the corresponding alternate
|
||
representation.</p>
|
||
<p>The times in the stat object have the following semantics:</p>
|
||
<ul>
|
||
<li><code>atime</code> "Access Time": Time when file data last accessed. Changed
|
||
by the <a href="http://man7.org/linux/man-pages/man2/mknod.2.html"><code>mknod(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/utimes.2.html"><code>utimes(2)</code></a>, and <a href="http://man7.org/linux/man-pages/man2/read.2.html"><code>read(2)</code></a> system calls.</li>
|
||
<li><code>mtime</code> "Modified Time": Time when file data last modified.
|
||
Changed by the <a href="http://man7.org/linux/man-pages/man2/mknod.2.html"><code>mknod(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/utimes.2.html"><code>utimes(2)</code></a>, and <a href="http://man7.org/linux/man-pages/man2/write.2.html"><code>write(2)</code></a> system calls.</li>
|
||
<li><code>ctime</code> "Change Time": Time when file status was last changed
|
||
(inode data modification). Changed by the <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a>,
|
||
<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/mknod.2.html"><code>mknod(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>, <a href="http://man7.org/linux/man-pages/man2/utimes.2.html"><code>utimes(2)</code></a>,
|
||
<a href="http://man7.org/linux/man-pages/man2/read.2.html"><code>read(2)</code></a>, and <a href="http://man7.org/linux/man-pages/man2/write.2.html"><code>write(2)</code></a> system calls.</li>
|
||
<li><code>birthtime</code> "Birth Time": Time of file creation. Set once when the
|
||
file is created. On filesystems where birthtime is not available,
|
||
this field may instead hold either the <code>ctime</code> or
|
||
<code>1970-01-01T00:00Z</code> (ie, Unix epoch timestamp <code>0</code>). This value may be greater
|
||
than <code>atime</code> or <code>mtime</code> in this case. On Darwin and other FreeBSD variants,
|
||
also set if the <code>atime</code> is explicitly set to an earlier value than the current
|
||
<code>birthtime</code> using the <a href="http://man7.org/linux/man-pages/man2/utimes.2.html"><code>utimes(2)</code></a> system call.</li>
|
||
</ul>
|
||
<p>Prior to Node.js 0.12, the <code>ctime</code> held the <code>birthtime</code> on Windows systems. As
|
||
of 0.12, <code>ctime</code> is not "creation time", and on Unix systems, it never was.</p>
|
||
<h2>Class: <code>fs.WriteStream</code><span><a class="mark" href="#fs_class_fs_writestream" id="fs_class_fs_writestream">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<ul>
|
||
<li>Extends <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li>
|
||
</ul>
|
||
<p>Instances of <code>fs.WriteStream</code> are created and returned using the
|
||
<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> function.</p>
|
||
<h3>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_2" id="fs_event_close_2">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<p>Emitted when the <code>WriteStream</code>'s underlying file descriptor has been closed.</p>
|
||
<h3>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open_1" id="fs_event_open_1">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Integer file descriptor used by the <code>WriteStream</code>.</li>
|
||
</ul>
|
||
<p>Emitted when the <code>WriteStream</code>'s file is opened.</p>
|
||
<h3>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready_1" id="fs_event_ready_1">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v9.11.0</span>
|
||
</div>
|
||
<p>Emitted when the <code>fs.WriteStream</code> is ready to be used.</p>
|
||
<p>Fires immediately after <code>'open'</code>.</p>
|
||
<h3><code>writeStream.bytesWritten</code><span><a class="mark" href="#fs_writestream_byteswritten" id="fs_writestream_byteswritten">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.4.7</span>
|
||
</div>
|
||
<p>The number of bytes written so far. Does not include data that is still queued
|
||
for writing.</p>
|
||
<h3><code>writeStream.path</code><span><a class="mark" href="#fs_writestream_path" id="fs_writestream_path">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.93</span>
|
||
</div>
|
||
<p>The path to the file the stream is writing to as specified in the first
|
||
argument to <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>. If <code>path</code> is passed as a string, then
|
||
<code>writeStream.path</code> will be a string. If <code>path</code> is passed as a <code>Buffer</code>, then
|
||
<code>writeStream.path</code> will be a <code>Buffer</code>.</p>
|
||
<h3><code>writeStream.pending</code><span><a class="mark" href="#fs_writestream_pending" id="fs_writestream_pending">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v11.2.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>This property is <code>true</code> if the underlying file has not been opened yet,
|
||
i.e. before the <code>'ready'</code> event is emitted.</p>
|
||
<h2><code>fs.access(path[, mode], callback)</code><span><a class="mark" href="#fs_fs_access_path_mode_callback" id="fs_fs_access_path_mode_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v6.3.0</td>
|
||
<td><p>The constants like <code>fs.R_OK</code>, etc which were present directly on <code>fs</code> were moved into <code>fs.constants</code> as a soft deprecation. Thus for Node.js <code>< v6.3.0</code> use <code>fs</code> to access those constants, or do something like <code>(fs.constants || fs).R_OK</code> to work with all versions.</p></td></tr>
|
||
<tr><td>v0.11.15</td>
|
||
<td><p><span>Added in: v0.11.15</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>fs.constants.F_OK</code></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Tests a user's permissions for the file or directory specified by <code>path</code>.
|
||
The <code>mode</code> argument is an optional integer that specifies the accessibility
|
||
checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values
|
||
of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of
|
||
two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p>
|
||
<p>The final argument, <code>callback</code>, is a callback function that is invoked with
|
||
a possible error argument. If any of the accessibility checks fail, the error
|
||
argument will be an <code>Error</code> object. The following examples check if
|
||
<code>package.json</code> exists, and if it is readable or writable.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> file = <span class="hljs-string">'package.json'</span>;
|
||
|
||
<span class="hljs-comment">// Check if the file exists in the current directory.</span>
|
||
fs.access(file, fs.constants.F_OK, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${file}</span> <span class="hljs-subst">${err ? <span class="hljs-string">'does not exist'</span> : <span class="hljs-string">'exists'</span>}</span>`</span>);
|
||
});
|
||
|
||
<span class="hljs-comment">// Check if the file is readable.</span>
|
||
fs.access(file, fs.constants.R_OK, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${file}</span> <span class="hljs-subst">${err ? <span class="hljs-string">'is not readable'</span> : <span class="hljs-string">'is readable'</span>}</span>`</span>);
|
||
});
|
||
|
||
<span class="hljs-comment">// Check if the file is writable.</span>
|
||
fs.access(file, fs.constants.W_OK, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${file}</span> <span class="hljs-subst">${err ? <span class="hljs-string">'is not writable'</span> : <span class="hljs-string">'is writable'</span>}</span>`</span>);
|
||
});
|
||
|
||
<span class="hljs-comment">// Check if the file exists in the current directory, and if it is writable.</span>
|
||
fs.access(file, fs.constants.F_OK | fs.constants.W_OK, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-built_in">console</span>.error(
|
||
<span class="hljs-string">`<span class="hljs-subst">${file}</span> <span class="hljs-subst">${err.code === <span class="hljs-string">'ENOENT'</span> ? <span class="hljs-string">'does not exist'</span> : <span class="hljs-string">'is read-only'</span>}</span>`</span>);
|
||
} <span class="hljs-keyword">else</span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${file}</span> exists, and it is writable`</span>);
|
||
}
|
||
});</code></pre>
|
||
<p>Do not use <code>fs.access()</code> to check for the accessibility of a file before calling
|
||
<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code>. Doing
|
||
so introduces a race condition, since other processes may change the file's
|
||
state between the two calls. Instead, user code should open/read/write the
|
||
file directly and handle the error raised if the file is not accessible.</p>
|
||
<p><strong>write (NOT RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.access(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (!err) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile already exists'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
writeMyData(fd);
|
||
});
|
||
});</code></pre>
|
||
<p><strong>write (RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-keyword">if</span> (err.code === <span class="hljs-string">'EEXIST'</span>) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile already exists'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
<span class="hljs-keyword">throw</span> err;
|
||
}
|
||
|
||
writeMyData(fd);
|
||
});</code></pre>
|
||
<p><strong>read (NOT RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.access(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-keyword">if</span> (err.code === <span class="hljs-string">'ENOENT'</span>) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile does not exist'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
<span class="hljs-keyword">throw</span> err;
|
||
}
|
||
|
||
fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
readMyData(fd);
|
||
});
|
||
});</code></pre>
|
||
<p><strong>read (RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-keyword">if</span> (err.code === <span class="hljs-string">'ENOENT'</span>) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile does not exist'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
<span class="hljs-keyword">throw</span> err;
|
||
}
|
||
|
||
readMyData(fd);
|
||
});</code></pre>
|
||
<p>The "not recommended" examples above check for accessibility and then use the
|
||
file; the "recommended" examples are better because they use the file directly
|
||
and handle the error, if any.</p>
|
||
<p>In general, check for the accessibility of a file only if the file will not be
|
||
used directly, for example when its accessibility is a signal from another
|
||
process.</p>
|
||
<p>On Windows, access-control policies (ACLs) on a directory may limit access to
|
||
a file or directory. The <code>fs.access()</code> function, however, does not check the
|
||
ACL and therefore may report that a path is accessible even if the ACL restricts
|
||
the user from reading or writing to it.</p>
|
||
<h2><code>fs.accessSync(path[, mode])</code><span><a class="mark" href="#fs_fs_accesssync_path_mode" id="fs_fs_accesssync_path_mode">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.11.15</td>
|
||
<td><p><span>Added in: v0.11.15</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>fs.constants.F_OK</code></li>
|
||
</ul>
|
||
<p>Synchronously tests a user's permissions for the file or directory specified
|
||
by <code>path</code>. The <code>mode</code> argument is an optional integer that specifies the
|
||
accessibility checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for
|
||
possible values of <code>mode</code>. It is possible to create a mask consisting of
|
||
the bitwise OR of two or more values
|
||
(e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p>
|
||
<p>If any of the accessibility checks fail, an <code>Error</code> will be thrown. Otherwise,
|
||
the method will return <code>undefined</code>.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">try</span> {
|
||
fs.accessSync(<span class="hljs-string">'etc/passwd'</span>, fs.constants.R_OK | fs.constants.W_OK);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'can read/write'</span>);
|
||
} <span class="hljs-keyword">catch</span> (err) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'no access!'</span>);
|
||
}</code></pre>
|
||
<h2><code>fs.appendFile(path, data[, options], callback)</code><span><a class="mark" href="#fs_fs_appendfile_path_data_options_callback" id="fs_fs_appendfile_path_data_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The passed <code>options</code> object will never be modified.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.6.7</td>
|
||
<td><p><span>Added in: v0.6.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> filename or file descriptor</li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'a'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously append data to a file, creating the file if it does not yet
|
||
exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_buffer"><code>Buffer</code></a>.</p>
|
||
<pre><code class="language-js">fs.appendFile(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The "data to append" was appended to file!'</span>);
|
||
});</code></pre>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding:</p>
|
||
<pre><code class="language-js">fs.appendFile(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre>
|
||
<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened
|
||
for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will
|
||
not be closed automatically.</p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'a'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
fs.appendFile(fd, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
fs.close(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});
|
||
});</code></pre>
|
||
<h2><code>fs.appendFileSync(path, data[, options])</code><span><a class="mark" href="#fs_fs_appendfilesync_path_data_options" id="fs_fs_appendfilesync_path_data_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The passed <code>options</code> object will never be modified.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.6.7</td>
|
||
<td><p><span>Added in: v0.6.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> filename or file descriptor</li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'a'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Synchronously append data to a file, creating the file if it does not yet
|
||
exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_buffer"><code>Buffer</code></a>.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">try</span> {
|
||
fs.appendFileSync(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The "data to append" was appended to file!'</span>);
|
||
} <span class="hljs-keyword">catch</span> (err) {
|
||
<span class="hljs-comment">/* Handle the error */</span>
|
||
}</code></pre>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding:</p>
|
||
<pre><code class="language-js">fs.appendFileSync(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>);</code></pre>
|
||
<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened
|
||
for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will
|
||
not be closed automatically.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">let</span> fd;
|
||
|
||
<span class="hljs-keyword">try</span> {
|
||
fd = fs.openSync(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'a'</span>);
|
||
fs.appendFileSync(fd, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>);
|
||
} <span class="hljs-keyword">catch</span> (err) {
|
||
<span class="hljs-comment">/* Handle the error */</span>
|
||
} <span class="hljs-keyword">finally</span> {
|
||
<span class="hljs-keyword">if</span> (fd !== <span class="hljs-literal">undefined</span>)
|
||
fs.closeSync(fd);
|
||
}</code></pre>
|
||
<h2><code>fs.chmod(path, mode, callback)</code><span><a class="mark" href="#fs_fs_chmod_path_mode_callback" id="fs_fs_chmod_path_mode_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.30</td>
|
||
<td><p><span>Added in: v0.1.30</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously changes the permissions of a file. No arguments other than a
|
||
possible exception are given to the completion callback.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a>.</p>
|
||
<pre><code class="language-js">fs.chmod(<span class="hljs-string">'my_file.txt'</span>, <span class="hljs-number">0o775</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The permissions for file "my_file.txt" have been changed!'</span>);
|
||
});</code></pre>
|
||
<h3>File modes<span><a class="mark" href="#fs_file_modes" id="fs_file_modes">#</a></span></h3>
|
||
<p>The <code>mode</code> argument used in both the <code>fs.chmod()</code> and <code>fs.chmodSync()</code>
|
||
methods is a numeric bitmask created using a logical OR of the following
|
||
constants:</p>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<table><thead><tr><th>Constant</th><th>Octal</th><th>Description</th></tr></thead><tbody><tr><td><code>fs.constants.S_IRUSR</code></td><td><code>0o400</code></td><td>read by owner</td></tr><tr><td><code>fs.constants.S_IWUSR</code></td><td><code>0o200</code></td><td>write by owner</td></tr><tr><td><code>fs.constants.S_IXUSR</code></td><td><code>0o100</code></td><td>execute/search by owner</td></tr><tr><td><code>fs.constants.S_IRGRP</code></td><td><code>0o40</code></td><td>read by group</td></tr><tr><td><code>fs.constants.S_IWGRP</code></td><td><code>0o20</code></td><td>write by group</td></tr><tr><td><code>fs.constants.S_IXGRP</code></td><td><code>0o10</code></td><td>execute/search by group</td></tr><tr><td><code>fs.constants.S_IROTH</code></td><td><code>0o4</code></td><td>read by others</td></tr><tr><td><code>fs.constants.S_IWOTH</code></td><td><code>0o2</code></td><td>write by others</td></tr><tr><td><code>fs.constants.S_IXOTH</code></td><td><code>0o1</code></td><td>execute/search by others</td></tr></tbody></table>
|
||
<p>An easier method of constructing the <code>mode</code> is to use a sequence of three
|
||
octal digits (e.g. <code>765</code>). The left-most digit (<code>7</code> in the example), specifies
|
||
the permissions for the file owner. The middle digit (<code>6</code> in the example),
|
||
specifies permissions for the group. The right-most digit (<code>5</code> in the example),
|
||
specifies the permissions for others.</p>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<table><thead><tr><th>Number</th><th>Description</th></tr></thead><tbody><tr><td><code>7</code></td><td>read, write, and execute</td></tr><tr><td><code>6</code></td><td>read and write</td></tr><tr><td><code>5</code></td><td>read and execute</td></tr><tr><td><code>4</code></td><td>read only</td></tr><tr><td><code>3</code></td><td>write and execute</td></tr><tr><td><code>2</code></td><td>write only</td></tr><tr><td><code>1</code></td><td>execute only</td></tr><tr><td><code>0</code></td><td>no permission</td></tr></tbody></table>
|
||
<p>For example, the octal value <code>0o765</code> means:</p>
|
||
<ul>
|
||
<li>The owner may read, write and execute the file.</li>
|
||
<li>The group may read and write the file.</li>
|
||
<li>Others may read and execute the file.</li>
|
||
</ul>
|
||
<p>When using raw numbers where file modes are expected, any value larger than
|
||
<code>0o777</code> may result in platform-specific behaviors that are not supported to work
|
||
consistently. Therefore constants like <code>S_ISVTX</code>, <code>S_ISGID</code> or <code>S_ISUID</code> are not
|
||
exposed in <code>fs.constants</code>.</p>
|
||
<p>Caveats: on Windows only the write permission can be changed, and the
|
||
distinction among the permissions of group, owner or others is not
|
||
implemented.</p>
|
||
<h2><code>fs.chmodSync(path, mode)</code><span><a class="mark" href="#fs_fs_chmodsync_path_mode" id="fs_fs_chmodsync_path_mode">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.6.7</td>
|
||
<td><p><span>Added in: v0.6.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a>.</p>
|
||
<h2><code>fs.chown(path, uid, gid, callback)</code><span><a class="mark" href="#fs_fs_chown_path_uid_gid_callback" id="fs_fs_chown_path_uid_gid_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.97</td>
|
||
<td><p><span>Added in: v0.1.97</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously changes owner and group of a file. No arguments other than a
|
||
possible exception are given to the completion callback.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a>.</p>
|
||
<h2><code>fs.chownSync(path, uid, gid)</code><span><a class="mark" href="#fs_fs_chownsync_path_uid_gid" id="fs_fs_chownsync_path_uid_gid">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.97</td>
|
||
<td><p><span>Added in: v0.1.97</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronously changes owner and group of a file. Returns <code>undefined</code>.
|
||
This is the synchronous version of <a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown()</code></a>.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a>.</p>
|
||
<h2><code>fs.close(fd, callback)</code><span><a class="mark" href="#fs_fs_close_fd_callback" id="fs_fs_close_fd_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/close.2.html"><code>close(2)</code></a>. No arguments other than a possible exception are given
|
||
to the completion callback.</p>
|
||
<p>Calling <code>fs.close()</code> on any file descriptor (<code>fd</code>) that is currently in use
|
||
through any other <code>fs</code> operation may lead to undefined behavior.</p>
|
||
<h2><code>fs.closeSync(fd)</code><span><a class="mark" href="#fs_fs_closesync_fd" id="fs_fs_closesync_fd">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.21</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/close.2.html"><code>close(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<p>Calling <code>fs.closeSync()</code> on any file descriptor (<code>fd</code>) that is currently in use
|
||
through any other <code>fs</code> operation may lead to undefined behavior.</p>
|
||
<h2><code>fs.constants</code><span><a class="mark" href="#fs_fs_constants" id="fs_fs_constants">#</a></span></h2>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
|
||
</ul>
|
||
<p>Returns an object containing commonly used constants for file system
|
||
operations. The specific constants currently defined are described in
|
||
<a href="#fs_fs_constants_1">FS constants</a>.</p>
|
||
<h2><code>fs.copyFile(src, dest[, flags], callback)</code><span><a class="mark" href="#fs_fs_copyfile_src_dest_flags_callback" id="fs_fs_copyfile_src_dest_flags_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v14.0.0</td>
|
||
<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr>
|
||
<tr><td>v8.5.0</td>
|
||
<td><p><span>Added in: v8.5.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>src</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> source filename to copy</li>
|
||
<li><code>dest</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> destination filename of the copy operation</li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> modifiers for copy operation. <strong>Default:</strong> <code>0</code>.</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>
|
||
</ul>
|
||
<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> 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.</p>
|
||
<p><code>flags</code> is an optional integer that specifies the behavior
|
||
of the copy operation. It is possible to create a mask consisting of the bitwise
|
||
OR of two or more values (e.g.
|
||
<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p>
|
||
<ul>
|
||
<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already
|
||
exists.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a
|
||
copy-on-write reflink. If the platform does not support copy-on-write, then a
|
||
fallback copy mechanism is used.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to
|
||
create a copy-on-write reflink. If the platform does not support copy-on-write,
|
||
then the operation will fail.</li>
|
||
</ul>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span>
|
||
fs.copyFile(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'source.txt was copied to destination.txt'</span>);
|
||
});</code></pre>
|
||
<p>If the third argument is a number, then it specifies <code>flags</code>:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> { COPYFILE_EXCL } = fs.constants;
|
||
|
||
<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span>
|
||
fs.copyFile(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, COPYFILE_EXCL, callback);</code></pre>
|
||
<h2><code>fs.copyFileSync(src, dest[, flags])</code><span><a class="mark" href="#fs_fs_copyfilesync_src_dest_flags" id="fs_fs_copyfilesync_src_dest_flags">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v14.0.0</td>
|
||
<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr>
|
||
<tr><td>v8.5.0</td>
|
||
<td><p><span>Added in: v8.5.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>src</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> source filename to copy</li>
|
||
<li><code>dest</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> destination filename of the copy operation</li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> modifiers for copy operation. <strong>Default:</strong> <code>0</code>.</li>
|
||
</ul>
|
||
<p>Synchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it
|
||
already exists. Returns <code>undefined</code>. 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.</p>
|
||
<p><code>flags</code> is an optional integer that specifies the behavior
|
||
of the copy operation. It is possible to create a mask consisting of the bitwise
|
||
OR of two or more values (e.g.
|
||
<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p>
|
||
<ul>
|
||
<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already
|
||
exists.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a
|
||
copy-on-write reflink. If the platform does not support copy-on-write, then a
|
||
fallback copy mechanism is used.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to
|
||
create a copy-on-write reflink. If the platform does not support copy-on-write,
|
||
then the operation will fail.</li>
|
||
</ul>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span>
|
||
fs.copyFileSync(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'source.txt was copied to destination.txt'</span>);</code></pre>
|
||
<p>If the third argument is a number, then it specifies <code>flags</code>:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> { COPYFILE_EXCL } = fs.constants;
|
||
|
||
<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span>
|
||
fs.copyFileSync(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, COPYFILE_EXCL);</code></pre>
|
||
<h2><code>fs.createReadStream(path[, options])</code><span><a class="mark" href="#fs_fs_createreadstream_path_options" id="fs_fs_createreadstream_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr>
|
||
<tr><td>v12.10.0</td>
|
||
<td><p>Enable <code>emitClose</code> option.</p></td></tr>
|
||
<tr><td>v11.0.0</td>
|
||
<td><p>Impose new restrictions on <code>start</code> and <code>end</code>, throwing more appropriate errors in cases when we cannot reasonably handle the input values.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The passed <code>options</code> object will never be modified.</p></td></tr>
|
||
<tr><td>v2.3.0</td>
|
||
<td><p>The passed <code>options</code> object can be a string now.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong>
|
||
<code>'r'</code>.</li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>autoClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
||
<li><code>emitClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>end</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>Infinity</code></li>
|
||
<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>64 * 1024</code></li>
|
||
<li><code>fs</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> See <a href="stream.html#stream_class_stream_readable">Readable Stream</a>.</li>
|
||
</ul>
|
||
<p>Unlike the 16 kb default <code>highWaterMark</code> for a readable stream, the stream
|
||
returned by this method has a default <code>highWaterMark</code> of 64 kb.</p>
|
||
<p><code>options</code> can include <code>start</code> and <code>end</code> values to read a range of bytes from
|
||
the file instead of the entire file. Both <code>start</code> and <code>end</code> are inclusive and
|
||
start counting at 0, allowed values are in the
|
||
[0, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER"><code>Number.MAX_SAFE_INTEGER</code></a>] range. If <code>fd</code> is specified and <code>start</code> is
|
||
omitted or <code>undefined</code>, <code>fs.createReadStream()</code> reads sequentially from the
|
||
current file position. The <code>encoding</code> can be any one of those accepted by
|
||
<a href="buffer.html#buffer_buffer"><code>Buffer</code></a>.</p>
|
||
<p>If <code>fd</code> is specified, <code>ReadStream</code> will ignore the <code>path</code> argument and will use
|
||
the specified file descriptor. This means that no <code>'open'</code> event will be
|
||
emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s should be passed to
|
||
<a href="net.html#net_class_net_socket"><code>net.Socket</code></a>.</p>
|
||
<p>If <code>fd</code> points to a character device that only supports blocking reads
|
||
(such as keyboard or sound card), read operations do not finish until data is
|
||
available. This can prevent the process from exiting and the stream from
|
||
closing naturally.</p>
|
||
<p>By default, the stream will not emit a <code>'close'</code> event after it has been
|
||
destroyed. This is the opposite of the default for other <code>Readable</code> streams.
|
||
Set the <code>emitClose</code> option to <code>true</code> to change this behavior.</p>
|
||
<p>By providing the <code>fs</code> option, it is possible to override the corresponding <code>fs</code>
|
||
implementations for <code>open</code>, <code>read</code>, and <code>close</code>. When providing the <code>fs</code> option,
|
||
overrides for <code>open</code>, <code>read</code>, and <code>close</code> are required.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-comment">// Create a stream from some character device.</span>
|
||
<span class="hljs-keyword">const</span> stream = fs.createReadStream(<span class="hljs-string">'/dev/input/event0'</span>);
|
||
<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> {
|
||
stream.close(); <span class="hljs-comment">// This may not close the stream.</span>
|
||
<span class="hljs-comment">// Artificially marking end-of-stream, as if the underlying resource had</span>
|
||
<span class="hljs-comment">// indicated end-of-file by itself, allows the stream to close.</span>
|
||
<span class="hljs-comment">// This does not cancel pending read operations, and if there is such an</span>
|
||
<span class="hljs-comment">// operation, the process may still not be able to exit successfully</span>
|
||
<span class="hljs-comment">// until it finishes.</span>
|
||
stream.push(<span class="hljs-literal">null</span>);
|
||
stream.read(<span class="hljs-number">0</span>);
|
||
}, <span class="hljs-number">100</span>);</code></pre>
|
||
<p>If <code>autoClose</code> is false, then the file descriptor won't be closed, even if
|
||
there's an error. It is the application's responsibility to close it and make
|
||
sure there's no file descriptor leak. If <code>autoClose</code> is set to true (default
|
||
behavior), on <code>'error'</code> or <code>'end'</code> the file descriptor will be closed
|
||
automatically.</p>
|
||
<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the
|
||
file was created.</p>
|
||
<p>An example to read the last 10 bytes of a file which is 100 bytes long:</p>
|
||
<pre><code class="language-js">fs.createReadStream(<span class="hljs-string">'sample.txt'</span>, { <span class="hljs-attr">start</span>: <span class="hljs-number">90</span>, <span class="hljs-attr">end</span>: <span class="hljs-number">99</span> });</code></pre>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<h2><code>fs.createWriteStream(path[, options])</code><span><a class="mark" href="#fs_fs_createwritestream_path_options" id="fs_fs_createwritestream_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr>
|
||
<tr><td>v12.10.0</td>
|
||
<td><p>Enable <code>emitClose</code> option.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The passed <code>options</code> object will never be modified.</p></td></tr>
|
||
<tr><td>v5.5.0</td>
|
||
<td><p>The <code>autoClose</code> option is supported now.</p></td></tr>
|
||
<tr><td>v2.3.0</td>
|
||
<td><p>The passed <code>options</code> object can be a string now.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong>
|
||
<code>'w'</code>.</li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>autoClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
||
<li><code>emitClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>fs</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> See <a href="#stream_class_stream_writable">Writable Stream</a>.</li>
|
||
</ul>
|
||
<p><code>options</code> may also include a <code>start</code> option to allow writing data at
|
||
some position past the beginning of the file, allowed values are in the
|
||
[0, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER"><code>Number.MAX_SAFE_INTEGER</code></a>] range. Modifying a file rather
|
||
than replacing it may require a <code>flags</code> mode of <code>r+</code> rather than the
|
||
default mode <code>w</code>. The <code>encoding</code> can be any one of those accepted by
|
||
<a href="buffer.html#buffer_buffer"><code>Buffer</code></a>.</p>
|
||
<p>If <code>autoClose</code> is set to true (default behavior) on <code>'error'</code> or <code>'finish'</code>
|
||
the file descriptor will be closed automatically. If <code>autoClose</code> is false,
|
||
then the file descriptor won't be closed, even if there's an error.
|
||
It is the application's responsibility to close it and make sure there's no
|
||
file descriptor leak.</p>
|
||
<p>By default, the stream will not emit a <code>'close'</code> event after it has been
|
||
destroyed. This is the opposite of the default for other <code>Writable</code> streams.
|
||
Set the <code>emitClose</code> option to <code>true</code> to change this behavior.</p>
|
||
<p>By providing the <code>fs</code> option it is possible to override the corresponding <code>fs</code>
|
||
implementations for <code>open</code>, <code>write</code>, <code>writev</code> and <code>close</code>. Overriding <code>write()</code>
|
||
without <code>writev()</code> can reduce performance as some optimizations (<code>_writev()</code>)
|
||
will be disabled. When providing the <code>fs</code> option, overrides for <code>open</code>,
|
||
<code>close</code>, and at least one of <code>write</code> and <code>writev</code> are required.</p>
|
||
<p>Like <a href="#fs_class_fs_readstream"><code>ReadStream</code></a>, if <code>fd</code> is specified, <a href="#fs_class_fs_writestream"><code>WriteStream</code></a> will ignore the
|
||
<code>path</code> argument and will use the specified file descriptor. This means that no
|
||
<code>'open'</code> event will be emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s
|
||
should be passed to <a href="net.html#net_class_net_socket"><code>net.Socket</code></a>.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<h2><code>fs.exists(path, callback)</code><span><a class="mark" href="#fs_fs_exists_path_callback" id="fs_fs_exists_path_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v1.0.0</td>
|
||
<td><p><span>Deprecated since: v1.0.0</span></p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<p></p><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated: Use <a href="#fs_fs_stat_path_options_callback"><code>fs.stat()</code></a> or <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a> instead.</div><p></p>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>exists</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Test whether or not the given path exists by checking with the file system.
|
||
Then call the <code>callback</code> argument with either true or false:</p>
|
||
<pre><code class="language-js">fs.exists(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-function">(<span class="hljs-params">exists</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(exists ? <span class="hljs-string">'it\'s there'</span> : <span class="hljs-string">'no passwd!'</span>);
|
||
});</code></pre>
|
||
<p><strong>The parameters for this callback are not consistent with other Node.js
|
||
callbacks.</strong> Normally, the first parameter to a Node.js callback is an <code>err</code>
|
||
parameter, optionally followed by other parameters. The <code>fs.exists()</code> callback
|
||
has only one boolean parameter. This is one reason <code>fs.access()</code> is recommended
|
||
instead of <code>fs.exists()</code>.</p>
|
||
<p>Using <code>fs.exists()</code> to check for the existence of a file before calling
|
||
<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended. Doing
|
||
so introduces a race condition, since other processes may change the file's
|
||
state between the two calls. Instead, user code should open/read/write the
|
||
file directly and handle the error raised if the file does not exist.</p>
|
||
<p><strong>write (NOT RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.exists(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">exists</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (exists) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile already exists'</span>);
|
||
} <span class="hljs-keyword">else</span> {
|
||
fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
writeMyData(fd);
|
||
});
|
||
}
|
||
});</code></pre>
|
||
<p><strong>write (RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-keyword">if</span> (err.code === <span class="hljs-string">'EEXIST'</span>) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile already exists'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
<span class="hljs-keyword">throw</span> err;
|
||
}
|
||
|
||
writeMyData(fd);
|
||
});</code></pre>
|
||
<p><strong>read (NOT RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.exists(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">exists</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (exists) {
|
||
fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
readMyData(fd);
|
||
});
|
||
} <span class="hljs-keyword">else</span> {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile does not exist'</span>);
|
||
}
|
||
});</code></pre>
|
||
<p><strong>read (RECOMMENDED)</strong></p>
|
||
<pre><code class="language-js">fs.open(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) {
|
||
<span class="hljs-keyword">if</span> (err.code === <span class="hljs-string">'ENOENT'</span>) {
|
||
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">'myfile does not exist'</span>);
|
||
<span class="hljs-keyword">return</span>;
|
||
}
|
||
|
||
<span class="hljs-keyword">throw</span> err;
|
||
}
|
||
|
||
readMyData(fd);
|
||
});</code></pre>
|
||
<p>The "not recommended" examples above check for existence and then use the
|
||
file; the "recommended" examples are better because they use the file directly
|
||
and handle the error, if any.</p>
|
||
<p>In general, check for the existence of a file only if the file won’t be
|
||
used directly, for example when its existence is a signal from another
|
||
process.</p>
|
||
<h2><code>fs.existsSync(path)</code><span><a class="mark" href="#fs_fs_existssync_path" id="fs_fs_existssync_path">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
|
||
</ul>
|
||
<p>Returns <code>true</code> if the path exists, <code>false</code> otherwise.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="fs.html#fs_fs_exists_path_callback"><code>fs.exists()</code></a>.</p>
|
||
<p><code>fs.exists()</code> is deprecated, but <code>fs.existsSync()</code> is not. The <code>callback</code>
|
||
parameter to <code>fs.exists()</code> accepts parameters that are inconsistent with other
|
||
Node.js callbacks. <code>fs.existsSync()</code> does not use a callback.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">if</span> (fs.existsSync(<span class="hljs-string">'/etc/passwd'</span>)) {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The path exists.'</span>);
|
||
}</code></pre>
|
||
<h2><code>fs.fchmod(fd, mode, callback)</code><span><a class="mark" href="#fs_fs_fchmod_fd_mode_callback" id="fs_fs_fchmod_fd_mode_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.4.7</td>
|
||
<td><p><span>Added in: v0.4.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fchmod.2.html"><code>fchmod(2)</code></a>. No arguments other than a possible exception
|
||
are given to the completion callback.</p>
|
||
<h2><code>fs.fchmodSync(fd, mode)</code><span><a class="mark" href="#fs_fs_fchmodsync_fd_mode" id="fs_fs_fchmodsync_fd_mode">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.4.7</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/fchmod.2.html"><code>fchmod(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.fchown(fd, uid, gid, callback)</code><span><a class="mark" href="#fs_fs_fchown_fd_uid_gid_callback" id="fs_fs_fchown_fd_uid_gid_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.4.7</td>
|
||
<td><p><span>Added in: v0.4.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fchown.2.html"><code>fchown(2)</code></a>. No arguments other than a possible exception are given
|
||
to the completion callback.</p>
|
||
<h2><code>fs.fchownSync(fd, uid, gid)</code><span><a class="mark" href="#fs_fs_fchownsync_fd_uid_gid" id="fs_fs_fchownsync_fd_uid_gid">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.4.7</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/fchown.2.html"><code>fchown(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.fdatasync(fd, callback)</code><span><a class="mark" href="#fs_fs_fdatasync_fd_callback" id="fs_fs_fdatasync_fd_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.96</td>
|
||
<td><p><span>Added in: v0.1.96</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a>. No arguments other than a possible exception are
|
||
given to the completion callback.</p>
|
||
<h2><code>fs.fdatasyncSync(fd)</code><span><a class="mark" href="#fs_fs_fdatasyncsync_fd" id="fs_fs_fdatasyncsync_fd">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.96</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.fstat(fd[, options], callback)</code><span><a class="mark" href="#fs_fs_fstat_fd_options_callback" id="fs_fs_fstat_fd_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.95</td>
|
||
<td><p><span>Added in: v0.1.95</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fstat.2.html"><code>fstat(2)</code></a>. The callback gets two arguments <code>(err, stats)</code> where
|
||
<code>stats</code> is an <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object. <code>fstat()</code> is identical to <a href="fs.html#fs_fs_stat_path_options_callback"><code>stat()</code></a>,
|
||
except that the file to be stat-ed is specified by the file descriptor <code>fd</code>.</p>
|
||
<h2><code>fs.fstatSync(fd[, options])</code><span><a class="mark" href="#fs_fs_fstatsync_fd_options" id="fs_fs_fstatsync_fd_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v0.1.95</td>
|
||
<td><p><span>Added in: v0.1.95</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/fstat.2.html"><code>fstat(2)</code></a>.</p>
|
||
<h2><code>fs.fsync(fd, callback)</code><span><a class="mark" href="#fs_fs_fsync_fd_callback" id="fs_fs_fsync_fd_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.96</td>
|
||
<td><p><span>Added in: v0.1.96</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a>. No arguments other than a possible exception are given
|
||
to the completion callback.</p>
|
||
<h2><code>fs.fsyncSync(fd)</code><span><a class="mark" href="#fs_fs_fsyncsync_fd" id="fs_fs_fsyncsync_fd">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.96</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.ftruncate(fd[, len], callback)</code><span><a class="mark" href="#fs_fs_ftruncate_fd_len_callback" id="fs_fs_ftruncate_fd_len_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.8.6</td>
|
||
<td><p><span>Added in: v0.8.6</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/ftruncate.2.html"><code>ftruncate(2)</code></a>. No arguments other than a possible exception are
|
||
given to the completion callback.</p>
|
||
<p>If the file referred to by the file descriptor was larger than <code>len</code> bytes, only
|
||
the first <code>len</code> bytes will be retained in the file.</p>
|
||
<p>For example, the following program retains only the first four bytes of the
|
||
file:</p>
|
||
<pre><code class="language-js"><span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>));
|
||
<span class="hljs-comment">// Prints: Node.js</span>
|
||
|
||
<span class="hljs-comment">// get the file descriptor of the file to be truncated</span>
|
||
<span class="hljs-keyword">const</span> fd = fs.openSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>);
|
||
|
||
<span class="hljs-comment">// Truncate the file to first four bytes</span>
|
||
fs.ftruncate(fd, <span class="hljs-number">4</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
assert.ifError(err);
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>));
|
||
});
|
||
<span class="hljs-comment">// Prints: Node</span></code></pre>
|
||
<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the
|
||
extended part is filled with null bytes (<code>'\0'</code>):</p>
|
||
<pre><code class="language-js"><span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>));
|
||
<span class="hljs-comment">// Prints: Node.js</span>
|
||
|
||
<span class="hljs-comment">// get the file descriptor of the file to be truncated</span>
|
||
<span class="hljs-keyword">const</span> fd = fs.openSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>);
|
||
|
||
<span class="hljs-comment">// Truncate the file to 10 bytes, whereas the actual size is 7 bytes</span>
|
||
fs.ftruncate(fd, <span class="hljs-number">10</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
assert.ifError(err);
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>));
|
||
});
|
||
<span class="hljs-comment">// Prints: <Buffer 4e 6f 64 65 2e 6a 73 00 00 00></span>
|
||
<span class="hljs-comment">// ('Node.js\0\0\0' in UTF8)</span></code></pre>
|
||
<p>The last three bytes are null bytes (<code>'\0'</code>), to compensate the over-truncation.</p>
|
||
<h2><code>fs.ftruncateSync(fd[, len])</code><span><a class="mark" href="#fs_fs_ftruncatesync_fd_len" id="fs_fs_ftruncatesync_fd_len">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.8.6</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
</ul>
|
||
<p>Returns <code>undefined</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate()</code></a>.</p>
|
||
<h2><code>fs.futimes(fd, atime, mtime, callback)</code><span><a class="mark" href="#fs_fs_futimes_fd_atime_mtime_callback" id="fs_fs_futimes_fd_atime_mtime_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v4.1.0</td>
|
||
<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr>
|
||
<tr><td>v0.4.2</td>
|
||
<td><p><span>Added in: v0.4.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Change the file system timestamps of the object referenced by the supplied file
|
||
descriptor. See <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p>
|
||
<p>This function does not work on AIX versions before 7.1, it will return the
|
||
error <code>UV_ENOSYS</code>.</p>
|
||
<h2><code>fs.futimesSync(fd, atime, mtime)</code><span><a class="mark" href="#fs_fs_futimessync_fd_atime_mtime" id="fs_fs_futimessync_fd_atime_mtime">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v4.1.0</td>
|
||
<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr>
|
||
<tr><td>v0.4.2</td>
|
||
<td><p><span>Added in: v0.4.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>Synchronous version of <a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes()</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.lchmod(path, mode, callback)</code><span><a class="mark" href="#fs_fs_lchmod_path_mode_callback" id="fs_fs_lchmod_path_mode_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.4.7</td>
|
||
<td><p><span>Deprecated since: v0.4.7</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2"><code>lchmod(2)</code></a>. No arguments other than a possible exception
|
||
are given to the completion callback.</p>
|
||
<p>Only available on macOS.</p>
|
||
<h2><code>fs.lchmodSync(path, mode)</code><span><a class="mark" href="#fs_fs_lchmodsync_path_mode" id="fs_fs_lchmodsync_path_mode">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Deprecated since: v0.4.7</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2"><code>lchmod(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.lchown(path, uid, gid, callback)</code><span><a class="mark" href="#fs_fs_lchown_path_uid_gid_callback" id="fs_fs_lchown_path_uid_gid_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.6.0</td>
|
||
<td><p>This API is no longer deprecated.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.4.7</td>
|
||
<td><p>Documentation-only deprecation.</p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/lchown.2.html"><code>lchown(2)</code></a>. No arguments other than a possible exception are given
|
||
to the completion callback.</p>
|
||
<h2><code>fs.lchownSync(path, uid, gid)</code><span><a class="mark" href="#fs_fs_lchownsync_path_uid_gid" id="fs_fs_lchownsync_path_uid_gid">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.6.0</td>
|
||
<td><p>This API is no longer deprecated.</p></td></tr>
|
||
<tr><td>v0.4.7</td>
|
||
<td><p>Documentation-only deprecation.</p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/lchown.2.html"><code>lchown(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.lutimes(path, atime, mtime, callback)</code><span><a class="mark" href="#fs_fs_lutimes_path_atime_mtime_callback" id="fs_fs_lutimes_path_atime_mtime_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.19.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Changes the access and modification times of a file in the same way as
|
||
<a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>, with the difference that if the path refers to a symbolic
|
||
link, then the link is not dereferenced: instead, the timestamps of the
|
||
symbolic link itself are changed.</p>
|
||
<p>No arguments other than a possible exception are given to the completion
|
||
callback.</p>
|
||
<h2><code>fs.lutimesSync(path, atime, mtime)</code><span><a class="mark" href="#fs_fs_lutimessync_path_atime_mtime" id="fs_fs_lutimessync_path_atime_mtime">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.19.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>Change the file system timestamps of the symbolic link referenced by <code>path</code>.
|
||
Returns <code>undefined</code>, or throws an exception when parameters are incorrect or
|
||
the operation fails. This is the synchronous version of <a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes()</code></a>.</p>
|
||
<h2><code>fs.link(existingPath, newPath, callback)</code><span><a class="mark" href="#fs_fs_link_existingpath_newpath_callback" id="fs_fs_link_existingpath_newpath_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>existingPath</code> and <code>newPath</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>existingPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a>. No arguments other than a possible exception are given to
|
||
the completion callback.</p>
|
||
<h2><code>fs.linkSync(existingPath, newPath)</code><span><a class="mark" href="#fs_fs_linksync_existingpath_newpath" id="fs_fs_linksync_existingpath_newpath">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>existingPath</code> and <code>newPath</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>existingPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.lstat(path[, options], callback)</code><span><a class="mark" href="#fs_fs_lstat_path_options_callback" id="fs_fs_lstat_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.30</td>
|
||
<td><p><span>Added in: v0.1.30</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a>. The callback gets two arguments <code>(err, stats)</code> where
|
||
<code>stats</code> is a <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object. <code>lstat()</code> is identical to <code>stat()</code>,
|
||
except that if <code>path</code> is a symbolic link, then the link itself is stat-ed,
|
||
not the file that it refers to.</p>
|
||
<h2><code>fs.lstatSync(path[, options])</code><span><a class="mark" href="#fs_fs_lstatsync_path_options" id="fs_fs_lstatsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.30</td>
|
||
<td><p><span>Added in: v0.1.30</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a>.</p>
|
||
<h2><code>fs.mkdir(path[, options], callback)</code><span><a class="mark" href="#fs_fs_mkdir_path_options_callback" id="fs_fs_mkdir_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>In <code>recursive</code> mode, the callback now receives the first created path as an argument.</p></td></tr>
|
||
<tr><td>v10.12.0</td>
|
||
<td><p>The second argument can now be an <code>options</code> object with <code>recursive</code> and <code>mode</code> properties.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.8</td>
|
||
<td><p><span>Added in: v0.1.8</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a>
|
||
<ul>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Not supported on Windows. <strong>Default:</strong> <code>0o777</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously creates a directory.</p>
|
||
<p>The callback is given a possible exception and, if <code>recursive</code> is <code>true</code>, the
|
||
first directory path created, <code>(err, [path])</code>.</p>
|
||
<p>The optional <code>options</code> argument can be an integer specifying mode (permission
|
||
and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code>
|
||
property indicating whether parent directories should be created. Calling
|
||
<code>fs.mkdir()</code> when <code>path</code> is a directory that exists results in an error only
|
||
when <code>recursive</code> is false.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist.</span>
|
||
fs.mkdir(<span class="hljs-string">'/tmp/a/apple'</span>, { <span class="hljs-attr">recursive</span>: <span class="hljs-literal">true</span> }, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
});</code></pre>
|
||
<p>On Windows, using <code>fs.mkdir()</code> on the root directory even with recursion will
|
||
result in an error:</p>
|
||
<pre><code class="language-js">fs.mkdir(<span class="hljs-string">'/'</span>, { <span class="hljs-attr">recursive</span>: <span class="hljs-literal">true</span> }, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-comment">// => [Error: EPERM: operation not permitted, mkdir 'C:\']</span>
|
||
});</code></pre>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"><code>mkdir(2)</code></a>.</p>
|
||
<h2><code>fs.mkdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_mkdirsync_path_options" id="fs_fs_mkdirsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>In <code>recursive</code> mode, the first created path is returned now.</p></td></tr>
|
||
<tr><td>v10.12.0</td>
|
||
<td><p>The second argument can now be an <code>options</code> object with <code>recursive</code> and <code>mode</code> properties.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a>
|
||
<ul>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Not supported on Windows. <strong>Default:</strong> <code>0o777</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li>
|
||
</ul>
|
||
<p>Synchronously creates a directory. Returns <code>undefined</code>, or if <code>recursive</code> is
|
||
<code>true</code>, the first directory path created.
|
||
This is the synchronous version of <a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir()</code></a>.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"><code>mkdir(2)</code></a>.</p>
|
||
<h2><code>fs.mkdtemp(prefix[, options], callback)</code><span><a class="mark" href="#fs_fs_mkdtemp_prefix_options_callback" id="fs_fs_mkdtemp_prefix_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v6.2.1</td>
|
||
<td><p>The <code>callback</code> parameter is optional now.</p></td></tr>
|
||
<tr><td>v5.10.0</td>
|
||
<td><p><span>Added in: v5.10.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>directory</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Creates a unique temporary directory.</p>
|
||
<p>Generates six random characters to be appended behind a required
|
||
<code>prefix</code> to create a unique temporary directory. Due to platform
|
||
inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some platforms,
|
||
notably the BSDs, can return more than six random characters, and replace
|
||
trailing <code>X</code> characters in <code>prefix</code> with random characters.</p>
|
||
<p>The created directory path is passed as a string to the callback's second
|
||
parameter.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use.</p>
|
||
<pre><code class="language-js">fs.mkdtemp(path.join(os.tmpdir(), <span class="hljs-string">'foo-'</span>), <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(directory);
|
||
<span class="hljs-comment">// Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2</span>
|
||
});</code></pre>
|
||
<p>The <code>fs.mkdtemp()</code> method will append the six randomly selected characters
|
||
directly to the <code>prefix</code> string. For instance, given a directory <code>/tmp</code>, if the
|
||
intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the <code>prefix</code>
|
||
must end with a trailing platform-specific path separator
|
||
(<code>require('path').sep</code>).</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// The parent directory for the new temporary directory</span>
|
||
<span class="hljs-keyword">const</span> tmpDir = os.tmpdir();
|
||
|
||
<span class="hljs-comment">// This method is *INCORRECT*:</span>
|
||
fs.mkdtemp(tmpDir, <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(directory);
|
||
<span class="hljs-comment">// Will print something similar to `/tmpabc123`.</span>
|
||
<span class="hljs-comment">// A new temporary directory is created at the file system root</span>
|
||
<span class="hljs-comment">// rather than *within* the /tmp directory.</span>
|
||
});
|
||
|
||
<span class="hljs-comment">// This method is *CORRECT*:</span>
|
||
<span class="hljs-keyword">const</span> { sep } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'path'</span>);
|
||
fs.mkdtemp(<span class="hljs-string">`<span class="hljs-subst">${tmpDir}</span><span class="hljs-subst">${sep}</span>`</span>, <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(directory);
|
||
<span class="hljs-comment">// Will print something similar to `/tmp/abc123`.</span>
|
||
<span class="hljs-comment">// A new temporary directory is created within</span>
|
||
<span class="hljs-comment">// the /tmp directory.</span>
|
||
});</code></pre>
|
||
<h2><code>fs.mkdtempSync(prefix[, options])</code><span><a class="mark" href="#fs_fs_mkdtempsync_prefix_options" id="fs_fs_mkdtempsync_prefix_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v5.10.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Returns the created directory path.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp()</code></a>.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use.</p>
|
||
<h2><code>fs.open(path[, flags[, mode]], callback)</code><span><a class="mark" href="#fs_fs_open_path_flags_mode_callback" id="fs_fs_open_path_flags_mode_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v11.1.0</td>
|
||
<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr>
|
||
<tr><td>v9.9.0</td>
|
||
<td><p>The <code>as</code> and <code>as+</code> modes are supported now.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.
|
||
<strong>Default:</strong> <code>'r'</code>.</li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code> (readable and writable)</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous file open. See <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a>.</p>
|
||
<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the file was
|
||
created. On Windows, only the write permission can be manipulated; see
|
||
<a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p>
|
||
<p>The callback gets two arguments <code>(err, fd)</code>.</p>
|
||
<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented
|
||
by <a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a>. Under NTFS, if the filename contains
|
||
a colon, Node.js will open a file system stream, as described by
|
||
<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p>
|
||
<p>Functions based on <code>fs.open()</code> exhibit this behavior as well:
|
||
<code>fs.writeFile()</code>, <code>fs.readFile()</code>, etc.</p>
|
||
<h2><code>fs.opendir(path[, options], callback)</code><span><a class="mark" href="#fs_fs_opendir_path_options_callback" id="fs_fs_opendir_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr>
|
||
<tr><td>v12.12.0</td>
|
||
<td><p><span>Added in: v12.12.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>bufferSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of directory entries that are buffered
|
||
internally when reading from the directory. Higher values lead to better
|
||
performance but higher memory usage. <strong>Default:</strong> <code>32</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>dir</code> <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p>
|
||
<p>Creates an <a href="#fs_class_fs_dir"><code>fs.Dir</code></a>, which contains all further functions for reading from
|
||
and cleaning up the directory.</p>
|
||
<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the
|
||
directory and subsequent read operations.</p>
|
||
<h2><code>fs.opendirSync(path[, options])</code><span><a class="mark" href="#fs_fs_opendirsync_path_options" id="fs_fs_opendirsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr>
|
||
<tr><td>v12.12.0</td>
|
||
<td><p><span>Added in: v12.12.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>bufferSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of directory entries that are buffered
|
||
internally when reading from the directory. Higher values lead to better
|
||
performance but higher memory usage. <strong>Default:</strong> <code>32</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li>
|
||
</ul>
|
||
<p>Synchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p>
|
||
<p>Creates an <a href="#fs_class_fs_dir"><code>fs.Dir</code></a>, which contains all further functions for reading from
|
||
and cleaning up the directory.</p>
|
||
<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the
|
||
directory and subsequent read operations.</p>
|
||
<h2><code>fs.openSync(path[, flags, mode])</code><span><a class="mark" href="#fs_fs_opensync_path_flags_mode" id="fs_fs_opensync_path_flags_mode">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v11.1.0</td>
|
||
<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr>
|
||
<tr><td>v9.9.0</td>
|
||
<td><p>The <code>as</code> and <code>as+</code> modes are supported now.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> <strong>Default:</strong> <code>'r'</code>.
|
||
See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.</li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
||
</ul>
|
||
<p>Returns an integer representing the file descriptor.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a>.</p>
|
||
<h2><code>fs.read(fd, buffer, offset, length, position, callback)</code><span><a class="mark" href="#fs_fs_read_fd_buffer_offset_length_position_callback" id="fs_fs_read_fd_buffer_offset_length_position_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code>, or a <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v7.4.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Read data from the file specified by <code>fd</code>.</p>
|
||
<p><code>buffer</code> is the buffer that the data (read from the fd) will be written to.</p>
|
||
<p><code>offset</code> is the offset in the buffer to start writing at.</p>
|
||
<p><code>length</code> is an integer specifying the number of bytes to read.</p>
|
||
<p><code>position</code> is an argument specifying where to begin reading from in the file.
|
||
If <code>position</code> is <code>null</code>, data will be read from the current file position,
|
||
and the file position will be updated.
|
||
If <code>position</code> is an integer, the file position will remain unchanged.</p>
|
||
<p>The callback is given the three arguments, <code>(err, bytesRead, buffer)</code>.</p>
|
||
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
||
a <code>Promise</code> for an <code>Object</code> with <code>bytesRead</code> and <code>buffer</code> properties.</p>
|
||
<h2><code>fs.read(fd, [options,] callback)</code><span><a class="mark" href="#fs_fs_read_fd_options_callback" id="fs_fs_read_fd_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>Options object can be passed in to make Buffer, offset, length and position optional</p></td></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p><span>Added in: v12.17.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>buffer.length</code></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Similar to the above <code>fs.read</code> function, this version takes an optional <code>options</code> object.
|
||
If no <code>options</code> object is specified, it will default with the above values.</p>
|
||
<h2><code>fs.readdir(path[, options], callback)</code><span><a class="mark" href="#fs_fs_readdir_path_options_callback" id="fs_fs_readdir_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>New option <code>withFileTypes</code> was added.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>The <code>options</code> parameter was added.</p></td></tr>
|
||
<tr><td>v0.1.8</td>
|
||
<td><p><span>Added in: v0.1.8</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>withFileTypes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>files</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer[]></a> | <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent[]></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a>. Reads the contents of a directory.
|
||
The callback gets two arguments <code>(err, files)</code> where <code>files</code> is an array of
|
||
the names of the files in the directory excluding <code>'.'</code> and <code>'..'</code>.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the filenames passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the filenames returned will be passed as <code>Buffer</code> objects.</p>
|
||
<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the <code>files</code> array will contain
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a> objects.</p>
|
||
<h2><code>fs.readdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_readdirsync_path_options" id="fs_fs_readdirsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>New option <code>withFileTypes</code> was added.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>withFileTypes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer[]></a> | <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent[]></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a>.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the filenames returned. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the filenames returned will be passed as <code>Buffer</code> objects.</p>
|
||
<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the result will contain
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a> objects.</p>
|
||
<h2><code>fs.readFile(path[, options], callback)</code><span><a class="mark" href="#fs_fs_readfile_path_options_callback" id="fs_fs_readfile_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v5.1.0</td>
|
||
<td><p>The <code>callback</code> will always be called with <code>null</code> as the <code>error</code> parameter in case of success.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.1.29</td>
|
||
<td><p><span>Added in: v0.1.29</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> filename or file descriptor</li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'r'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously reads the entire contents of a file.</p>
|
||
<pre><code class="language-js">fs.readFile(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(data);
|
||
});</code></pre>
|
||
<p>The callback is passed two arguments <code>(err, data)</code>, where <code>data</code> is the
|
||
contents of the file.</p>
|
||
<p>If no encoding is specified, then the raw buffer is returned.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding:</p>
|
||
<pre><code class="language-js">fs.readFile(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre>
|
||
<p>When the path is a directory, the behavior of <code>fs.readFile()</code> and
|
||
<a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync()</code></a> is platform-specific. On macOS, Linux, and Windows, an
|
||
error will be returned. On FreeBSD, a representation of the directory's contents
|
||
will be returned.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// macOS, Linux, and Windows</span>
|
||
fs.readFile(<span class="hljs-string">'<directory>'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> {
|
||
<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span>
|
||
});
|
||
|
||
<span class="hljs-comment">// FreeBSD</span>
|
||
fs.readFile(<span class="hljs-string">'<directory>'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> {
|
||
<span class="hljs-comment">// => null, <data></span>
|
||
});</code></pre>
|
||
<p>The <code>fs.readFile()</code> function buffers the entire file. To minimize memory costs,
|
||
when possible prefer streaming via <code>fs.createReadStream()</code>.</p>
|
||
<h3>File descriptors<span><a class="mark" href="#fs_file_descriptors_1" id="fs_file_descriptors_1">#</a></span></h3>
|
||
<ol>
|
||
<li>Any specified file descriptor has to support reading.</li>
|
||
<li>If a file descriptor is specified as the <code>path</code>, it will not be closed
|
||
automatically.</li>
|
||
<li>The reading will begin at the current position. For example, if the file
|
||
already had <code>'Hello World</code>' and six bytes are read with the file descriptor,
|
||
the call to <code>fs.readFile()</code> with the same file descriptor, would give
|
||
<code>'World'</code>, rather than <code>'Hello World'</code>.</li>
|
||
</ol>
|
||
<h2><code>fs.readFileSync(path[, options])</code><span><a class="mark" href="#fs_fs_readfilesync_path_options" id="fs_fs_readfilesync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.1.8</td>
|
||
<td><p><span>Added in: v0.1.8</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> filename or file descriptor</li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'r'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>Returns the contents of the <code>path</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile()</code></a>.</p>
|
||
<p>If the <code>encoding</code> option is specified then this function returns a
|
||
string. Otherwise it returns a buffer.</p>
|
||
<p>Similar to <a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile()</code></a>, when the path is a directory, the behavior of
|
||
<code>fs.readFileSync()</code> is platform-specific.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// macOS, Linux, and Windows</span>
|
||
fs.readFileSync(<span class="hljs-string">'<directory>'</span>);
|
||
<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span>
|
||
|
||
<span class="hljs-comment">// FreeBSD</span>
|
||
fs.readFileSync(<span class="hljs-string">'<directory>'</span>); <span class="hljs-comment">// => <data></span></code></pre>
|
||
<h2><code>fs.readlink(path[, options], callback)</code><span><a class="mark" href="#fs_fs_readlink_path_options_callback" id="fs_fs_readlink_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>linkString</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a>. The callback gets two arguments <code>(err, linkString)</code>.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the link path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the link path returned will be passed as a <code>Buffer</code> object.</p>
|
||
<h2><code>fs.readlinkSync(path[, options])</code><span><a class="mark" href="#fs_fs_readlinksync_path_options" id="fs_fs_readlinksync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a>. Returns the symbolic link's string value.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the link path returned will be passed as a <code>Buffer</code> object.</p>
|
||
<h2><code>fs.readSync(fd, buffer, offset, length, position)</code><span><a class="mark" href="#fs_fs_readsync_fd_buffer_offset_length_position" id="fs_fs_readsync_fd_buffer_offset_length_position">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
||
</ul>
|
||
<p>Returns the number of <code>bytesRead</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p>
|
||
<h2><code>fs.readSync(fd, buffer, [options])</code><span><a class="mark" href="#fs_fs_readsync_fd_buffer_options" id="fs_fs_readsync_fd_buffer_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p>Options object can be passed in to make offset, length and position optional</p></td></tr>
|
||
<tr><td>v12.17.0</td>
|
||
<td><p><span>Added in: v12.17.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>buffer.length</code></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
|
||
</ul>
|
||
<p>Returns the number of <code>bytesRead</code>.</p>
|
||
<p>Similar to the above <code>fs.readSync</code> function, this version takes an optional <code>options</code> object.
|
||
If no <code>options</code> object is specified, it will default with the above values.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p>
|
||
<h2><code>fs.readv(fd, buffers[, position], callback)</code><span><a class="mark" href="#fs_fs_readv_fd_buffers_position_callback" id="fs_fs_readv_fd_buffers_position_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.17.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Read from a file specified by <code>fd</code> and write to an array of <code>ArrayBufferView</code>s
|
||
using <code>readv()</code>.</p>
|
||
<p><code>position</code> is the offset from the beginning of the file from where data
|
||
should be read. If <code>typeof position !== 'number'</code>, the data will be read
|
||
from the current position.</p>
|
||
<p>The callback will be given three arguments: <code>err</code>, <code>bytesRead</code>, and
|
||
<code>buffers</code>. <code>bytesRead</code> is how many bytes were read from the file.</p>
|
||
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
||
a <code>Promise</code> for an <code>Object</code> with <code>bytesRead</code> and <code>buffers</code> properties.</p>
|
||
<h2><code>fs.readvSync(fd, buffers[, position])</code><span><a class="mark" href="#fs_fs_readvsync_fd_buffers_position" id="fs_fs_readvsync_fd_buffers_position">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.17.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of bytes read.</li>
|
||
</ul>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv()</code></a>.</p>
|
||
<h2><code>fs.realpath(path[, options], callback)</code><span><a class="mark" href="#fs_fs_realpath_path_options_callback" id="fs_fs_realpath_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p>Pipe/Socket resolve support was added.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v6.4.0</td>
|
||
<td><p>Calling <code>realpath</code> now works again for various edge cases on Windows.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>The <code>cache</code> parameter was removed.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>resolvedPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously computes the canonical pathname by resolving <code>.</code>, <code>..</code> and
|
||
symbolic links.</p>
|
||
<p>A canonical pathname is not necessarily unique. Hard links and bind mounts can
|
||
expose a file system entity through many pathnames.</p>
|
||
<p>This function behaves like <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>, with some exceptions:</p>
|
||
<ol>
|
||
<li>
|
||
<p>No case conversion is performed on case-insensitive file systems.</p>
|
||
</li>
|
||
<li>
|
||
<p>The maximum number of symbolic links is platform-independent and generally
|
||
(much) higher than what the native <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a> implementation supports.</p>
|
||
</li>
|
||
</ol>
|
||
<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>. May use <code>process.cwd</code>
|
||
to resolve relative paths.</p>
|
||
<p>Only paths that can be converted to UTF8 strings are supported.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the path returned will be passed as a <code>Buffer</code> object.</p>
|
||
<p>If <code>path</code> resolves to a socket or a pipe, the function will return a system
|
||
dependent name for that object.</p>
|
||
<h2><code>fs.realpath.native(path[, options], callback)</code><span><a class="mark" href="#fs_fs_realpath_native_path_options_callback" id="fs_fs_realpath_native_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v9.2.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>resolvedPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p>
|
||
<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>.</p>
|
||
<p>Only paths that can be converted to UTF8 strings are supported.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the path returned will be passed as a <code>Buffer</code> object.</p>
|
||
<p>On Linux, when Node.js is linked against musl libc, the procfs file system must
|
||
be mounted on <code>/proc</code> in order for this function to work. Glibc does not have
|
||
this restriction.</p>
|
||
<h2><code>fs.realpathSync(path[, options])</code><span><a class="mark" href="#fs_fs_realpathsync_path_options" id="fs_fs_realpathsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p>Pipe/Socket resolve support was added.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v6.4.0</td>
|
||
<td><p>Calling <code>realpathSync</code> now works again for various edge cases on Windows.</p></td></tr>
|
||
<tr><td>v6.0.0</td>
|
||
<td><p>The <code>cache</code> parameter was removed.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>Returns the resolved pathname.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath()</code></a>.</p>
|
||
<h2><code>fs.realpathSync.native(path[, options])</code><span><a class="mark" href="#fs_fs_realpathsync_native_path_options" id="fs_fs_realpathsync_native_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v9.2.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p>
|
||
<p>Only paths that can be converted to UTF8 strings are supported.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the path returned. If the <code>encoding</code> is set to <code>'buffer'</code>,
|
||
the path returned will be passed as a <code>Buffer</code> object.</p>
|
||
<p>On Linux, when Node.js is linked against musl libc, the procfs file system must
|
||
be mounted on <code>/proc</code> in order for this function to work. Glibc does not have
|
||
this restriction.</p>
|
||
<h2><code>fs.rename(oldPath, newPath, callback)</code><span><a class="mark" href="#fs_fs_rename_oldpath_newpath_callback" id="fs_fs_rename_oldpath_newpath_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>oldPath</code> and <code>newPath</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>oldPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously rename file at <code>oldPath</code> to the pathname provided
|
||
as <code>newPath</code>. In the case that <code>newPath</code> already exists, it will
|
||
be overwritten. If there is a directory at <code>newPath</code>, an error will
|
||
be raised instead. No arguments other than a possible exception are
|
||
given to the completion callback.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a>.</p>
|
||
<pre><code class="language-js">fs.rename(<span class="hljs-string">'oldFile.txt'</span>, <span class="hljs-string">'newFile.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Rename complete!'</span>);
|
||
});</code></pre>
|
||
<h2><code>fs.renameSync(oldPath, newPath)</code><span><a class="mark" href="#fs_fs_renamesync_oldpath_newpath" id="fs_fs_renamesync_oldpath_newpath">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>oldPath</code> and <code>newPath</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>oldPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.rmdir(path[, options], callback)</code><span><a class="mark" href="#fs_fs_rmdir_path_options_callback" id="fs_fs_rmdir_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>maxBusyTries</code> option is renamed to <code>maxRetries</code>, and its default is 0. The <code>emfileWait</code> option has been removed, and <code>EMFILE</code> errors use the same retry logic as other errors. The <code>retryDelay</code> option is now supported. <code>ENFILE</code> errors are now retried.</p></td></tr>
|
||
<tr><td>v12.10.0</td>
|
||
<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<p></p><div class="api_stability api_stability_1"><a href="documentation.html#documentation_stability_index">Stability: 1</a> - Recursive removal is experimental.</div><p></p>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>maxRetries</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> If an <code>EBUSY</code>, <code>EMFILE</code>, <code>ENFILE</code>, <code>ENOTEMPTY</code>, or
|
||
<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear
|
||
backoff wait of <code>retryDelay</code> ms longer on each try. This option represents the
|
||
number of retries. This option is ignored if the <code>recursive</code> option is not
|
||
<code>true</code>. <strong>Default:</strong> <code>0</code>.</li>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, perform a recursive directory removal. In
|
||
recursive mode, errors are not reported if <code>path</code> does not exist, and
|
||
operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li>
|
||
<li><code>retryDelay</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The amount of time in milliseconds to wait between
|
||
retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>.
|
||
<strong>Default:</strong> <code>100</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"><code>rmdir(2)</code></a>. No arguments other than a possible exception are given
|
||
to the completion callback.</p>
|
||
<p>Using <code>fs.rmdir()</code> on a file (not a directory) results in an <code>ENOENT</code> error on
|
||
Windows and an <code>ENOTDIR</code> error on POSIX.</p>
|
||
<h2><code>fs.rmdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_rmdirsync_path_options" id="fs_fs_rmdirsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>maxBusyTries</code> option is renamed to <code>maxRetries</code>, and its default is 0. The <code>emfileWait</code> option has been removed, and <code>EMFILE</code> errors use the same retry logic as other errors. The <code>retryDelay</code> option is now supported. <code>ENFILE</code> errors are now retried.</p></td></tr>
|
||
<tr><td>v12.10.0</td>
|
||
<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<p></p><div class="api_stability api_stability_1"><a href="documentation.html#documentation_stability_index">Stability: 1</a> - Recursive removal is experimental.</div><p></p>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>maxRetries</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> If an <code>EBUSY</code>, <code>EMFILE</code>, <code>ENFILE</code>, <code>ENOTEMPTY</code>, or
|
||
<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear
|
||
backoff wait of <code>retryDelay</code> ms longer on each try. This option represents the
|
||
number of retries. This option is ignored if the <code>recursive</code> option is not
|
||
<code>true</code>. <strong>Default:</strong> <code>0</code>.</li>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, perform a recursive directory removal. In
|
||
recursive mode, errors are not reported if <code>path</code> does not exist, and
|
||
operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li>
|
||
<li><code>retryDelay</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The amount of time in milliseconds to wait between
|
||
retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>.
|
||
<strong>Default:</strong> <code>100</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"><code>rmdir(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<p>Using <code>fs.rmdirSync()</code> on a file (not a directory) results in an <code>ENOENT</code> error
|
||
on Windows and an <code>ENOTDIR</code> error on POSIX.</p>
|
||
<h2><code>fs.stat(path[, options], callback)</code><span><a class="mark" href="#fs_fs_stat_path_options_callback" id="fs_fs_stat_path_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/stat.2.html"><code>stat(2)</code></a>. The callback gets two arguments <code>(err, stats)</code> where
|
||
<code>stats</code> is an <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object.</p>
|
||
<p>In case of an error, the <code>err.code</code> will be one of <a href="errors.html#errors_common_system_errors">Common System Errors</a>.</p>
|
||
<p>Using <code>fs.stat()</code> to check for the existence of a file before calling
|
||
<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended.
|
||
Instead, user code should open/read/write the file directly and handle the
|
||
error raised if the file is not available.</p>
|
||
<p>To check if a file exists without manipulating it afterwards, <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a>
|
||
is recommended.</p>
|
||
<p>For example, given the following directory structure:</p>
|
||
<pre><code class="language-text">- txtDir
|
||
-- file.txt
|
||
- app.js</code></pre>
|
||
<p>The next program will check for the stats of the given paths:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">const</span> pathsToCheck = [<span class="hljs-string">'./txtDir'</span>, <span class="hljs-string">'./txtDir/file.txt'</span>];
|
||
|
||
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i < pathsToCheck.length; i++) {
|
||
fs.stat(pathsToCheck[i], <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">err, stats</span>) </span>{
|
||
<span class="hljs-built_in">console</span>.log(stats.isDirectory());
|
||
<span class="hljs-built_in">console</span>.log(stats);
|
||
});
|
||
}</code></pre>
|
||
<p>The resulting output will resemble:</p>
|
||
<pre><code class="language-console">true
|
||
Stats {
|
||
dev: 16777220,
|
||
mode: 16877,
|
||
nlink: 3,
|
||
uid: 501,
|
||
gid: 20,
|
||
rdev: 0,
|
||
blksize: 4096,
|
||
ino: 14214262,
|
||
size: 96,
|
||
blocks: 0,
|
||
atimeMs: 1561174653071.963,
|
||
mtimeMs: 1561174614583.3518,
|
||
ctimeMs: 1561174626623.5366,
|
||
birthtimeMs: 1561174126937.2893,
|
||
atime: 2019-06-22T03:37:33.072Z,
|
||
mtime: 2019-06-22T03:36:54.583Z,
|
||
ctime: 2019-06-22T03:37:06.624Z,
|
||
birthtime: 2019-06-22T03:28:46.937Z
|
||
}
|
||
false
|
||
Stats {
|
||
dev: 16777220,
|
||
mode: 33188,
|
||
nlink: 1,
|
||
uid: 501,
|
||
gid: 20,
|
||
rdev: 0,
|
||
blksize: 4096,
|
||
ino: 14214074,
|
||
size: 8,
|
||
blocks: 8,
|
||
atimeMs: 1561174616618.8555,
|
||
mtimeMs: 1561174614584,
|
||
ctimeMs: 1561174614583.8145,
|
||
birthtimeMs: 1561174007710.7478,
|
||
atime: 2019-06-22T03:36:56.619Z,
|
||
mtime: 2019-06-22T03:36:54.584Z,
|
||
ctime: 2019-06-22T03:36:54.584Z,
|
||
birthtime: 2019-06-22T03:26:47.711Z
|
||
}</code></pre>
|
||
<h2><code>fs.statSync(path[, options])</code><span><a class="mark" href="#fs_fs_statsync_path_options" id="fs_fs_statsync_path_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/stat.2.html"><code>stat(2)</code></a>.</p>
|
||
<h2><code>fs.symlink(target, path[, type], callback)</code><span><a class="mark" href="#fs_fs_symlink_target_path_type_callback" id="fs_fs_symlink_target_path_type_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.0.0</td>
|
||
<td><p>If the <code>type</code> argument is left undefined, Node will autodetect <code>target</code> type and automatically select <code>dir</code> or <code>file</code></p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>target</code> and <code>path</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>target</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/symlink.2.html"><code>symlink(2)</code></a> which creates the link called <code>path</code> pointing to
|
||
<code>target</code>. No arguments other than a possible exception are given to the
|
||
completion callback.</p>
|
||
<p>The <code>type</code> argument is only available on Windows and ignored on other platforms.
|
||
It can be set to <code>'dir'</code>, <code>'file'</code>, or <code>'junction'</code>. If the <code>type</code> argument is
|
||
not set, Node.js will autodetect <code>target</code> type and use <code>'file'</code> or <code>'dir'</code>. If
|
||
the <code>target</code> does not exist, <code>'file'</code> will be used. Windows junction points
|
||
require the destination path to be absolute. When using <code>'junction'</code>, the
|
||
<code>target</code> argument will automatically be normalized to absolute path.</p>
|
||
<p>Relative targets are relative to the link’s parent directory.</p>
|
||
<pre><code class="language-js">fs.symlink(<span class="hljs-string">'./mew'</span>, <span class="hljs-string">'./example/mewtwo'</span>, callback);</code></pre>
|
||
<p>The above example creates a symbolic link <code>mewtwo</code> in the <code>example</code> which points
|
||
to <code>mew</code> in the same directory:</p>
|
||
<pre><code class="language-bash">$ tree example/
|
||
example/
|
||
├── mew
|
||
└── mewtwo -> ./mew</code></pre>
|
||
<h2><code>fs.symlinkSync(target, path[, type])</code><span><a class="mark" href="#fs_fs_symlinksync_target_path_type" id="fs_fs_symlinksync_target_path_type">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.0.0</td>
|
||
<td><p>If the <code>type</code> argument is left undefined, Node will autodetect <code>target</code> type and automatically select <code>dir</code> or <code>file</code></p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>target</code> and <code>path</code> parameters can be WHATWG <code>URL</code> objects using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>target</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
<p>Returns <code>undefined</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink()</code></a>.</p>
|
||
<h2><code>fs.truncate(path[, len], callback)</code><span><a class="mark" href="#fs_fs_truncate_path_len_callback" id="fs_fs_truncate_path_len_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.8.6</td>
|
||
<td><p><span>Added in: v0.8.6</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/truncate.2.html"><code>truncate(2)</code></a>. No arguments other than a possible exception are
|
||
given to the completion callback. A file descriptor can also be passed as the
|
||
first argument. In this case, <code>fs.ftruncate()</code> is called.</p>
|
||
<p>Passing a file descriptor is deprecated and may result in an error being thrown
|
||
in the future.</p>
|
||
<h2><code>fs.truncateSync(path[, len])</code><span><a class="mark" href="#fs_fs_truncatesync_path_len" id="fs_fs_truncatesync_path_len">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.8.6</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/truncate.2.html"><code>truncate(2)</code></a>. Returns <code>undefined</code>. A file descriptor can also be
|
||
passed as the first argument. In this case, <code>fs.ftruncateSync()</code> is called.</p>
|
||
<p>Passing a file descriptor is deprecated and may result in an error being thrown
|
||
in the future.</p>
|
||
<h2><code>fs.unlink(path, callback)</code><span><a class="mark" href="#fs_fs_unlink_path_callback" id="fs_fs_unlink_path_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Asynchronously removes a file or symbolic link. No arguments other than a
|
||
possible exception are given to the completion callback.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span>
|
||
fs.unlink(<span class="hljs-string">'path/file.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'path/file.txt was deleted'</span>);
|
||
});</code></pre>
|
||
<p><code>fs.unlink()</code> will not work on a directory, empty or otherwise. To remove a
|
||
directory, use <a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir()</code></a>.</p>
|
||
<p>See also: <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>.</p>
|
||
<h2><code>fs.unlinkSync(path)</code><span><a class="mark" href="#fs_fs_unlinksync_path" id="fs_fs_unlinksync_path">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
</ul>
|
||
<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>. Returns <code>undefined</code>.</p>
|
||
<h2><code>fs.unwatchFile(filename[, listener])</code><span><a class="mark" href="#fs_fs_unwatchfile_filename_listener" id="fs_fs_unwatchfile_filename_listener">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v0.1.31</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>listener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Optional, a listener previously attached using
|
||
<code>fs.watchFile()</code></li>
|
||
</ul>
|
||
<p>Stop watching for changes on <code>filename</code>. If <code>listener</code> is specified, only that
|
||
particular listener is removed. Otherwise, <em>all</em> listeners are removed,
|
||
effectively stopping watching of <code>filename</code>.</p>
|
||
<p>Calling <code>fs.unwatchFile()</code> with a filename that is not being watched is a
|
||
no-op, not an error.</p>
|
||
<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile()</code> and
|
||
<code>fs.unwatchFile()</code>. <code>fs.watch()</code> should be used instead of <code>fs.watchFile()</code>
|
||
and <code>fs.unwatchFile()</code> when possible.</p>
|
||
<h2><code>fs.utimes(path, atime, mtime, callback)</code><span><a class="mark" href="#fs_fs_utimes_path_atime_mtime_callback" id="fs_fs_utimes_path_atime_mtime_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v4.1.0</td>
|
||
<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr>
|
||
<tr><td>v0.4.2</td>
|
||
<td><p><span>Added in: v0.4.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Change the file system timestamps of the object referenced by <code>path</code>.</p>
|
||
<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p>
|
||
<ul>
|
||
<li>Values can be either numbers representing Unix epoch time in seconds,
|
||
<code>Date</code>s, or a numeric string like <code>'123456789.0'</code>.</li>
|
||
<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or
|
||
<code>-Infinity</code>, an <code>Error</code> will be thrown.</li>
|
||
</ul>
|
||
<h2><code>fs.utimesSync(path, atime, mtime)</code><span><a class="mark" href="#fs_fs_utimessync_path_atime_mtime" id="fs_fs_utimessync_path_atime_mtime">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v8.0.0</td>
|
||
<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v4.1.0</td>
|
||
<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr>
|
||
<tr><td>v0.4.2</td>
|
||
<td><p><span>Added in: v0.4.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
</ul>
|
||
<p>Returns <code>undefined</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p>
|
||
<h2><code>fs.watch(filename[, options][, listener])</code><span><a class="mark" href="#fs_fs_watch_filename_options_listener" id="fs_fs_watch_filename_options_listener">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The passed <code>options</code> object will never be modified.</p></td></tr>
|
||
<tr><td>v0.5.10</td>
|
||
<td><p><span>Added in: v0.5.10</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>persistent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether the process should continue to run
|
||
as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Indicates whether all subdirectories should be
|
||
watched, or only the current directory. This applies when a directory is
|
||
specified, and only on supported platforms (See <a href="#fs_caveats">Caveats</a>). <strong>Default:</strong>
|
||
<code>false</code>.</li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Specifies the character encoding to be used for the
|
||
filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>listener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a> <strong>Default:</strong> <code>undefined</code>
|
||
<ul>
|
||
<li><code>eventType</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li>
|
||
</ul>
|
||
<p>Watch for changes on <code>filename</code>, where <code>filename</code> is either a file or a
|
||
directory.</p>
|
||
<p>The second argument is optional. If <code>options</code> is provided as a string, it
|
||
specifies the <code>encoding</code>. Otherwise <code>options</code> should be passed as an object.</p>
|
||
<p>The listener callback gets two arguments <code>(eventType, filename)</code>. <code>eventType</code>
|
||
is either <code>'rename'</code> or <code>'change'</code>, and <code>filename</code> is the name of the file
|
||
which triggered the event.</p>
|
||
<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or
|
||
disappears in the directory.</p>
|
||
<p>The listener callback is attached to the <code>'change'</code> event fired by
|
||
<a href="#fs_class_fs_fswatcher"><code>fs.FSWatcher</code></a>, but it is not the same thing as the <code>'change'</code> value of
|
||
<code>eventType</code>.</p>
|
||
<h3>Caveats<span><a class="mark" href="#fs_caveats" id="fs_caveats">#</a></span></h3>
|
||
|
||
<p>The <code>fs.watch</code> API is not 100% consistent across platforms, and is
|
||
unavailable in some situations.</p>
|
||
<p>The recursive option is only supported on macOS and Windows.</p>
|
||
<p>On Windows, no events will be emitted if the watched directory is moved or
|
||
renamed. An <code>EPERM</code> error is reported when the watched directory is deleted.</p>
|
||
<h4>Availability<span><a class="mark" href="#fs_availability" id="fs_availability">#</a></span></h4>
|
||
|
||
<p>This feature depends on the underlying operating system providing a way
|
||
to be notified of filesystem changes.</p>
|
||
<ul>
|
||
<li>On Linux systems, this uses <a href="https://man7.org/linux/man-pages/man7/inotify.7.html"><code>inotify(7)</code></a>.</li>
|
||
<li>On BSD systems, this uses <a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2"><code>kqueue(2)</code></a>.</li>
|
||
<li>On macOS, this uses <a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2"><code>kqueue(2)</code></a> for files and <a href="https://developer.apple.com/documentation/coreservices/file_system_events"><code>FSEvents</code></a> for
|
||
directories.</li>
|
||
<li>On SunOS systems (including Solaris and SmartOS), this uses <a href="https://illumos.org/man/port_create"><code>event ports</code></a>.</li>
|
||
<li>On Windows systems, this feature depends on <a href="https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw"><code>ReadDirectoryChangesW</code></a>.</li>
|
||
<li>On Aix systems, this feature depends on <a href="https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/"><code>AHAFS</code></a>, which must be enabled.</li>
|
||
<li>On IBM i systems, this feature is not supported.</li>
|
||
</ul>
|
||
<p>If the underlying functionality is not available for some reason, then
|
||
<code>fs.watch()</code> will not be able to function and may thrown an exception.
|
||
For example, watching files or directories can be unreliable, and in some
|
||
cases impossible, on network file systems (NFS, SMB, etc) or host file systems
|
||
when using virtualization software such as Vagrant or Docker.</p>
|
||
<p>It is still possible to use <code>fs.watchFile()</code>, which uses stat polling, but
|
||
this method is slower and less reliable.</p>
|
||
<h4>Inodes<span><a class="mark" href="#fs_inodes" id="fs_inodes">#</a></span></h4>
|
||
|
||
<p>On Linux and macOS systems, <code>fs.watch()</code> resolves the path to an <a href="https://en.wikipedia.org/wiki/Inode">inode</a> and
|
||
watches the inode. If the watched path is deleted and recreated, it is assigned
|
||
a new inode. The watch will emit an event for the delete but will continue
|
||
watching the <em>original</em> inode. Events for the new inode will not be emitted.
|
||
This is expected behavior.</p>
|
||
<p>AIX files retain the same inode for the lifetime of a file. Saving and closing a
|
||
watched file on AIX will result in two notifications (one for adding new
|
||
content, and one for truncation).</p>
|
||
<h4>Filename argument<span><a class="mark" href="#fs_filename_argument" id="fs_filename_argument">#</a></span></h4>
|
||
|
||
<p>Providing <code>filename</code> argument in the callback is only supported on Linux,
|
||
macOS, Windows, and AIX. Even on supported platforms, <code>filename</code> is not always
|
||
guaranteed to be provided. Therefore, don't assume that <code>filename</code> argument is
|
||
always provided in the callback, and have some fallback logic if it is <code>null</code>.</p>
|
||
<pre><code class="language-js">fs.watch(<span class="hljs-string">'somedir'</span>, <span class="hljs-function">(<span class="hljs-params">eventType, filename</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`event type is: <span class="hljs-subst">${eventType}</span>`</span>);
|
||
<span class="hljs-keyword">if</span> (filename) {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`filename provided: <span class="hljs-subst">${filename}</span>`</span>);
|
||
} <span class="hljs-keyword">else</span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'filename not provided'</span>);
|
||
}
|
||
});</code></pre>
|
||
<h2><code>fs.watchFile(filename[, options], listener)</code><span><a class="mark" href="#fs_fs_watchfile_filename_options_listener" id="fs_fs_watchfile_filename_options_listener">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>The <code>bigint</code> option is now supported.</p></td></tr>
|
||
<tr><td>v7.6.0</td>
|
||
<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol. Support is currently still <em>experimental</em>.</p></td></tr>
|
||
<tr><td>v0.1.31</td>
|
||
<td><p><span>Added in: v0.1.31</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>persistent</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>true</code></li>
|
||
<li><code>interval</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>5007</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><code>listener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>current</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
<li><code>previous</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li>
|
||
</ul>
|
||
<p>Watch for changes on <code>filename</code>. The callback <code>listener</code> will be called each
|
||
time the file is accessed.</p>
|
||
<p>The <code>options</code> argument may be omitted. If provided, it should be an object. The
|
||
<code>options</code> object may contain a boolean named <code>persistent</code> that indicates
|
||
whether the process should continue to run as long as files are being watched.
|
||
The <code>options</code> object may specify an <code>interval</code> property indicating how often the
|
||
target should be polled in milliseconds.</p>
|
||
<p>The <code>listener</code> gets two arguments the current stat object and the previous
|
||
stat object:</p>
|
||
<pre><code class="language-js">fs.watchFile(<span class="hljs-string">'message.text'</span>, <span class="hljs-function">(<span class="hljs-params">curr, prev</span>) =></span> {
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`the current mtime is: <span class="hljs-subst">${curr.mtime}</span>`</span>);
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`the previous mtime was: <span class="hljs-subst">${prev.mtime}</span>`</span>);
|
||
});</code></pre>
|
||
<p>These stat objects are instances of <code>fs.Stat</code>. If the <code>bigint</code> option is <code>true</code>,
|
||
the numeric values in these objects are specified as <code>BigInt</code>s.</p>
|
||
<p>To be notified when the file was modified, not just accessed, it is necessary
|
||
to compare <code>curr.mtime</code> and <code>prev.mtime</code>.</p>
|
||
<p>When an <code>fs.watchFile</code> operation results in an <code>ENOENT</code> error, it
|
||
will invoke the listener once, with all the fields zeroed (or, for dates, the
|
||
Unix Epoch). If the file is created later on, the listener will be called
|
||
again, with the latest stat objects. This is a change in functionality since
|
||
v0.10.</p>
|
||
<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile</code> and
|
||
<code>fs.unwatchFile</code>. <code>fs.watch</code> should be used instead of <code>fs.watchFile</code> and
|
||
<code>fs.unwatchFile</code> when possible.</p>
|
||
<p>When a file being watched by <code>fs.watchFile()</code> disappears and reappears,
|
||
then the contents of <code>previous</code> in the second callback event (the file's
|
||
reappearance) will be the same as the contents of <code>previous</code> in the first
|
||
callback event (its disappearance).</p>
|
||
<p>This happens when:</p>
|
||
<ul>
|
||
<li>the file is deleted, followed by a restore</li>
|
||
<li>the file is renamed and then renamed a second time back to its original name</li>
|
||
</ul>
|
||
<h2><code>fs.write(fd, buffer[, offset[, length[, position]]], callback)</code><span><a class="mark" href="#fs_fs_write_fd_buffer_offset_length_position_callback" id="fs_fs_write_fd_buffer_offset_length_position_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code></p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.4.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr>
|
||
<tr><td>v7.2.0</td>
|
||
<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.0.2</td>
|
||
<td><p><span>Added in: v0.0.2</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Write <code>buffer</code> to the file specified by <code>fd</code>.</p>
|
||
<p><code>offset</code> determines the part of the buffer to be written, and <code>length</code> is
|
||
an integer specifying the number of bytes to write.</p>
|
||
<p><code>position</code> refers to the offset from the beginning of the file where this data
|
||
should be written. If <code>typeof position !== 'number'</code>, the data will be written
|
||
at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p>
|
||
<p>The callback will be given three arguments <code>(err, bytesWritten, buffer)</code> where
|
||
<code>bytesWritten</code> specifies how many <em>bytes</em> were written from <code>buffer</code>.</p>
|
||
<p>If this method is invoked as its <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed version, it returns
|
||
a <code>Promise</code> for an <code>Object</code> with <code>bytesWritten</code> and <code>buffer</code> properties.</p>
|
||
<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting
|
||
for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is
|
||
recommended.</p>
|
||
<p>On Linux, positional writes don't work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<h2><code>fs.write(fd, string[, position[, encoding]], callback)</code><span><a class="mark" href="#fs_fs_write_fd_string_position_encoding_callback" id="fs_fs_write_fd_string_position_encoding_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.2.0</td>
|
||
<td><p>The <code>position</code> parameter is optional now.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v0.11.5</td>
|
||
<td><p><span>Added in: v0.11.5</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>written</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Write <code>string</code> to the file specified by <code>fd</code>. If <code>string</code> is not a string, then
|
||
the value will be coerced to one.</p>
|
||
<p><code>position</code> refers to the offset from the beginning of the file where this data
|
||
should be written. If <code>typeof position !== 'number'</code> the data will be written at
|
||
the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p>
|
||
<p><code>encoding</code> is the expected string encoding.</p>
|
||
<p>The callback will receive the arguments <code>(err, written, string)</code> where <code>written</code>
|
||
specifies how many <em>bytes</em> the passed string required to be written. Bytes
|
||
written is not necessarily the same as string characters written. See
|
||
<a href="buffer.html#buffer_static_method_buffer_bytelength_string_encoding"><code>Buffer.byteLength</code></a>.</p>
|
||
<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting
|
||
for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is
|
||
recommended.</p>
|
||
<p>On Linux, positional writes don't work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<p>On Windows, if the file descriptor is connected to the console (e.g. <code>fd == 1</code>
|
||
or <code>stdout</code>) a string containing non-ASCII characters will not be rendered
|
||
properly by default, regardless of the encoding used.
|
||
It is possible to configure the console to render UTF-8 properly by changing the
|
||
active codepage with the <code>chcp 65001</code> command. See the <a href="https://ss64.com/nt/chcp.html">chcp</a> docs for more
|
||
details.</p>
|
||
<h2><code>fs.writeFile(file, data[, options], callback)</code><span><a class="mark" href="#fs_fs_writefile_file_data_options_callback" id="fs_fs_writefile_file_data_options_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will throw a <code>TypeError</code> at runtime.</p></td></tr>
|
||
<tr><td>v7.4.0</td>
|
||
<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr>
|
||
<tr><td>v7.0.0</td>
|
||
<td><p>The <code>callback</code> parameter is no longer optional. Not passing it will emit a deprecation warning with id DEP0013.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.1.29</td>
|
||
<td><p><span>Added in: v0.1.29</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> filename or file descriptor</li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'w'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>When <code>file</code> is a filename, asynchronously writes data to the file, replacing the
|
||
file if it already exists. <code>data</code> can be a string or a buffer.</p>
|
||
<p>When <code>file</code> is a file descriptor, the behavior is similar to calling
|
||
<code>fs.write()</code> directly (which is recommended). See the notes below on using
|
||
a file descriptor.</p>
|
||
<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> data = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Uint8Array</span>(Buffer.from(<span class="hljs-string">'Hello Node.js'</span>));
|
||
fs.writeFile(<span class="hljs-string">'message.txt'</span>, data, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> {
|
||
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err;
|
||
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The file has been saved!'</span>);
|
||
});</code></pre>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding:</p>
|
||
<pre><code class="language-js">fs.writeFile(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'Hello Node.js'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre>
|
||
<p>It is unsafe to use <code>fs.writeFile()</code> multiple times on the same file without
|
||
waiting for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is
|
||
recommended.</p>
|
||
<h3>Using <code>fs.writeFile()</code> with file descriptors<span><a class="mark" href="#fs_using_fs_writefile_with_file_descriptors" id="fs_using_fs_writefile_with_file_descriptors">#</a></span></h3>
|
||
<p>When <code>file</code> is a file descriptor, the behavior is almost identical to directly
|
||
calling <code>fs.write()</code> like:</p>
|
||
<pre><code class="language-js">fs.write(fd, Buffer.from(data, options.encoding), callback);</code></pre>
|
||
<p>The difference from directly calling <code>fs.write()</code> is that under some unusual
|
||
conditions, <code>fs.write()</code> may write only part of the buffer and will need to be
|
||
retried to write the remaining data, whereas <code>fs.writeFile()</code> will retry until
|
||
the data is entirely written (or an error occurs).</p>
|
||
<p>The implications of this are a common source of confusion. In
|
||
the file descriptor case, the file is not replaced! The data is not necessarily
|
||
written to the beginning of the file, and the file's original data may remain
|
||
before and/or after the newly written data.</p>
|
||
<p>For example, if <code>fs.writeFile()</code> is called twice in a row, first to write the
|
||
string <code>'Hello'</code>, then to write the string <code>', World'</code>, the file would contain
|
||
<code>'Hello, World'</code>, and might contain some of the file's original data (depending
|
||
on the size of the original file, and the position of the file descriptor). If
|
||
a file name had been used instead of a descriptor, the file would be guaranteed
|
||
to contain only <code>', World'</code>.</p>
|
||
<h2><code>fs.writeFileSync(file, data[, options])</code><span><a class="mark" href="#fs_fs_writefilesync_file_data_options" id="fs_fs_writefilesync_file_data_options">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v7.4.0</td>
|
||
<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr>
|
||
<tr><td>v5.0.0</td>
|
||
<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr>
|
||
<tr><td>v0.1.29</td>
|
||
<td><p><span>Added in: v0.1.29</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> filename or file descriptor</li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'w'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Returns <code>undefined</code>.</p>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile()</code></a>.</p>
|
||
<h2><code>fs.writeSync(fd, buffer[, offset[, length[, position]]])</code><span><a class="mark" href="#fs_fs_writesync_fd_buffer_offset_length_position" id="fs_fs_writesync_fd_buffer_offset_length_position">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.10.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr>
|
||
<tr><td>v7.4.0</td>
|
||
<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr>
|
||
<tr><td>v7.2.0</td>
|
||
<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr>
|
||
<tr><td>v0.1.21</td>
|
||
<td><p><span>Added in: v0.1.21</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of bytes written.</li>
|
||
</ul>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer...)</code></a>.</p>
|
||
<h2><code>fs.writeSync(fd, string[, position[, encoding]])</code><span><a class="mark" href="#fs_fs_writesync_fd_string_position_encoding" id="fs_fs_writesync_fd_string_position_encoding">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v7.2.0</td>
|
||
<td><p>The <code>position</code> parameter is optional now.</p></td></tr>
|
||
<tr><td>v0.11.5</td>
|
||
<td><p><span>Added in: v0.11.5</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of bytes written.</li>
|
||
</ul>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string...)</code></a>.</p>
|
||
<h2><code>fs.writev(fd, buffers[, position], callback)</code><span><a class="mark" href="#fs_fs_writev_fd_buffers_position_callback" id="fs_fs_writev_fd_buffers_position_callback">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.9.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a>
|
||
<ul>
|
||
<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li>
|
||
<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Write an array of <code>ArrayBufferView</code>s to the file specified by <code>fd</code> using
|
||
<code>writev()</code>.</p>
|
||
<p><code>position</code> is the offset from the beginning of the file where this data
|
||
should be written. If <code>typeof position !== 'number'</code>, the data will be written
|
||
at the current position.</p>
|
||
<p>The callback will be given three arguments: <code>err</code>, <code>bytesWritten</code>, and
|
||
<code>buffers</code>. <code>bytesWritten</code> is how many bytes were written from <code>buffers</code>.</p>
|
||
<p>If this method is <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed, it returns a <code>Promise</code> for an
|
||
<code>Object</code> with <code>bytesWritten</code> and <code>buffers</code> properties.</p>
|
||
<p>It is unsafe to use <code>fs.writev()</code> multiple times on the same file without
|
||
waiting for the callback. For this scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p>
|
||
<p>On Linux, positional writes don't work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<h2><code>fs.writevSync(fd, buffers[, position])</code><span><a class="mark" href="#fs_fs_writevsync_fd_buffers_position" id="fs_fs_writevsync_fd_buffers_position">#</a></span></h2>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.9.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The number of bytes written.</li>
|
||
</ul>
|
||
<p>For detailed information, see the documentation of the asynchronous version of
|
||
this API: <a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev()</code></a>.</p>
|
||
<h2><code>fs</code> Promises API<span><a class="mark" href="#fs_fs_promises_api" id="fs_fs_promises_api">#</a></span></h2>
|
||
<p>The <code>fs.promises</code> API provides an alternative set of asynchronous file system
|
||
methods that return <code>Promise</code> objects rather than using callbacks. The
|
||
API is accessible via <code>require('fs').promises</code>.</p>
|
||
<h3>Class: <code>FileHandle</code><span><a class="mark" href="#fs_class_filehandle" id="fs_class_filehandle">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<p>A <code>FileHandle</code> object is a wrapper for a numeric file descriptor.
|
||
Instances of <code>FileHandle</code> are distinct from numeric file descriptors
|
||
in that they provide an object oriented API for working with files.</p>
|
||
<p>If a <code>FileHandle</code> is not closed using the
|
||
<code>filehandle.close()</code> method, it might automatically close the file descriptor
|
||
and will emit a process warning, thereby helping to prevent memory leaks.
|
||
Please do not rely on this behavior because it is unreliable and
|
||
the file may not be closed. Instead, always explicitly close <code>FileHandle</code>s.
|
||
Node.js may change this behavior in the future.</p>
|
||
<p>Instances of the <code>FileHandle</code> object are created internally by the
|
||
<code>fsPromises.open()</code> method.</p>
|
||
<p>Unlike the callback-based API (<code>fs.fstat()</code>, <code>fs.fchown()</code>, <code>fs.fchmod()</code>, and
|
||
so on), a numeric file descriptor is not used by the promise-based API. Instead,
|
||
the promise-based API uses the <code>FileHandle</code> class in order to help avoid
|
||
accidental leaking of unclosed file descriptors after a <code>Promise</code> is resolved or
|
||
rejected.</p>
|
||
<h4><code>filehandle.appendFile(data, options)</code><span><a class="mark" href="#fs_filehandle_appendfile_data_options" id="fs_filehandle_appendfile_data_options">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Alias of <a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p>
|
||
<p>When operating on file handles, the mode cannot be changed from what it was set
|
||
to with <a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open()</code></a>. Therefore, this is equivalent to
|
||
<a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p>
|
||
<h4><code>filehandle.chmod(mode)</code><span><a class="mark" href="#fs_filehandle_chmod_mode" id="fs_filehandle_chmod_mode">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Modifies the permissions on the file. The <code>Promise</code> is resolved with no
|
||
arguments upon success.</p>
|
||
<h4><code>filehandle.chown(uid, gid)</code><span><a class="mark" href="#fs_filehandle_chown_uid_gid" id="fs_filehandle_chown_uid_gid">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the ownership of the file then resolves the <code>Promise</code> with no arguments
|
||
upon success.</p>
|
||
<h4><code>filehandle.close()</code><span><a class="mark" href="#fs_filehandle_close" id="fs_filehandle_close">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> A <code>Promise</code> that will be resolved once the underlying
|
||
file descriptor is closed, or will be rejected if an error occurs while
|
||
closing.</li>
|
||
</ul>
|
||
<p>Closes the file descriptor.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fsPromises = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>).promises;
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">openAndClose</span>(<span class="hljs-params"></span>) </span>{
|
||
<span class="hljs-keyword">let</span> filehandle;
|
||
<span class="hljs-keyword">try</span> {
|
||
filehandle = <span class="hljs-keyword">await</span> fsPromises.open(<span class="hljs-string">'thefile.txt'</span>, <span class="hljs-string">'r'</span>);
|
||
} <span class="hljs-keyword">finally</span> {
|
||
<span class="hljs-keyword">if</span> (filehandle !== <span class="hljs-literal">undefined</span>)
|
||
<span class="hljs-keyword">await</span> filehandle.close();
|
||
}
|
||
}</code></pre>
|
||
<h4><code>filehandle.datasync()</code><span><a class="mark" href="#fs_filehandle_datasync" id="fs_filehandle_datasync">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a>. The <code>Promise</code> is resolved with no arguments upon
|
||
success.</p>
|
||
<h4><code>filehandle.fd</code><span><a class="mark" href="#fs_filehandle_fd" id="fs_filehandle_fd">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The numeric file descriptor managed by the <code>FileHandle</code> object.</li>
|
||
</ul>
|
||
<h4><code>filehandle.read(buffer, offset, length, position)</code><span><a class="mark" href="#fs_filehandle_read_buffer_offset_length_position" id="fs_filehandle_read_buffer_offset_length_position">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Read data from the file.</p>
|
||
<p><code>buffer</code> is the buffer that the data will be written to.</p>
|
||
<p><code>offset</code> is the offset in the buffer to start writing at.</p>
|
||
<p><code>length</code> is an integer specifying the number of bytes to read.</p>
|
||
<p><code>position</code> is an argument specifying where to begin reading from in the file.
|
||
If <code>position</code> is <code>null</code>, data will be read from the current file position,
|
||
and the file position will be updated.
|
||
If <code>position</code> is an integer, the file position will remain unchanged.</p>
|
||
<p>Following successful read, the <code>Promise</code> is resolved with an object with a
|
||
<code>bytesRead</code> property specifying the number of bytes read, and a <code>buffer</code>
|
||
property that is a reference to the passed in <code>buffer</code> argument.</p>
|
||
<h4><code>filehandle.read(options)</code><span><a class="mark" href="#fs_filehandle_read_options" id="fs_filehandle_read_options">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.17.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>buffer.length</code></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<h4><code>filehandle.readFile(options)</code><span><a class="mark" href="#fs_filehandle_readfile_options" id="fs_filehandle_readfile_options">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously reads the entire contents of a file.</p>
|
||
<p>The <code>Promise</code> is resolved with the contents of the file. If no encoding is
|
||
specified (using <code>options.encoding</code>), the data is returned as a <code>Buffer</code>
|
||
object. Otherwise, the data will be a string.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<p>The <code>FileHandle</code> has to support reading.</p>
|
||
<p>If one or more <code>filehandle.read()</code> calls are made on a file handle and then a
|
||
<code>filehandle.readFile()</code> call is made, the data will be read from the current
|
||
position till the end of the file. It doesn't always read from the beginning
|
||
of the file.</p>
|
||
<h4><code>filehandle.readv(buffers[, position])</code><span><a class="mark" href="#fs_filehandle_readv_buffers_position" id="fs_filehandle_readv_buffers_position">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.17.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Read from a file and write to an array of <code>ArrayBufferView</code>s</p>
|
||
<p>The <code>Promise</code> is resolved with an object containing a <code>bytesRead</code> property
|
||
identifying the number of bytes read, and a <code>buffers</code> property containing
|
||
a reference to the <code>buffers</code> input.</p>
|
||
<p><code>position</code> is the offset from the beginning of the file where this data
|
||
should be read from. If <code>typeof position !== 'number'</code>, the data will be read
|
||
from the current position.</p>
|
||
<h4><code>filehandle.stat([options])</code><span><a class="mark" href="#fs_filehandle_stat_options" id="fs_filehandle_stat_options">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Retrieves the <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> for the file.</p>
|
||
<h4><code>filehandle.sync()</code><span><a class="mark" href="#fs_filehandle_sync" id="fs_filehandle_sync">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a>. The <code>Promise</code> is resolved with no arguments upon
|
||
success.</p>
|
||
<h4><code>filehandle.truncate(len)</code><span><a class="mark" href="#fs_filehandle_truncate_len" id="fs_filehandle_truncate_len">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Truncates the file then resolves the <code>Promise</code> with no arguments upon success.</p>
|
||
<p>If the file was larger than <code>len</code> bytes, only the first <code>len</code> bytes will be
|
||
retained in the file.</p>
|
||
<p>For example, the following program retains only the first four bytes of the
|
||
file:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> fsPromises = fs.promises;
|
||
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>));
|
||
<span class="hljs-comment">// Prints: Node.js</span>
|
||
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">doTruncate</span>(<span class="hljs-params"></span>) </span>{
|
||
<span class="hljs-keyword">let</span> filehandle = <span class="hljs-literal">null</span>;
|
||
<span class="hljs-keyword">try</span> {
|
||
filehandle = <span class="hljs-keyword">await</span> fsPromises.open(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>);
|
||
<span class="hljs-keyword">await</span> filehandle.truncate(<span class="hljs-number">4</span>);
|
||
} <span class="hljs-keyword">finally</span> {
|
||
<span class="hljs-keyword">if</span> (filehandle) {
|
||
<span class="hljs-comment">// Close the file if it is opened.</span>
|
||
<span class="hljs-keyword">await</span> filehandle.close();
|
||
}
|
||
}
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>)); <span class="hljs-comment">// Prints: Node</span>
|
||
}
|
||
|
||
doTruncate().catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the
|
||
extended part is filled with null bytes (<code>'\0'</code>):</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> fsPromises = fs.promises;
|
||
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>));
|
||
<span class="hljs-comment">// Prints: Node.js</span>
|
||
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">doTruncate</span>(<span class="hljs-params"></span>) </span>{
|
||
<span class="hljs-keyword">let</span> filehandle = <span class="hljs-literal">null</span>;
|
||
<span class="hljs-keyword">try</span> {
|
||
filehandle = <span class="hljs-keyword">await</span> fsPromises.open(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>);
|
||
<span class="hljs-keyword">await</span> filehandle.truncate(<span class="hljs-number">10</span>);
|
||
} <span class="hljs-keyword">finally</span> {
|
||
<span class="hljs-keyword">if</span> (filehandle) {
|
||
<span class="hljs-comment">// Close the file if it is opened.</span>
|
||
<span class="hljs-keyword">await</span> filehandle.close();
|
||
}
|
||
}
|
||
<span class="hljs-built_in">console</span>.log(fs.readFileSync(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'utf8'</span>)); <span class="hljs-comment">// Prints Node.js\0\0\0</span>
|
||
}
|
||
|
||
doTruncate().catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<p>The last three bytes are null bytes (<code>'\0'</code>), to compensate the over-truncation.</p>
|
||
<h4><code>filehandle.utimes(atime, mtime)</code><span><a class="mark" href="#fs_filehandle_utimes_atime_mtime" id="fs_filehandle_utimes_atime_mtime">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Change the file system timestamps of the object referenced by the <code>FileHandle</code>
|
||
then resolves the <code>Promise</code> with no arguments upon success.</p>
|
||
<p>This function does not work on AIX versions before 7.1, it will resolve the
|
||
<code>Promise</code> with an error using code <code>UV_ENOSYS</code>.</p>
|
||
<h4><code>filehandle.write(buffer[, offset[, length[, position]]])</code><span><a class="mark" href="#fs_filehandle_write_buffer_offset_length_position" id="fs_filehandle_write_buffer_offset_length_position">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
||
<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Write <code>buffer</code> to the file.</p>
|
||
<p>The <code>Promise</code> is resolved with an object containing a <code>bytesWritten</code> property
|
||
identifying the number of bytes written, and a <code>buffer</code> property containing
|
||
a reference to the <code>buffer</code> written.</p>
|
||
<p><code>offset</code> determines the part of the buffer to be written, and <code>length</code> is
|
||
an integer specifying the number of bytes to write.</p>
|
||
<p><code>position</code> refers to the offset from the beginning of the file where this data
|
||
should be written. If <code>typeof position !== 'number'</code>, the data will be written
|
||
at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p>
|
||
<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file
|
||
without waiting for the <code>Promise</code> to be resolved (or rejected). For this
|
||
scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p>
|
||
<p>On Linux, positional writes do not work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<h4><code>filehandle.write(string[, position[, encoding]])</code><span><a class="mark" href="#fs_filehandle_write_string_position_encoding" id="fs_filehandle_write_string_position_encoding">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Write <code>string</code> to the file. If <code>string</code> is not a string, then
|
||
the value will be coerced to one.</p>
|
||
<p>The <code>Promise</code> is resolved with an object containing a <code>bytesWritten</code> property
|
||
identifying the number of bytes written, and a <code>buffer</code> property containing
|
||
a reference to the <code>string</code> written.</p>
|
||
<p><code>position</code> refers to the offset from the beginning of the file where this data
|
||
should be written. If the type of <code>position</code> is not a <code>number</code> the data
|
||
will be written at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p>
|
||
<p><code>encoding</code> is the expected string encoding.</p>
|
||
<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file
|
||
without waiting for the <code>Promise</code> to be resolved (or rejected). For this
|
||
scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p>
|
||
<p>On Linux, positional writes do not work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<h4><code>filehandle.writeFile(data, options)</code><span><a class="mark" href="#fs_filehandle_writefile_data_options" id="fs_filehandle_writefile_data_options">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously writes data to a file, replacing the file if it already exists.
|
||
<code>data</code> can be a string or a buffer. The <code>Promise</code> will be resolved with no
|
||
arguments upon success.</p>
|
||
<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<p>The <code>FileHandle</code> has to support writing.</p>
|
||
<p>It is unsafe to use <code>filehandle.writeFile()</code> multiple times on the same file
|
||
without waiting for the <code>Promise</code> to be resolved (or rejected).</p>
|
||
<p>If one or more <code>filehandle.write()</code> calls are made on a file handle and then a
|
||
<code>filehandle.writeFile()</code> call is made, the data will be written from the
|
||
current position till the end of the file. It doesn't always write from the
|
||
beginning of the file.</p>
|
||
<h4><code>filehandle.writev(buffers[, position])</code><span><a class="mark" href="#fs_filehandle_writev_buffers_position" id="fs_filehandle_writev_buffers_position">#</a></span></h4>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.9.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li>
|
||
<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Write an array of <code>ArrayBufferView</code>s to the file.</p>
|
||
<p>The <code>Promise</code> is resolved with an object containing a <code>bytesWritten</code> property
|
||
identifying the number of bytes written, and a <code>buffers</code> property containing
|
||
a reference to the <code>buffers</code> input.</p>
|
||
<p><code>position</code> is the offset from the beginning of the file where this data
|
||
should be written. If <code>typeof position !== 'number'</code>, the data will be written
|
||
at the current position.</p>
|
||
<p>It is unsafe to call <code>writev()</code> multiple times on the same file without waiting
|
||
for the previous operation to complete.</p>
|
||
<p>On Linux, positional writes don't work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<h3><code>fsPromises.access(path[, mode])</code><span><a class="mark" href="#fs_fspromises_access_path_mode" id="fs_fspromises_access_path_mode">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>fs.constants.F_OK</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Tests a user's permissions for the file or directory specified by <code>path</code>.
|
||
The <code>mode</code> argument is an optional integer that specifies the accessibility
|
||
checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values
|
||
of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of
|
||
two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p>
|
||
<p>If the accessibility check is successful, the <code>Promise</code> is resolved with no
|
||
value. If any of the accessibility checks fail, the <code>Promise</code> is rejected
|
||
with an <code>Error</code> object. The following example checks if the file
|
||
<code>/etc/passwd</code> can be read and written by the current process.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> fsPromises = fs.promises;
|
||
|
||
fsPromises.access(<span class="hljs-string">'/etc/passwd'</span>, fs.constants.R_OK | fs.constants.W_OK)
|
||
.then(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'can access'</span>))
|
||
.catch(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.error(<span class="hljs-string">'cannot access'</span>));</code></pre>
|
||
<p>Using <code>fsPromises.access()</code> to check for the accessibility of a file before
|
||
calling <code>fsPromises.open()</code> is not recommended. Doing so introduces a race
|
||
condition, since other processes may change the file's state between the two
|
||
calls. Instead, user code should open/read/write the file directly and handle
|
||
the error raised if the file is not accessible.</p>
|
||
<h3><code>fsPromises.appendFile(path, data[, options])</code><span><a class="mark" href="#fs_fspromises_appendfile_path_data_options" id="fs_fspromises_appendfile_path_data_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> filename or <code>FileHandle</code></li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'a'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously append data to a file, creating the file if it does not yet
|
||
exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_buffer"><code>Buffer</code></a>. The <code>Promise</code> will be
|
||
resolved with no arguments upon success.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<p>The <code>path</code> may be specified as a <code>FileHandle</code> that has been opened
|
||
for appending (using <code>fsPromises.open()</code>).</p>
|
||
<h3><code>fsPromises.chmod(path, mode)</code><span><a class="mark" href="#fs_fspromises_chmod_path_mode" id="fs_fspromises_chmod_path_mode">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the permissions of a file then resolves the <code>Promise</code> with no
|
||
arguments upon succces.</p>
|
||
<h3><code>fsPromises.chown(path, uid, gid)</code><span><a class="mark" href="#fs_fspromises_chown_path_uid_gid" id="fs_fspromises_chown_path_uid_gid">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the ownership of a file then resolves the <code>Promise</code> with no arguments
|
||
upon success.</p>
|
||
<h3><code>fsPromises.copyFile(src, dest[, flags])</code><span><a class="mark" href="#fs_fspromises_copyfile_src_dest_flags" id="fs_fspromises_copyfile_src_dest_flags">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v14.0.0</td>
|
||
<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>src</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> source filename to copy</li>
|
||
<li><code>dest</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> destination filename of the copy operation</li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> modifiers for copy operation. <strong>Default:</strong> <code>0</code>.</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it
|
||
already exists. The <code>Promise</code> will be resolved with no arguments upon success.</p>
|
||
<p>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.</p>
|
||
<p><code>flags</code> is an optional integer that specifies the behavior
|
||
of the copy operation. It is possible to create a mask consisting of the bitwise
|
||
OR of two or more values (e.g.
|
||
<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p>
|
||
<ul>
|
||
<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already
|
||
exists.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a
|
||
copy-on-write reflink. If the platform does not support copy-on-write, then a
|
||
fallback copy mechanism is used.</li>
|
||
<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to
|
||
create a copy-on-write reflink. If the platform does not support copy-on-write,
|
||
then the operation will fail.</li>
|
||
</ul>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fsPromises = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>).promises;
|
||
|
||
<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span>
|
||
fsPromises.copyFile(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>)
|
||
.then(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'source.txt was copied to destination.txt'</span>))
|
||
.catch(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The file could not be copied'</span>));</code></pre>
|
||
<p>If the third argument is a number, then it specifies <code>flags</code>:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
<span class="hljs-keyword">const</span> fsPromises = fs.promises;
|
||
<span class="hljs-keyword">const</span> { COPYFILE_EXCL } = fs.constants;
|
||
|
||
<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span>
|
||
fsPromises.copyFile(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, COPYFILE_EXCL)
|
||
.then(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'source.txt was copied to destination.txt'</span>))
|
||
.catch(<span class="hljs-function">() =></span> <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'The file could not be copied'</span>));</code></pre>
|
||
<h3><code>fsPromises.lchmod(path, mode)</code><span><a class="mark" href="#fs_fspromises_lchmod_path_mode" id="fs_fspromises_lchmod_path_mode">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Deprecated since: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the permissions on a symbolic link then resolves the <code>Promise</code> with
|
||
no arguments upon success. This method is only implemented on macOS.</p>
|
||
<h3><code>fsPromises.lchown(path, uid, gid)</code><span><a class="mark" href="#fs_fspromises_lchown_path_uid_gid" id="fs_fspromises_lchown_path_uid_gid">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.6.0</td>
|
||
<td><p>This API is no longer deprecated.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the ownership on a symbolic link then resolves the <code>Promise</code> with
|
||
no arguments upon success.</p>
|
||
<h3><code>fsPromises.lutimes(path, atime, mtime)</code><span><a class="mark" href="#fs_fspromises_lutimes_path_atime_mtime" id="fs_fspromises_lutimes_path_atime_mtime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v12.19.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Changes the access and modification times of a file in the same way as
|
||
<a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes()</code></a>, with the difference that if the path refers to a
|
||
symbolic link, then the link is not dereferenced: instead, the timestamps of
|
||
the symbolic link itself are changed.</p>
|
||
<p>Upon success, the <code>Promise</code> is resolved without arguments.</p>
|
||
<h3><code>fsPromises.link(existingPath, newPath)</code><span><a class="mark" href="#fs_fspromises_link_existingpath_newpath" id="fs_fspromises_link_existingpath_newpath">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>existingPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a>. The <code>Promise</code> is resolved with no arguments upon success.</p>
|
||
<h3><code>fsPromises.lstat(path[, options])</code><span><a class="mark" href="#fs_fspromises_lstat_path_options" id="fs_fspromises_lstat_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a>. The <code>Promise</code> is resolved with the <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object
|
||
for the given symbolic link <code>path</code>.</p>
|
||
<h3><code>fsPromises.mkdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_mkdir_path_options" id="fs_fspromises_mkdir_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a>
|
||
<ul>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Not supported on Windows. <strong>Default:</strong> <code>0o777</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously creates a directory then resolves the <code>Promise</code> with either no
|
||
arguments, or the first directory path created if <code>recursive</code> is <code>true</code>.</p>
|
||
<p>The optional <code>options</code> argument can be an integer specifying mode (permission
|
||
and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code>
|
||
property indicating whether parent directories should be created. Calling
|
||
<code>fsPromises.mkdir()</code> when <code>path</code> is a directory that exists results in a
|
||
rejection only when <code>recursive</code> is false.</p>
|
||
<h3><code>fsPromises.mkdtemp(prefix[, options])</code><span><a class="mark" href="#fs_fspromises_mkdtemp_prefix_options" id="fs_fspromises_mkdtemp_prefix_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Creates a unique temporary directory and resolves the <code>Promise</code> with the created
|
||
directory path. A unique directory name is generated by appending six random
|
||
characters to the end of the provided <code>prefix</code>. Due to platform
|
||
inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some platforms,
|
||
notably the BSDs, can return more than six random characters, and replace
|
||
trailing <code>X</code> characters in <code>prefix</code> with random characters.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use.</p>
|
||
<pre><code class="language-js">fsPromises.mkdtemp(path.join(os.tmpdir(), <span class="hljs-string">'foo-'</span>))
|
||
.catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<p>The <code>fsPromises.mkdtemp()</code> method will append the six randomly selected
|
||
characters directly to the <code>prefix</code> string. For instance, given a directory
|
||
<code>/tmp</code>, if the intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the
|
||
<code>prefix</code> must end with a trailing platform-specific path separator
|
||
(<code>require('path').sep</code>).</p>
|
||
<h3><code>fsPromises.open(path, flags[, mode])</code><span><a class="mark" href="#fs_fspromises_open_path_flags_mode" id="fs_fspromises_open_path_flags_mode">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v11.1.0</td>
|
||
<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>flags</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.
|
||
<strong>Default:</strong> <code>'r'</code>.</li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code> (readable and writable)</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous file open that returns a <code>Promise</code> that, when resolved, yields a
|
||
<code>FileHandle</code> object. See <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a>.</p>
|
||
<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the file was
|
||
created.</p>
|
||
<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented
|
||
by <a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file">Naming Files, Paths, and Namespaces</a>. Under NTFS, if the filename contains
|
||
a colon, Node.js will open a file system stream, as described by
|
||
<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p>
|
||
<h3><code>fsPromises.opendir(path[, options])</code><span><a class="mark" href="#fs_fspromises_opendir_path_options" id="fs_fspromises_opendir_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr>
|
||
<tr><td>v12.12.0</td>
|
||
<td><p><span>Added in: v12.12.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>bufferSize</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of directory entries that are buffered
|
||
internally when reading from the directory. Higher values lead to better
|
||
performance but higher memory usage. <strong>Default:</strong> <code>32</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> containing <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li>
|
||
</ul>
|
||
<p>Asynchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p>
|
||
<p>Creates an <a href="#fs_class_fs_dir"><code>fs.Dir</code></a>, which contains all further functions for reading from
|
||
and cleaning up the directory.</p>
|
||
<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the
|
||
directory and subsequent read operations.</p>
|
||
<p>Example using async iteration:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">print</span>(<span class="hljs-params">path</span>) </span>{
|
||
<span class="hljs-keyword">const</span> dir = <span class="hljs-keyword">await</span> fs.promises.opendir(path);
|
||
<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> dirent <span class="hljs-keyword">of</span> dir) {
|
||
<span class="hljs-built_in">console</span>.log(dirent.name);
|
||
}
|
||
}
|
||
print(<span class="hljs-string">'./'</span>).catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<h3><code>fsPromises.readdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_readdir_path_options" id="fs_fspromises_readdir_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.11.0</td>
|
||
<td><p>New option <code>withFileTypes</code> was added.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>withFileTypes</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <strong>Default:</strong> <code>false</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Reads the contents of a directory then resolves the <code>Promise</code> with an array
|
||
of the names of the files in the directory excluding <code>'.'</code> and <code>'..'</code>.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the filenames. If the <code>encoding</code> is set to <code>'buffer'</code>, the filenames returned
|
||
will be passed as <code>Buffer</code> objects.</p>
|
||
<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the resolved array will contain
|
||
<a href="#fs_class_fs_dirent"><code>fs.Dirent</code></a> objects.</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">print</span>(<span class="hljs-params">path</span>) </span>{
|
||
<span class="hljs-keyword">const</span> files = <span class="hljs-keyword">await</span> fs.promises.readdir(path);
|
||
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> file <span class="hljs-keyword">of</span> files) {
|
||
<span class="hljs-built_in">console</span>.log(file);
|
||
}
|
||
}
|
||
print(<span class="hljs-string">'./'</span>).catch(<span class="hljs-built_in">console</span>.error);</code></pre>
|
||
<h3><code>fsPromises.readFile(path[, options])</code><span><a class="mark" href="#fs_fspromises_readfile_path_options" id="fs_fspromises_readfile_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> filename or <code>FileHandle</code></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>null</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'r'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously reads the entire contents of a file.</p>
|
||
<p>The <code>Promise</code> is resolved with the contents of the file. If no encoding is
|
||
specified (using <code>options.encoding</code>), the data is returned as a <code>Buffer</code>
|
||
object. Otherwise, the data will be a string.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<p>When the <code>path</code> is a directory, the behavior of <code>fsPromises.readFile()</code> is
|
||
platform-specific. On macOS, Linux, and Windows, the promise will be rejected
|
||
with an error. On FreeBSD, a representation of the directory's contents will be
|
||
returned.</p>
|
||
<p>Any specified <code>FileHandle</code> has to support reading.</p>
|
||
<h3><code>fsPromises.readlink(path[, options])</code><span><a class="mark" href="#fs_fspromises_readlink_path_options" id="fs_fspromises_readlink_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a>. The <code>Promise</code> is resolved with the <code>linkString</code> upon
|
||
success.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, the link path
|
||
returned will be passed as a <code>Buffer</code> object.</p>
|
||
<h3><code>fsPromises.realpath(path[, options])</code><span><a class="mark" href="#fs_fspromises_realpath_path_options" id="fs_fspromises_realpath_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Determines the actual location of <code>path</code> using the same semantics as the
|
||
<code>fs.realpath.native()</code> function then resolves the <code>Promise</code> with the resolved
|
||
path.</p>
|
||
<p>Only paths that can be converted to UTF8 strings are supported.</p>
|
||
<p>The optional <code>options</code> argument can be a string specifying an encoding, or an
|
||
object with an <code>encoding</code> property specifying the character encoding to use for
|
||
the path. If the <code>encoding</code> is set to <code>'buffer'</code>, the path returned will be
|
||
passed as a <code>Buffer</code> object.</p>
|
||
<p>On Linux, when Node.js is linked against musl libc, the procfs file system must
|
||
be mounted on <code>/proc</code> in order for this function to work. Glibc does not have
|
||
this restriction.</p>
|
||
<h3><code>fsPromises.rename(oldPath, newPath)</code><span><a class="mark" href="#fs_fspromises_rename_oldpath_newpath" id="fs_fspromises_rename_oldpath_newpath">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>oldPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>newPath</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Renames <code>oldPath</code> to <code>newPath</code> and resolves the <code>Promise</code> with no arguments
|
||
upon success.</p>
|
||
<h3><code>fsPromises.rmdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_rmdir_path_options" id="fs_fspromises_rmdir_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v12.16.0</td>
|
||
<td><p>The <code>maxBusyTries</code> option is renamed to <code>maxRetries</code>, and its default is 0. The <code>emfileWait</code> option has been removed, and <code>EMFILE</code> errors use the same retry logic as other errors. The <code>retryDelay</code> option is now supported. <code>ENFILE</code> errors are now retried.</p></td></tr>
|
||
<tr><td>v12.10.0</td>
|
||
<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<p></p><div class="api_stability api_stability_1"><a href="documentation.html#documentation_stability_index">Stability: 1</a> - Recursive removal is experimental.</div><p></p>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>maxRetries</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> If an <code>EBUSY</code>, <code>EMFILE</code>, <code>ENFILE</code>, <code>ENOTEMPTY</code>, or
|
||
<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear
|
||
backoff wait of <code>retryDelay</code> ms longer on each try. This option represents the
|
||
number of retries. This option is ignored if the <code>recursive</code> option is not
|
||
<code>true</code>. <strong>Default:</strong> <code>0</code>.</li>
|
||
<li><code>recursive</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If <code>true</code>, perform a recursive directory removal. In
|
||
recursive mode, errors are not reported if <code>path</code> does not exist, and
|
||
operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li>
|
||
<li><code>retryDelay</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The amount of time in milliseconds to wait between
|
||
retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>.
|
||
<strong>Default:</strong> <code>100</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Removes the directory identified by <code>path</code> then resolves the <code>Promise</code> with
|
||
no arguments upon success.</p>
|
||
<p>Using <code>fsPromises.rmdir()</code> on a file (not a directory) results in the
|
||
<code>Promise</code> being rejected with an <code>ENOENT</code> error on Windows and an <code>ENOTDIR</code>
|
||
error on POSIX.</p>
|
||
<h3><code>fsPromises.stat(path[, options])</code><span><a class="mark" href="#fs_fspromises_stat_path_options" id="fs_fspromises_stat_path_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<details class="changelog"><summary>History</summary>
|
||
<table>
|
||
<tbody><tr><th>Version</th><th>Changes</th></tr>
|
||
<tr><td>v10.5.0</td>
|
||
<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr>
|
||
<tr><td>v10.0.0</td>
|
||
<td><p><span>Added in: v10.0.0</span></p></td></tr>
|
||
</tbody></table>
|
||
</details>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a>
|
||
<ul>
|
||
<li><code>bigint</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether the numeric values in the returned
|
||
<a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>The <code>Promise</code> is resolved with the <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object for the given <code>path</code>.</p>
|
||
<h3><code>fsPromises.symlink(target, path[, type])</code><span><a class="mark" href="#fs_fspromises_symlink_target_path_type" id="fs_fspromises_symlink_target_path_type">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>target</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> <strong>Default:</strong> <code>'file'</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Creates a symbolic link then resolves the <code>Promise</code> with no arguments upon
|
||
success.</p>
|
||
<p>The <code>type</code> argument is only used on Windows platforms and can be one of <code>'dir'</code>,
|
||
<code>'file'</code>, or <code>'junction'</code>. Windows junction points require the destination path
|
||
to be absolute. When using <code>'junction'</code>, the <code>target</code> argument will
|
||
automatically be normalized to absolute path.</p>
|
||
<h3><code>fsPromises.truncate(path[, len])</code><span><a class="mark" href="#fs_fspromises_truncate_path_len" id="fs_fspromises_truncate_path_len">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>len</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0</code></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Truncates the <code>path</code> then resolves the <code>Promise</code> with no arguments upon
|
||
success. The <code>path</code> <em>must</em> be a string or <code>Buffer</code>.</p>
|
||
<h3><code>fsPromises.unlink(path)</code><span><a class="mark" href="#fs_fspromises_unlink_path" id="fs_fspromises_unlink_path">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronous <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>. The <code>Promise</code> is resolved with no arguments upon
|
||
success.</p>
|
||
<h3><code>fsPromises.utimes(path, atime, mtime)</code><span><a class="mark" href="#fs_fspromises_utimes_path_atime_mtime" id="fs_fspromises_utimes_path_atime_mtime">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>path</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a></li>
|
||
<li><code>atime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li><code>mtime</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Change the file system timestamps of the object referenced by <code>path</code> then
|
||
resolves the <code>Promise</code> with no arguments upon success.</p>
|
||
<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p>
|
||
<ul>
|
||
<li>Values can be either numbers representing Unix epoch time, <code>Date</code>s, or a
|
||
numeric string like <code>'123456789.0'</code>.</li>
|
||
<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or
|
||
<code>-Infinity</code>, an <code>Error</code> will be thrown.</li>
|
||
</ul>
|
||
<h3><code>fsPromises.writeFile(file, data[, options])</code><span><a class="mark" href="#fs_fspromises_writefile_file_data_options" id="fs_fspromises_writefile_file_data_options">#</a></span></h3>
|
||
<div class="api_metadata">
|
||
<span>Added in: v10.0.0</span>
|
||
</div>
|
||
<ul>
|
||
<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> filename or <code>FileHandle</code></li>
|
||
<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a></li>
|
||
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a>
|
||
<ul>
|
||
<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li>
|
||
<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li>
|
||
<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'w'</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li>
|
||
</ul>
|
||
<p>Asynchronously writes data to a file, replacing the file if it already exists.
|
||
<code>data</code> can be a string or a buffer. The <code>Promise</code> will be resolved with no
|
||
arguments upon success.</p>
|
||
<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p>
|
||
<p>If <code>options</code> is a string, then it specifies the encoding.</p>
|
||
<p>Any specified <code>FileHandle</code> has to support writing.</p>
|
||
<p>It is unsafe to use <code>fsPromises.writeFile()</code> multiple times on the same file
|
||
without waiting for the <code>Promise</code> to be resolved (or rejected).</p>
|
||
<h2>FS constants<span><a class="mark" href="#fs_fs_constants_1" id="fs_fs_constants_1">#</a></span></h2>
|
||
<p>The following constants are exported by <code>fs.constants</code>.</p>
|
||
<p>Not every constant will be available on every operating system.</p>
|
||
<p>To use more than one constant, use the bitwise OR <code>|</code> operator.</p>
|
||
<p>Example:</p>
|
||
<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);
|
||
|
||
<span class="hljs-keyword">const</span> {
|
||
O_RDWR,
|
||
O_CREAT,
|
||
O_EXCL
|
||
} = fs.constants;
|
||
|
||
fs.open(<span class="hljs-string">'/path/to/my/file'</span>, O_RDWR | O_CREAT | O_EXCL, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-comment">// ...</span>
|
||
});</code></pre>
|
||
<h3>File access constants<span><a class="mark" href="#fs_file_access_constants" id="fs_file_access_constants">#</a></span></h3>
|
||
<p>The following constants are meant for use with <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a>.</p>
|
||
<table>
|
||
<tbody><tr>
|
||
<th>Constant</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>F_OK</code></td>
|
||
<td>Flag indicating that the file is visible to the calling process.
|
||
This is useful for determining if a file exists, but says nothing
|
||
about <code>rwx</code> permissions. Default if no mode is specified.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>R_OK</code></td>
|
||
<td>Flag indicating that the file can be read by the calling process.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>W_OK</code></td>
|
||
<td>Flag indicating that the file can be written by the calling
|
||
process.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>X_OK</code></td>
|
||
<td>Flag indicating that the file can be executed by the calling
|
||
process. This has no effect on Windows
|
||
(will behave like <code>fs.constants.F_OK</code>).</td>
|
||
</tr>
|
||
</tbody></table>
|
||
<h3>File copy constants<span><a class="mark" href="#fs_file_copy_constants" id="fs_file_copy_constants">#</a></span></h3>
|
||
<p>The following constants are meant for use with <a href="#fs_fs_copyfile_src_dest_flags_callback"><code>fs.copyFile()</code></a>.</p>
|
||
<table>
|
||
<tbody><tr>
|
||
<th>Constant</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>COPYFILE_EXCL</code></td>
|
||
<td>If present, the copy operation will fail with an error if the
|
||
destination path already exists.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>COPYFILE_FICLONE</code></td>
|
||
<td>If present, the copy operation will attempt to create a
|
||
copy-on-write reflink. If the underlying platform does not support
|
||
copy-on-write, then a fallback copy mechanism is used.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>COPYFILE_FICLONE_FORCE</code></td>
|
||
<td>If present, the copy operation will attempt to create a
|
||
copy-on-write reflink. If the underlying platform does not support
|
||
copy-on-write, then the operation will fail with an error.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
<h3>File open constants<span><a class="mark" href="#fs_file_open_constants" id="fs_file_open_constants">#</a></span></h3>
|
||
<p>The following constants are meant for use with <code>fs.open()</code>.</p>
|
||
<table>
|
||
<tbody><tr>
|
||
<th>Constant</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_RDONLY</code></td>
|
||
<td>Flag indicating to open a file for read-only access.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_WRONLY</code></td>
|
||
<td>Flag indicating to open a file for write-only access.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_RDWR</code></td>
|
||
<td>Flag indicating to open a file for read-write access.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_CREAT</code></td>
|
||
<td>Flag indicating to create the file if it does not already exist.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_EXCL</code></td>
|
||
<td>Flag indicating that opening a file should fail if the
|
||
<code>O_CREAT</code> flag is set and the file already exists.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_NOCTTY</code></td>
|
||
<td>Flag indicating that if path identifies a terminal device, opening the
|
||
path shall not cause that terminal to become the controlling terminal for
|
||
the process (if the process does not already have one).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_TRUNC</code></td>
|
||
<td>Flag indicating that if the file exists and is a regular file, and the
|
||
file is opened successfully for write access, its length shall be truncated
|
||
to zero.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_APPEND</code></td>
|
||
<td>Flag indicating that data will be appended to the end of the file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_DIRECTORY</code></td>
|
||
<td>Flag indicating that the open should fail if the path is not a
|
||
directory.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_NOATIME</code></td>
|
||
<td>Flag indicating reading accesses to the file system will no longer
|
||
result in an update to the <code>atime</code> information associated with
|
||
the file. This flag is available on Linux operating systems only.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_NOFOLLOW</code></td>
|
||
<td>Flag indicating that the open should fail if the path is a symbolic
|
||
link.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_SYNC</code></td>
|
||
<td>Flag indicating that the file is opened for synchronized I/O with write
|
||
operations waiting for file integrity.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_DSYNC</code></td>
|
||
<td>Flag indicating that the file is opened for synchronized I/O with write
|
||
operations waiting for data integrity.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_SYMLINK</code></td>
|
||
<td>Flag indicating to open the symbolic link itself rather than the
|
||
resource it is pointing to.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_DIRECT</code></td>
|
||
<td>When set, an attempt will be made to minimize caching effects of file
|
||
I/O.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>O_NONBLOCK</code></td>
|
||
<td>Flag indicating to open the file in nonblocking mode when possible.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>UV_FS_O_FILEMAP</code></td>
|
||
<td>When set, a memory file mapping is used to access the file. This flag
|
||
is available on Windows operating systems only. On other operating systems,
|
||
this flag is ignored.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
<h3>File type constants<span><a class="mark" href="#fs_file_type_constants" id="fs_file_type_constants">#</a></span></h3>
|
||
<p>The following constants are meant for use with the <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object's
|
||
<code>mode</code> property for determining a file's type.</p>
|
||
<table>
|
||
<tbody><tr>
|
||
<th>Constant</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFMT</code></td>
|
||
<td>Bit mask used to extract the file type code.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFREG</code></td>
|
||
<td>File type constant for a regular file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFDIR</code></td>
|
||
<td>File type constant for a directory.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFCHR</code></td>
|
||
<td>File type constant for a character-oriented device file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFBLK</code></td>
|
||
<td>File type constant for a block-oriented device file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFIFO</code></td>
|
||
<td>File type constant for a FIFO/pipe.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFLNK</code></td>
|
||
<td>File type constant for a symbolic link.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IFSOCK</code></td>
|
||
<td>File type constant for a socket.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
<h3>File mode constants<span><a class="mark" href="#fs_file_mode_constants" id="fs_file_mode_constants">#</a></span></h3>
|
||
<p>The following constants are meant for use with the <a href="#fs_class_fs_stats"><code>fs.Stats</code></a> object's
|
||
<code>mode</code> property for determining the access permissions for a file.</p>
|
||
<table>
|
||
<tbody><tr>
|
||
<th>Constant</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IRWXU</code></td>
|
||
<td>File mode indicating readable, writable, and executable by owner.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IRUSR</code></td>
|
||
<td>File mode indicating readable by owner.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IWUSR</code></td>
|
||
<td>File mode indicating writable by owner.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IXUSR</code></td>
|
||
<td>File mode indicating executable by owner.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IRWXG</code></td>
|
||
<td>File mode indicating readable, writable, and executable by group.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IRGRP</code></td>
|
||
<td>File mode indicating readable by group.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IWGRP</code></td>
|
||
<td>File mode indicating writable by group.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IXGRP</code></td>
|
||
<td>File mode indicating executable by group.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IRWXO</code></td>
|
||
<td>File mode indicating readable, writable, and executable by others.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IROTH</code></td>
|
||
<td>File mode indicating readable by others.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IWOTH</code></td>
|
||
<td>File mode indicating writable by others.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>S_IXOTH</code></td>
|
||
<td>File mode indicating executable by others.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
<h2>File system flags<span><a class="mark" href="#fs_file_system_flags" id="fs_file_system_flags">#</a></span></h2>
|
||
<p>The following flags are available wherever the <code>flag</code> option takes a
|
||
string.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>'a'</code>: Open file for appending.
|
||
The file is created if it does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'ax'</code>: Like <code>'a'</code> but fails if the path exists.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'a+'</code>: Open file for reading and appending.
|
||
The file is created if it does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'ax+'</code>: Like <code>'a+'</code> but fails if the path exists.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'as'</code>: Open file for appending in synchronous mode.
|
||
The file is created if it does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'as+'</code>: Open file for reading and appending in synchronous mode.
|
||
The file is created if it does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'r'</code>: Open file for reading.
|
||
An exception occurs if the file does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'r+'</code>: Open file for reading and writing.
|
||
An exception occurs if the file does not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'rs+'</code>: Open file for reading and writing in synchronous mode. Instructs
|
||
the operating system to bypass the local file system cache.</p>
|
||
<p>This is primarily useful for opening files on NFS mounts as it allows
|
||
skipping the potentially stale local cache. It has a very real impact on
|
||
I/O performance so using this flag is not recommended unless it is needed.</p>
|
||
<p>This doesn't turn <code>fs.open()</code> or <code>fsPromises.open()</code> into a synchronous
|
||
blocking call. If synchronous operation is desired, something like
|
||
<code>fs.openSync()</code> should be used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'w'</code>: Open file for writing.
|
||
The file is created (if it does not exist) or truncated (if it exists).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'wx'</code>: Like <code>'w'</code> but fails if the path exists.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'w+'</code>: Open file for reading and writing.
|
||
The file is created (if it does not exist) or truncated (if it exists).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>'wx+'</code>: Like <code>'w+'</code> but fails if the path exists.</p>
|
||
</li>
|
||
</ul>
|
||
<p><code>flag</code> can also be a number as documented by <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a>; commonly used constants
|
||
are available from <code>fs.constants</code>. On Windows, flags are translated to
|
||
their equivalent ones where applicable, e.g. <code>O_WRONLY</code> to <code>FILE_GENERIC_WRITE</code>,
|
||
or <code>O_EXCL|O_CREAT</code> to <code>CREATE_NEW</code>, as accepted by <code>CreateFileW</code>.</p>
|
||
<p>The exclusive flag <code>'x'</code> (<code>O_EXCL</code> flag in <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a>) causes the operation to
|
||
return an error if the path already exists. On POSIX, if the path is a symbolic
|
||
link, using <code>O_EXCL</code> returns an error even if the link is to a path that does
|
||
not exist. The exclusive flag may or may not work with network file systems.</p>
|
||
<p>On Linux, positional writes don't work when the file is opened in append mode.
|
||
The kernel ignores the position argument and always appends the data to
|
||
the end of the file.</p>
|
||
<p>Modifying a file rather than replacing it may require a flags mode of <code>'r+'</code>
|
||
rather than the default mode <code>'w'</code>.</p>
|
||
<p>The behavior of some flags are platform-specific. As such, opening a directory
|
||
on macOS and Linux with the <code>'a+'</code> flag, as in the example below, will return an
|
||
error. In contrast, on Windows and FreeBSD, a file descriptor or a <code>FileHandle</code>
|
||
will be returned.</p>
|
||
<pre><code class="language-js"><span class="hljs-comment">// macOS and Linux</span>
|
||
fs.open(<span class="hljs-string">'<directory>'</span>, <span class="hljs-string">'a+'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, open <directory>]</span>
|
||
});
|
||
|
||
<span class="hljs-comment">// Windows and FreeBSD</span>
|
||
fs.open(<span class="hljs-string">'<directory>'</span>, <span class="hljs-string">'a+'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> {
|
||
<span class="hljs-comment">// => null, <fd></span>
|
||
});</code></pre>
|
||
<p>On Windows, opening an existing hidden file using the <code>'w'</code> flag (either
|
||
through <code>fs.open()</code> or <code>fs.writeFile()</code> or <code>fsPromises.open()</code>) will fail with
|
||
<code>EPERM</code>. Existing hidden files can be opened for writing with the <code>'r+'</code> flag.</p>
|
||
<p>A call to <code>fs.ftruncate()</code> or <code>filehandle.truncate()</code> can be used to reset
|
||
the file contents.</p>
|
||
<!-- API END -->
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|