1<!DOCTYPE html> 2<html lang="en"> 3<head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width"> 6 <meta name="nodejs.org:node-version" content="v14.19.1"> 7 <title>File system | Node.js v14.19.1 Documentation</title> 8 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 9 <link rel="stylesheet" href="assets/style.css"> 10 <link rel="stylesheet" href="assets/hljs.css"> 11 <link rel="canonical" href="https://nodejs.org/api/fs.html"> 12</head> 13<body class="alt apidoc" id="api-section-fs"> 14 <div id="content" class="clearfix"> 15 <div id="column2" class="interior"> 16 <div id="intro" class="interior"> 17 <a href="/" title="Go back to the home page"> 18 Node.js 19 </a> 20 </div> 21 <ul> 22<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 23<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 24</ul> 25<hr class="line"> 26<ul> 27<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 28<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 29<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 30<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 31<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 32<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 33<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 34<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 35<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 36<li><a href="console.html" class="nav-console">Console</a></li> 37<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 38<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 39<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 40<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 41<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 42<li><a href="dns.html" class="nav-dns">DNS</a></li> 43<li><a href="domain.html" class="nav-domain">Domain</a></li> 44<li><a href="errors.html" class="nav-errors">Errors</a></li> 45<li><a href="events.html" class="nav-events">Events</a></li> 46<li><a href="fs.html" class="nav-fs active">File system</a></li> 47<li><a href="globals.html" class="nav-globals">Globals</a></li> 48<li><a href="http.html" class="nav-http">HTTP</a></li> 49<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 50<li><a href="https.html" class="nav-https">HTTPS</a></li> 51<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 52<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 53<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 54<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 55<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li> 56<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 57<li><a href="net.html" class="nav-net">Net</a></li> 58<li><a href="os.html" class="nav-os">OS</a></li> 59<li><a href="path.html" class="nav-path">Path</a></li> 60<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 61<li><a href="policy.html" class="nav-policy">Policies</a></li> 62<li><a href="process.html" class="nav-process">Process</a></li> 63<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 64<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 65<li><a href="readline.html" class="nav-readline">Readline</a></li> 66<li><a href="repl.html" class="nav-repl">REPL</a></li> 67<li><a href="report.html" class="nav-report">Report</a></li> 68<li><a href="stream.html" class="nav-stream">Stream</a></li> 69<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 70<li><a href="timers.html" class="nav-timers">Timers</a></li> 71<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 72<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 73<li><a href="tty.html" class="nav-tty">TTY</a></li> 74<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 75<li><a href="url.html" class="nav-url">URL</a></li> 76<li><a href="util.html" class="nav-util">Utilities</a></li> 77<li><a href="v8.html" class="nav-v8">V8</a></li> 78<li><a href="vm.html" class="nav-vm">VM</a></li> 79<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 80<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 81<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 82</ul> 83<hr class="line"> 84<ul> 85<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 86</ul> 87 </div> 88 89 <div id="column1" data-id="fs" class="interior"> 90 <header> 91 <div class="header-container"> 92 <h1>Node.js v14.19.1 documentation</h1> 93 <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 94 <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 95 <path fill="none" d="M0 0h24v24H0z" /> 96 <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 97 <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 98 </svg> 99 <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 100 <path d="M0 0h24v24H0z" fill="none" /> 101 <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 102 </svg> 103 </button> 104 </div> 105 <div id="gtoc"> 106 <ul> 107 <li> 108 <a href="index.html">Index</a> 109 </li> 110 <li> 111 <a href="all.html">View on single page</a> 112 </li> 113 <li> 114 <a href="fs.json">View as JSON</a> 115 </li> 116 117 <li class="version-picker"> 118 <a href="#">View another version <span>▼</span></a> 119 <ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v17.x/api/fs.html">17.x</a></li> 120<li><a href="https://nodejs.org/docs/latest-v16.x/api/fs.html">16.x <b>LTS</b></a></li> 121<li><a href="https://nodejs.org/docs/latest-v15.x/api/fs.html">15.x</a></li> 122<li><a href="https://nodejs.org/docs/latest-v14.x/api/fs.html">14.x <b>LTS</b></a></li> 123<li><a href="https://nodejs.org/docs/latest-v13.x/api/fs.html">13.x</a></li> 124<li><a href="https://nodejs.org/docs/latest-v12.x/api/fs.html">12.x <b>LTS</b></a></li> 125<li><a href="https://nodejs.org/docs/latest-v11.x/api/fs.html">11.x</a></li> 126<li><a href="https://nodejs.org/docs/latest-v10.x/api/fs.html">10.x</a></li> 127<li><a href="https://nodejs.org/docs/latest-v9.x/api/fs.html">9.x</a></li> 128<li><a href="https://nodejs.org/docs/latest-v8.x/api/fs.html">8.x</a></li> 129<li><a href="https://nodejs.org/docs/latest-v7.x/api/fs.html">7.x</a></li> 130<li><a href="https://nodejs.org/docs/latest-v6.x/api/fs.html">6.x</a></li> 131<li><a href="https://nodejs.org/docs/latest-v5.x/api/fs.html">5.x</a></li> 132<li><a href="https://nodejs.org/docs/latest-v4.x/api/fs.html">4.x</a></li> 133<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/fs.html">0.12.x</a></li> 134<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/fs.html">0.10.x</a></li></ol> 135 </li> 136 137 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/fs.md">Edit on GitHub</a></li> 138 </ul> 139 </div> 140 <hr> 141 </header> 142 143 <details id="toc" open><summary>Table of contents</summary><ul> 144<li><span class="stability_2"><a href="#fs_file_system">File system</a></span> 145<ul> 146<li><a href="#fs_promise_example">Promise example</a></li> 147<li><a href="#fs_callback_example">Callback example</a></li> 148<li><a href="#fs_synchronous_example">Synchronous example</a></li> 149<li><a href="#fs_promises_api">Promises API</a> 150<ul> 151<li><a href="#fs_class_filehandle">Class: <code>FileHandle</code></a> 152<ul> 153<li><a href="#fs_filehandle_appendfile_data_options"><code>filehandle.appendFile(data[, options])</code></a></li> 154<li><a href="#fs_filehandle_chmod_mode"><code>filehandle.chmod(mode)</code></a></li> 155<li><a href="#fs_filehandle_chown_uid_gid"><code>filehandle.chown(uid, gid)</code></a></li> 156<li><a href="#fs_filehandle_close"><code>filehandle.close()</code></a></li> 157<li><a href="#fs_filehandle_datasync"><code>filehandle.datasync()</code></a></li> 158<li><a href="#fs_filehandle_fd"><code>filehandle.fd</code></a></li> 159<li><a href="#fs_filehandle_read_buffer_offset_length_position"><code>filehandle.read(buffer, offset, length, position)</code></a></li> 160<li><a href="#fs_filehandle_read_options"><code>filehandle.read([options])</code></a></li> 161<li><a href="#fs_filehandle_readfile_options"><code>filehandle.readFile(options)</code></a></li> 162<li><a href="#fs_filehandle_readv_buffers_position"><code>filehandle.readv(buffers[, position])</code></a></li> 163<li><a href="#fs_filehandle_stat_options"><code>filehandle.stat([options])</code></a></li> 164<li><a href="#fs_filehandle_sync"><code>filehandle.sync()</code></a></li> 165<li><a href="#fs_filehandle_truncate_len"><code>filehandle.truncate(len)</code></a></li> 166<li><a href="#fs_filehandle_utimes_atime_mtime"><code>filehandle.utimes(atime, mtime)</code></a></li> 167<li><a href="#fs_filehandle_write_buffer_offset_length_position"><code>filehandle.write(buffer[, offset[, length[, position]]])</code></a></li> 168<li><a href="#fs_filehandle_write_string_position_encoding"><code>filehandle.write(string[, position[, encoding]])</code></a></li> 169<li><a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile(data, options)</code></a></li> 170<li><a href="#fs_filehandle_writev_buffers_position"><code>filehandle.writev(buffers[, position])</code></a></li> 171</ul> 172</li> 173<li><a href="#fs_fspromises_access_path_mode"><code>fsPromises.access(path[, mode])</code></a></li> 174<li><a href="#fs_fspromises_appendfile_path_data_options"><code>fsPromises.appendFile(path, data[, options])</code></a></li> 175<li><a href="#fs_fspromises_chmod_path_mode"><code>fsPromises.chmod(path, mode)</code></a></li> 176<li><a href="#fs_fspromises_chown_path_uid_gid"><code>fsPromises.chown(path, uid, gid)</code></a></li> 177<li><a href="#fs_fspromises_copyfile_src_dest_mode"><code>fsPromises.copyFile(src, dest[, mode])</code></a></li> 178<li><a href="#fs_fspromises_lchmod_path_mode"><code>fsPromises.lchmod(path, mode)</code></a></li> 179<li><a href="#fs_fspromises_lchown_path_uid_gid"><code>fsPromises.lchown(path, uid, gid)</code></a></li> 180<li><a href="#fs_fspromises_lutimes_path_atime_mtime"><code>fsPromises.lutimes(path, atime, mtime)</code></a></li> 181<li><a href="#fs_fspromises_link_existingpath_newpath"><code>fsPromises.link(existingPath, newPath)</code></a></li> 182<li><a href="#fs_fspromises_lstat_path_options"><code>fsPromises.lstat(path[, options])</code></a></li> 183<li><a href="#fs_fspromises_mkdir_path_options"><code>fsPromises.mkdir(path[, options])</code></a></li> 184<li><a href="#fs_fspromises_mkdtemp_prefix_options"><code>fsPromises.mkdtemp(prefix[, options])</code></a></li> 185<li><a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open(path, flags[, mode])</code></a></li> 186<li><a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir(path[, options])</code></a></li> 187<li><a href="#fs_fspromises_readdir_path_options"><code>fsPromises.readdir(path[, options])</code></a></li> 188<li><a href="#fs_fspromises_readfile_path_options"><code>fsPromises.readFile(path[, options])</code></a></li> 189<li><a href="#fs_fspromises_readlink_path_options"><code>fsPromises.readlink(path[, options])</code></a></li> 190<li><a href="#fs_fspromises_realpath_path_options"><code>fsPromises.realpath(path[, options])</code></a></li> 191<li><a href="#fs_fspromises_rename_oldpath_newpath"><code>fsPromises.rename(oldPath, newPath)</code></a></li> 192<li><a href="#fs_fspromises_rmdir_path_options"><code>fsPromises.rmdir(path[, options])</code></a></li> 193<li><a href="#fs_fspromises_rm_path_options"><code>fsPromises.rm(path[, options])</code></a></li> 194<li><a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat(path[, options])</code></a></li> 195<li><a href="#fs_fspromises_symlink_target_path_type"><code>fsPromises.symlink(target, path[, type])</code></a></li> 196<li><a href="#fs_fspromises_truncate_path_len"><code>fsPromises.truncate(path[, len])</code></a></li> 197<li><a href="#fs_fspromises_unlink_path"><code>fsPromises.unlink(path)</code></a></li> 198<li><a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes(path, atime, mtime)</code></a></li> 199<li><a href="#fs_fspromises_watch_filename_options"><code>fsPromises.watch(filename[, options])</code></a></li> 200<li><a href="#fs_fspromises_writefile_file_data_options"><code>fsPromises.writeFile(file, data[, options])</code></a></li> 201</ul> 202</li> 203<li><a href="#fs_callback_api">Callback API</a> 204<ul> 205<li><a href="#fs_fs_access_path_mode_callback"><code>fs.access(path[, mode], callback)</code></a></li> 206<li><a href="#fs_fs_appendfile_path_data_options_callback"><code>fs.appendFile(path, data[, options], callback)</code></a></li> 207<li><a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod(path, mode, callback)</code></a> 208<ul> 209<li><a href="#fs_file_modes">File modes</a></li> 210</ul> 211</li> 212<li><a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown(path, uid, gid, callback)</code></a></li> 213<li><a href="#fs_fs_close_fd_callback"><code>fs.close(fd[, callback])</code></a></li> 214<li><a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile(src, dest[, mode], callback)</code></a></li> 215<li><a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream(path[, options])</code></a></li> 216<li><a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream(path[, options])</code></a></li> 217<li><span class="stability_0"><a href="#fs_fs_exists_path_callback"><code>fs.exists(path, callback)</code></a></span></li> 218<li><a href="#fs_fs_fchmod_fd_mode_callback"><code>fs.fchmod(fd, mode, callback)</code></a></li> 219<li><a href="#fs_fs_fchown_fd_uid_gid_callback"><code>fs.fchown(fd, uid, gid, callback)</code></a></li> 220<li><a href="#fs_fs_fdatasync_fd_callback"><code>fs.fdatasync(fd, callback)</code></a></li> 221<li><a href="#fs_fs_fstat_fd_options_callback"><code>fs.fstat(fd[, options], callback)</code></a></li> 222<li><a href="#fs_fs_fsync_fd_callback"><code>fs.fsync(fd, callback)</code></a></li> 223<li><a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate(fd[, len], callback)</code></a></li> 224<li><a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes(fd, atime, mtime, callback)</code></a></li> 225<li><a href="#fs_fs_lchmod_path_mode_callback"><code>fs.lchmod(path, mode, callback)</code></a></li> 226<li><a href="#fs_fs_lchown_path_uid_gid_callback"><code>fs.lchown(path, uid, gid, callback)</code></a></li> 227<li><a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes(path, atime, mtime, callback)</code></a></li> 228<li><a href="#fs_fs_link_existingpath_newpath_callback"><code>fs.link(existingPath, newPath, callback)</code></a></li> 229<li><a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat(path[, options], callback)</code></a></li> 230<li><a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir(path[, options], callback)</code></a></li> 231<li><a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp(prefix[, options], callback)</code></a></li> 232<li><a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open(path[, flags[, mode]], callback)</code></a></li> 233<li><a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir(path[, options], callback)</code></a></li> 234<li><a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read(fd, buffer, offset, length, position, callback)</code></a></li> 235<li><a href="#fs_fs_read_fd_options_callback"><code>fs.read(fd, [options,] callback)</code></a></li> 236<li><a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir(path[, options], callback)</code></a></li> 237<li><a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile(path[, options], callback)</code></a> 238<ul> 239<li><a href="#fs_file_descriptors">File descriptors</a></li> 240<li><a href="#fs_performance_considerations">Performance Considerations</a></li> 241</ul> 242</li> 243<li><a href="#fs_fs_readlink_path_options_callback"><code>fs.readlink(path[, options], callback)</code></a></li> 244<li><a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv(fd, buffers[, position], callback)</code></a></li> 245<li><a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath(path[, options], callback)</code></a></li> 246<li><a href="#fs_fs_realpath_native_path_options_callback"><code>fs.realpath.native(path[, options], callback)</code></a></li> 247<li><a href="#fs_fs_rename_oldpath_newpath_callback"><code>fs.rename(oldPath, newPath, callback)</code></a></li> 248<li><a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir(path[, options], callback)</code></a></li> 249<li><a href="#fs_fs_rm_path_options_callback"><code>fs.rm(path[, options], callback)</code></a></li> 250<li><a href="#fs_fs_stat_path_options_callback"><code>fs.stat(path[, options], callback)</code></a></li> 251<li><a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink(target, path[, type], callback)</code></a></li> 252<li><a href="#fs_fs_truncate_path_len_callback"><code>fs.truncate(path[, len], callback)</code></a></li> 253<li><a href="#fs_fs_unlink_path_callback"><code>fs.unlink(path, callback)</code></a></li> 254<li><a href="#fs_fs_unwatchfile_filename_listener"><code>fs.unwatchFile(filename[, listener])</code></a></li> 255<li><a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes(path, atime, mtime, callback)</code></a></li> 256<li><a href="#fs_fs_watch_filename_options_listener"><code>fs.watch(filename[, options][, listener])</code></a> 257<ul> 258<li><a href="#fs_caveats">Caveats</a> 259<ul> 260<li><a href="#fs_availability">Availability</a></li> 261<li><a href="#fs_inodes">Inodes</a></li> 262<li><a href="#fs_filename_argument">Filename argument</a></li> 263</ul> 264</li> 265</ul> 266</li> 267<li><a href="#fs_fs_watchfile_filename_options_listener"><code>fs.watchFile(filename[, options], listener)</code></a></li> 268<li><a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer[, offset[, length[, position]]], callback)</code></a></li> 269<li><a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string[, position[, encoding]], callback)</code></a></li> 270<li><a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile(file, data[, options], callback)</code></a> 271<ul> 272<li><a href="#fs_using_fs_writefile_with_file_descriptors">Using <code>fs.writeFile()</code> with file descriptors</a></li> 273</ul> 274</li> 275<li><a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev(fd, buffers[, position], callback)</code></a></li> 276</ul> 277</li> 278<li><a href="#fs_synchronous_api">Synchronous API</a> 279<ul> 280<li><a href="#fs_fs_accesssync_path_mode"><code>fs.accessSync(path[, mode])</code></a></li> 281<li><a href="#fs_fs_appendfilesync_path_data_options"><code>fs.appendFileSync(path, data[, options])</code></a></li> 282<li><a href="#fs_fs_chmodsync_path_mode"><code>fs.chmodSync(path, mode)</code></a></li> 283<li><a href="#fs_fs_chownsync_path_uid_gid"><code>fs.chownSync(path, uid, gid)</code></a></li> 284<li><a href="#fs_fs_closesync_fd"><code>fs.closeSync(fd)</code></a></li> 285<li><a href="#fs_fs_copyfilesync_src_dest_mode"><code>fs.copyFileSync(src, dest[, mode])</code></a></li> 286<li><a href="#fs_fs_existssync_path"><code>fs.existsSync(path)</code></a></li> 287<li><a href="#fs_fs_fchmodsync_fd_mode"><code>fs.fchmodSync(fd, mode)</code></a></li> 288<li><a href="#fs_fs_fchownsync_fd_uid_gid"><code>fs.fchownSync(fd, uid, gid)</code></a></li> 289<li><a href="#fs_fs_fdatasyncsync_fd"><code>fs.fdatasyncSync(fd)</code></a></li> 290<li><a href="#fs_fs_fstatsync_fd_options"><code>fs.fstatSync(fd[, options])</code></a></li> 291<li><a href="#fs_fs_fsyncsync_fd"><code>fs.fsyncSync(fd)</code></a></li> 292<li><a href="#fs_fs_ftruncatesync_fd_len"><code>fs.ftruncateSync(fd[, len])</code></a></li> 293<li><a href="#fs_fs_futimessync_fd_atime_mtime"><code>fs.futimesSync(fd, atime, mtime)</code></a></li> 294<li><a href="#fs_fs_lchmodsync_path_mode"><code>fs.lchmodSync(path, mode)</code></a></li> 295<li><a href="#fs_fs_lchownsync_path_uid_gid"><code>fs.lchownSync(path, uid, gid)</code></a></li> 296<li><a href="#fs_fs_lutimessync_path_atime_mtime"><code>fs.lutimesSync(path, atime, mtime)</code></a></li> 297<li><a href="#fs_fs_linksync_existingpath_newpath"><code>fs.linkSync(existingPath, newPath)</code></a></li> 298<li><a href="#fs_fs_lstatsync_path_options"><code>fs.lstatSync(path[, options])</code></a></li> 299<li><a href="#fs_fs_mkdirsync_path_options"><code>fs.mkdirSync(path[, options])</code></a></li> 300<li><a href="#fs_fs_mkdtempsync_prefix_options"><code>fs.mkdtempSync(prefix[, options])</code></a></li> 301<li><a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync(path[, options])</code></a></li> 302<li><a href="#fs_fs_opensync_path_flags_mode"><code>fs.openSync(path[, flags[, mode]])</code></a></li> 303<li><a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync(path[, options])</code></a></li> 304<li><a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync(path[, options])</code></a></li> 305<li><a href="#fs_fs_readlinksync_path_options"><code>fs.readlinkSync(path[, options])</code></a></li> 306<li><a href="#fs_fs_readsync_fd_buffer_offset_length_position"><code>fs.readSync(fd, buffer, offset, length, position)</code></a></li> 307<li><a href="#fs_fs_readsync_fd_buffer_options"><code>fs.readSync(fd, buffer, [options])</code></a></li> 308<li><a href="#fs_fs_readvsync_fd_buffers_position"><code>fs.readvSync(fd, buffers[, position])</code></a></li> 309<li><a href="#fs_fs_realpathsync_path_options"><code>fs.realpathSync(path[, options])</code></a></li> 310<li><a href="#fs_fs_realpathsync_native_path_options"><code>fs.realpathSync.native(path[, options])</code></a></li> 311<li><a href="#fs_fs_renamesync_oldpath_newpath"><code>fs.renameSync(oldPath, newPath)</code></a></li> 312<li><a href="#fs_fs_rmdirsync_path_options"><code>fs.rmdirSync(path[, options])</code></a></li> 313<li><a href="#fs_fs_rmsync_path_options"><code>fs.rmSync(path[, options])</code></a></li> 314<li><a href="#fs_fs_statsync_path_options"><code>fs.statSync(path[, options])</code></a></li> 315<li><a href="#fs_fs_symlinksync_target_path_type"><code>fs.symlinkSync(target, path[, type])</code></a></li> 316<li><a href="#fs_fs_truncatesync_path_len"><code>fs.truncateSync(path[, len])</code></a></li> 317<li><a href="#fs_fs_unlinksync_path"><code>fs.unlinkSync(path)</code></a></li> 318<li><a href="#fs_fs_utimessync_path_atime_mtime"><code>fs.utimesSync(path, atime, mtime)</code></a></li> 319<li><a href="#fs_fs_writefilesync_file_data_options"><code>fs.writeFileSync(file, data[, options])</code></a></li> 320<li><a href="#fs_fs_writesync_fd_buffer_offset_length_position"><code>fs.writeSync(fd, buffer[, offset[, length[, position]]])</code></a></li> 321<li><a href="#fs_fs_writesync_fd_string_position_encoding"><code>fs.writeSync(fd, string[, position[, encoding]])</code></a></li> 322<li><a href="#fs_fs_writevsync_fd_buffers_position"><code>fs.writevSync(fd, buffers[, position])</code></a></li> 323</ul> 324</li> 325<li><a href="#fs_common_objects">Common Objects</a> 326<ul> 327<li><a href="#fs_class_fs_dir">Class: <code>fs.Dir</code></a> 328<ul> 329<li><a href="#fs_dir_close"><code>dir.close()</code></a></li> 330<li><a href="#fs_dir_close_callback"><code>dir.close(callback)</code></a></li> 331<li><a href="#fs_dir_closesync"><code>dir.closeSync()</code></a></li> 332<li><a href="#fs_dir_path"><code>dir.path</code></a></li> 333<li><a href="#fs_dir_read"><code>dir.read()</code></a></li> 334<li><a href="#fs_dir_read_callback"><code>dir.read(callback)</code></a></li> 335<li><a href="#fs_dir_readsync"><code>dir.readSync()</code></a></li> 336<li><a href="#fs_dir_symbol_asynciterator"><code>dir[Symbol.asyncIterator]()</code></a></li> 337</ul> 338</li> 339<li><a href="#fs_class_fs_dirent">Class: <code>fs.Dirent</code></a> 340<ul> 341<li><a href="#fs_dirent_isblockdevice"><code>dirent.isBlockDevice()</code></a></li> 342<li><a href="#fs_dirent_ischaracterdevice"><code>dirent.isCharacterDevice()</code></a></li> 343<li><a href="#fs_dirent_isdirectory"><code>dirent.isDirectory()</code></a></li> 344<li><a href="#fs_dirent_isfifo"><code>dirent.isFIFO()</code></a></li> 345<li><a href="#fs_dirent_isfile"><code>dirent.isFile()</code></a></li> 346<li><a href="#fs_dirent_issocket"><code>dirent.isSocket()</code></a></li> 347<li><a href="#fs_dirent_issymboliclink"><code>dirent.isSymbolicLink()</code></a></li> 348<li><a href="#fs_dirent_name"><code>dirent.name</code></a></li> 349</ul> 350</li> 351<li><a href="#fs_class_fs_fswatcher">Class: <code>fs.FSWatcher</code></a> 352<ul> 353<li><a href="#fs_event_change">Event: <code>'change'</code></a></li> 354<li><a href="#fs_event_close">Event: <code>'close'</code></a></li> 355<li><a href="#fs_event_error">Event: <code>'error'</code></a></li> 356<li><a href="#fs_watcher_close"><code>watcher.close()</code></a></li> 357<li><a href="#fs_watcher_ref"><code>watcher.ref()</code></a></li> 358<li><a href="#fs_watcher_unref"><code>watcher.unref()</code></a></li> 359</ul> 360</li> 361<li><a href="#fs_class_fs_statwatcher">Class: <code>fs.StatWatcher</code></a> 362<ul> 363<li><a href="#fs_watcher_ref_1"><code>watcher.ref()</code></a></li> 364<li><a href="#fs_watcher_unref_1"><code>watcher.unref()</code></a></li> 365</ul> 366</li> 367<li><a href="#fs_class_fs_readstream">Class: <code>fs.ReadStream</code></a> 368<ul> 369<li><a href="#fs_event_close_1">Event: <code>'close'</code></a></li> 370<li><a href="#fs_event_open">Event: <code>'open'</code></a></li> 371<li><a href="#fs_event_ready">Event: <code>'ready'</code></a></li> 372<li><a href="#fs_readstream_bytesread"><code>readStream.bytesRead</code></a></li> 373<li><a href="#fs_readstream_path"><code>readStream.path</code></a></li> 374<li><a href="#fs_readstream_pending"><code>readStream.pending</code></a></li> 375</ul> 376</li> 377<li><a href="#fs_class_fs_stats">Class: <code>fs.Stats</code></a> 378<ul> 379<li><a href="#fs_stats_isblockdevice"><code>stats.isBlockDevice()</code></a></li> 380<li><a href="#fs_stats_ischaracterdevice"><code>stats.isCharacterDevice()</code></a></li> 381<li><a href="#fs_stats_isdirectory"><code>stats.isDirectory()</code></a></li> 382<li><a href="#fs_stats_isfifo"><code>stats.isFIFO()</code></a></li> 383<li><a href="#fs_stats_isfile"><code>stats.isFile()</code></a></li> 384<li><a href="#fs_stats_issocket"><code>stats.isSocket()</code></a></li> 385<li><a href="#fs_stats_issymboliclink"><code>stats.isSymbolicLink()</code></a></li> 386<li><a href="#fs_stats_dev"><code>stats.dev</code></a></li> 387<li><a href="#fs_stats_ino"><code>stats.ino</code></a></li> 388<li><a href="#fs_stats_mode"><code>stats.mode</code></a></li> 389<li><a href="#fs_stats_nlink"><code>stats.nlink</code></a></li> 390<li><a href="#fs_stats_uid"><code>stats.uid</code></a></li> 391<li><a href="#fs_stats_gid"><code>stats.gid</code></a></li> 392<li><a href="#fs_stats_rdev"><code>stats.rdev</code></a></li> 393<li><a href="#fs_stats_size"><code>stats.size</code></a></li> 394<li><a href="#fs_stats_blksize"><code>stats.blksize</code></a></li> 395<li><a href="#fs_stats_blocks"><code>stats.blocks</code></a></li> 396<li><a href="#fs_stats_atimems"><code>stats.atimeMs</code></a></li> 397<li><a href="#fs_stats_mtimems"><code>stats.mtimeMs</code></a></li> 398<li><a href="#fs_stats_ctimems"><code>stats.ctimeMs</code></a></li> 399<li><a href="#fs_stats_birthtimems"><code>stats.birthtimeMs</code></a></li> 400<li><a href="#fs_stats_atimens"><code>stats.atimeNs</code></a></li> 401<li><a href="#fs_stats_mtimens"><code>stats.mtimeNs</code></a></li> 402<li><a href="#fs_stats_ctimens"><code>stats.ctimeNs</code></a></li> 403<li><a href="#fs_stats_birthtimens"><code>stats.birthtimeNs</code></a></li> 404<li><a href="#fs_stats_atime"><code>stats.atime</code></a></li> 405<li><a href="#fs_stats_mtime"><code>stats.mtime</code></a></li> 406<li><a href="#fs_stats_ctime"><code>stats.ctime</code></a></li> 407<li><a href="#fs_stats_birthtime"><code>stats.birthtime</code></a></li> 408<li><a href="#fs_stat_time_values">Stat time values</a></li> 409</ul> 410</li> 411<li><a href="#fs_class_fs_writestream">Class: <code>fs.WriteStream</code></a> 412<ul> 413<li><a href="#fs_event_close_2">Event: <code>'close'</code></a></li> 414<li><a href="#fs_event_open_1">Event: <code>'open'</code></a></li> 415<li><a href="#fs_event_ready_1">Event: <code>'ready'</code></a></li> 416<li><a href="#fs_writestream_byteswritten"><code>writeStream.bytesWritten</code></a></li> 417<li><a href="#fs_writestream_close_callback"><code>writeStream.close([callback])</code></a></li> 418<li><a href="#fs_writestream_path"><code>writeStream.path</code></a></li> 419<li><a href="#fs_writestream_pending"><code>writeStream.pending</code></a></li> 420</ul> 421</li> 422<li><a href="#fs_fs_constants"><code>fs.constants</code></a> 423<ul> 424<li><a href="#fs_fs_constants_1">FS constants</a> 425<ul> 426<li><a href="#fs_file_access_constants">File access constants</a></li> 427<li><a href="#fs_file_copy_constants">File copy constants</a></li> 428<li><a href="#fs_file_open_constants">File open constants</a></li> 429<li><a href="#fs_file_type_constants">File type constants</a></li> 430<li><a href="#fs_file_mode_constants">File mode constants</a></li> 431</ul> 432</li> 433</ul> 434</li> 435</ul> 436</li> 437<li><a href="#fs_notes">Notes</a> 438<ul> 439<li><a href="#fs_ordering_of_callback_and_promise_based_operations">Ordering of callback and promise-based operations</a></li> 440<li><a href="#fs_file_paths">File paths</a> 441<ul> 442<li><a href="#fs_string_paths">String paths</a></li> 443<li><a href="#fs_file_url_paths">File URL paths</a> 444<ul> 445<li><a href="#fs_platform_specific_considerations">Platform-specific considerations</a></li> 446</ul> 447</li> 448<li><a href="#fs_buffer_paths">Buffer paths</a></li> 449<li><a href="#fs_per_drive_working_directories_on_windows">Per-drive working directories on Windows</a></li> 450</ul> 451</li> 452<li><a href="#fs_file_descriptors_1">File descriptors</a></li> 453<li><a href="#fs_threadpool_usage">Threadpool usage</a></li> 454<li><a href="#fs_file_system_flags">File system flags</a></li> 455</ul> 456</li> 457</ul> 458</li> 459</ul></details> 460 461 <div id="apicontent"> 462 <h2>File system<span><a class="mark" href="#fs_file_system" id="fs_file_system">#</a></span></h2> 463 464<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p> 465 466<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v14.19.1/lib/fs.js">lib/fs.js</a></p> 467<p>The <code>fs</code> module enables interacting with the file system in a 468way modeled on standard POSIX functions.</p> 469<p>To use the promise-based APIs:</p> 470 471<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> fs <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs/promises'</span>);</code></pre> 472<p>To use the callback and sync APIs:</p> 473 474<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> fs <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>;</code><code class="language-js cjs"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>);</code></pre> 475<p>All file system operations have synchronous, callback, and promise-based 476forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).</p> 477<section><h3>Promise example<span><a class="mark" href="#fs_promise_example" id="fs_promise_example">#</a></span></h3> 478<p>Promise-based operations return a promise that is fulfilled when the 479asynchronous operation is complete.</p> 480 481<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { unlink } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 482 483<span class="hljs-keyword">try</span> { 484 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(<span class="hljs-string">'/tmp/hello'</span>); 485 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 486} <span class="hljs-keyword">catch</span> (error) { 487 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'there was an error:'</span>, error.<span class="hljs-property">message</span>); 488}</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { unlink } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs/promises'</span>); 489 490(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params">path</span>) { 491 <span class="hljs-keyword">try</span> { 492 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(path); 493 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`successfully deleted <span class="hljs-subst">${path}</span>`</span>); 494 } <span class="hljs-keyword">catch</span> (error) { 495 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'there was an error:'</span>, error.<span class="hljs-property">message</span>); 496 } 497})(<span class="hljs-string">'/tmp/hello'</span>);</code></pre> 498</section><section><h3>Callback example<span><a class="mark" href="#fs_callback_example" id="fs_callback_example">#</a></span></h3> 499<p>The callback form takes a completion callback function as its last 500argument and invokes the operation asynchronously. The arguments passed to 501the completion callback depend on the method, but the first argument is always 502reserved for an exception. If the operation is completed successfully, then 503the first argument is <code>null</code> or <code>undefined</code>.</p> 504 505<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { unlink } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 506 507<span class="hljs-title function_">unlink</span>(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 508 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 509 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 510});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { unlink } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>); 511 512<span class="hljs-title function_">unlink</span>(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 513 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 514 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 515});</code></pre> 516<p>The callback-based versions of the <code>fs</code> module APIs are preferable over 517the use of the promise APIs when maximal performance (both in terms of 518execution time and memory allocation are required).</p> 519</section><section><h3>Synchronous example<span><a class="mark" href="#fs_synchronous_example" id="fs_synchronous_example">#</a></span></h3> 520<p>The synchronous APIs block the Node.js event loop and further JavaScript 521execution until the operation is complete. Exceptions are thrown immediately 522and can be handled using <code>try…catch</code>, or can be allowed to bubble up.</p> 523 524<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { unlinkSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 525 526<span class="hljs-keyword">try</span> { 527 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 528 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 529} <span class="hljs-keyword">catch</span> (err) { 530 <span class="hljs-comment">// handle the error</span> 531}</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { unlinkSync } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>); 532 533<span class="hljs-keyword">try</span> { 534 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 535 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 536} <span class="hljs-keyword">catch</span> (err) { 537 <span class="hljs-comment">// handle the error</span> 538}</code></pre> 539</section><section><h3>Promises API<span><a class="mark" href="#fs_promises_api" id="fs_promises_api">#</a></span></h3> 540<div class="api_metadata"> 541<details class="changelog"><summary>History</summary> 542<table> 543<tbody><tr><th>Version</th><th>Changes</th></tr> 544<tr><td>v14.0.0</td> 545<td><p>Exposed as <code>require('fs/promises')</code>.</p></td></tr> 546<tr><td>v11.14.0, v10.17.0</td> 547<td><p>This API is no longer experimental.</p></td></tr> 548<tr><td>v10.1.0</td> 549<td><p>The API is accessible via <code>require('fs').promises</code> only.</p></td></tr> 550<tr><td>v10.0.0</td> 551<td><p><span>Added in: v10.0.0</span></p></td></tr> 552</tbody></table> 553</details> 554</div> 555<p>The <code>fs/promises</code> API provides asynchronous file system methods that return 556promises.</p> 557<p>The promise APIs use the underlying Node.js threadpool to perform file 558system operations off the event loop thread. These operations are not 559synchronized or threadsafe. Care must be taken when performing multiple 560concurrent modifications on the same file or data corruption may occur.</p> 561<h4>Class: <code>FileHandle</code><span><a class="mark" href="#fs_class_filehandle" id="fs_class_filehandle">#</a></span></h4> 562<div class="api_metadata"> 563<span>Added in: v10.0.0</span> 564</div> 565<p>A <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object is an object wrapper for a numeric file descriptor.</p> 566<p>Instances of the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object are created by the <code>fsPromises.open()</code> 567method.</p> 568<p>All <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> objects are <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a>s.</p> 569<p>If a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> is not closed using the <code>filehandle.close()</code> method, it will 570try to automatically close the file descriptor and emit a process warning, 571helping to prevent memory leaks. Please do not rely on this behavior because 572it can be unreliable and the file may not be closed. Instead, always explicitly 573close <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>s. Node.js may change this behavior in the future.</p> 574<h5><code>filehandle.appendFile(data[, options])</code><span><a class="mark" href="#fs_filehandle_appendfile_data_options" id="fs_filehandle_appendfile_data_options">#</a></span></h5> 575<div class="api_metadata"> 576<span>Added in: v10.0.0</span> 577</div> 578<ul> 579<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> 580<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> 581<ul> 582<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> 583</ul> 584</li> 585<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 586</ul> 587<p>Alias of <a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 588<p>When operating on file handles, the mode cannot be changed from what it was set 589to with <a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open()</code></a>. Therefore, this is equivalent to 590<a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 591<h5><code>filehandle.chmod(mode)</code><span><a class="mark" href="#fs_filehandle_chmod_mode" id="fs_filehandle_chmod_mode">#</a></span></h5> 592<div class="api_metadata"> 593<span>Added in: v10.0.0</span> 594</div> 595<ul> 596<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> the file mode bit mask.</li> 597<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 598</ul> 599<p>Modifies the permissions on the file. See <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a>.</p> 600<h5><code>filehandle.chown(uid, gid)</code><span><a class="mark" href="#fs_filehandle_chown_uid_gid" id="fs_filehandle_chown_uid_gid">#</a></span></h5> 601<div class="api_metadata"> 602<span>Added in: v10.0.0</span> 603</div> 604<ul> 605<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new owner's user id.</li> 606<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new group's group id.</li> 607<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 608</ul> 609<p>Changes the ownership of the file. A wrapper for <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a>.</p> 610<h5><code>filehandle.close()</code><span><a class="mark" href="#fs_filehandle_close" id="fs_filehandle_close">#</a></span></h5> 611<div class="api_metadata"> 612<span>Added in: v10.0.0</span> 613</div> 614<ul> 615<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 616</ul> 617<p>Closes the file handle after waiting for any pending operation on the handle to 618complete.</p> 619<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 620 621<span class="hljs-keyword">let</span> filehandle; 622<span class="hljs-keyword">try</span> { 623 filehandle = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-string">'thefile.txt'</span>, <span class="hljs-string">'r'</span>); 624} <span class="hljs-keyword">finally</span> { 625 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 626}</code></pre> 627<h5><code>filehandle.datasync()</code><span><a class="mark" href="#fs_filehandle_datasync" id="fs_filehandle_datasync">#</a></span></h5> 628<div class="api_metadata"> 629<span>Added in: v10.0.0</span> 630</div> 631<ul> 632<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 633</ul> 634<p>Forces all currently queued I/O operations associated with the file to the 635operating system's synchronized I/O completion state. Refer to the POSIX 636<a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a> documentation for details.</p> 637<p>Unlike <code>filehandle.sync</code> this method does not flush modified metadata.</p> 638<h5><code>filehandle.fd</code><span><a class="mark" href="#fs_filehandle_fd" id="fs_filehandle_fd">#</a></span></h5> 639<div class="api_metadata"> 640<span>Added in: v10.0.0</span> 641</div> 642<ul> 643<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 <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object.</li> 644</ul> 645<h5><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></h5> 646<div class="api_metadata"> 647<span>Added in: v10.0.0</span> 648</div> 649<ul> 650<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> A buffer that will be filled with the 651file data read.</li> 652<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The location in the buffer at which to start filling. 653<strong>Default:</strong> <code>0</code></li> 654<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes to read. <strong>Default:</strong> 655<code>buffer.byteLength</code></li> 656<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The location where to begin reading data from the 657file. If <code>null</code>, data will be read from the current file position, and 658the position will be updated. If <code>position</code> is an integer, the current 659file position will remain unchanged.</li> 660<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills upon success with an object with two properties: 661<ul> 662<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes read</li> 663<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> A reference to the passed in <code>buffer</code> 664argument.</li> 665</ul> 666</li> 667</ul> 668<p>Reads data from the file and stores that in the given buffer.</p> 669<p>If the file is not modified concurrently, the end-of-file is reached when the 670number of bytes read is zero.</p> 671<h5><code>filehandle.read([options])</code><span><a class="mark" href="#fs_filehandle_read_options" id="fs_filehandle_read_options">#</a></span></h5> 672<div class="api_metadata"> 673<span>Added in: v13.11.0, v12.17.0</span> 674</div> 675<ul> 676<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 677<ul> 678<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> A buffer that will be filled with the 679file data read. <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li> 680<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The location in the buffer at which to start filling. 681<strong>Default:</strong> <code>0</code></li> 682<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes to read. <strong>Default:</strong> 683<code>buffer.byteLength</code></li> 684<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The location where to begin reading data from the 685file. If <code>null</code>, data will be read from the current file position, and 686the position will be updated. If <code>position</code> is an integer, the current 687file position will remain unchanged. <strong>Default:</strong>: <code>null</code></li> 688</ul> 689</li> 690<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills upon success with an object with two properties: 691<ul> 692<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes read</li> 693<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> A reference to the passed in <code>buffer</code> 694argument.</li> 695</ul> 696</li> 697</ul> 698<p>Reads data from the file and stores that in the given buffer.</p> 699<p>If the file is not modified concurrently, the end-of-file is reached when the 700number of bytes read is zero.</p> 701<h5><code>filehandle.readFile(options)</code><span><a class="mark" href="#fs_filehandle_readfile_options" id="fs_filehandle_readfile_options">#</a></span></h5> 702<div class="api_metadata"> 703<span>Added in: v10.0.0</span> 704</div> 705<ul> 706<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> 707<ul> 708<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> 709<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 710</ul> 711</li> 712<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills upon a successful read with the contents of the 713file. If no encoding is specified (using <code>options.encoding</code>), the data is 714returned as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</li> 715</ul> 716<p>Asynchronously reads the entire contents of a file.</p> 717<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 718<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 719<p>If one or more <code>filehandle.read()</code> calls are made on a file handle and then a 720<code>filehandle.readFile()</code> call is made, the data will be read from the current 721position till the end of the file. It doesn't always read from the beginning 722of the file.</p> 723<h5><code>filehandle.readv(buffers[, position])</code><span><a class="mark" href="#fs_filehandle_readv_buffers_position" id="fs_filehandle_readv_buffers_position">#</a></span></h5> 724<div class="api_metadata"> 725<span>Added in: v13.13.0, v12.17.0</span> 726</div> 727<ul> 728<li><code>buffers</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> 729<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The offset from the beginning of the file where the data 730should be read from. If <code>position</code> is not a <code>number</code>, the data will be read 731from the current position.</li> 732<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills upon success an object containing two properties: 733<ul> 734<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> the number of bytes read</li> 735<li><code>buffers</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> property containing 736a reference to the <code>buffers</code> input.</li> 737</ul> 738</li> 739</ul> 740<p>Read from a file and write to an array of <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView></a>s</p> 741<h5><code>filehandle.stat([options])</code><span><a class="mark" href="#fs_filehandle_stat_options" id="fs_filehandle_stat_options">#</a></span></h5> 742<div class="api_metadata"> 743<details class="changelog"><summary>History</summary> 744<table> 745<tbody><tr><th>Version</th><th>Changes</th></tr> 746<tr><td>v10.5.0</td> 747<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 748<tr><td>v10.0.0</td> 749<td><p><span>Added in: v10.0.0</span></p></td></tr> 750</tbody></table> 751</details> 752</div> 753<ul> 754<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 755<ul> 756<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 757<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 758</ul> 759</li> 760<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with an <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file.</li> 761</ul> 762<h5><code>filehandle.sync()</code><span><a class="mark" href="#fs_filehandle_sync" id="fs_filehandle_sync">#</a></span></h5> 763<div class="api_metadata"> 764<span>Added in: v10.0.0</span> 765</div> 766<ul> 767<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fufills with <code>undefined</code> upon success.</li> 768</ul> 769<p>Request that all data for the open file descriptor is flushed to the storage 770device. The specific implementation is operating system and device specific. 771Refer to the POSIX <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a> documentation for more detail.</p> 772<h5><code>filehandle.truncate(len)</code><span><a class="mark" href="#fs_filehandle_truncate_len" id="fs_filehandle_truncate_len">#</a></span></h5> 773<div class="api_metadata"> 774<span>Added in: v10.0.0</span> 775</div> 776<ul> 777<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> 778<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 779</ul> 780<p>Truncates the file.</p> 781<p>If the file was larger than <code>len</code> bytes, only the first <code>len</code> bytes will be 782retained in the file.</p> 783<p>The following example retains only the first four bytes of the file:</p> 784<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 785 786<span class="hljs-keyword">let</span> filehandle = <span class="hljs-literal">null</span>; 787<span class="hljs-keyword">try</span> { 788 filehandle = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>); 789 <span class="hljs-keyword">await</span> filehandle.<span class="hljs-title function_">truncate</span>(<span class="hljs-number">4</span>); 790} <span class="hljs-keyword">finally</span> { 791 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 792}</code></pre> 793<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the 794extended part is filled with null bytes (<code>'\0'</code>):</p> 795<p>If <code>len</code> is negative then <code>0</code> will be used.</p> 796<h5><code>filehandle.utimes(atime, mtime)</code><span><a class="mark" href="#fs_filehandle_utimes_atime_mtime" id="fs_filehandle_utimes_atime_mtime">#</a></span></h5> 797<div class="api_metadata"> 798<span>Added in: v10.0.0</span> 799</div> 800<ul> 801<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> 802<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> 803<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 804</ul> 805<p>Change the file system timestamps of the object referenced by the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> 806then resolves the promise with no arguments upon success.</p> 807<p>This function does not work on AIX versions before 7.1, it will reject the 808promise with an error using code <code>UV_ENOSYS</code>.</p> 809<h5><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></h5> 810<div class="api_metadata"> 811<details class="changelog"><summary>History</summary> 812<table> 813<tbody><tr><th>Version</th><th>Changes</th></tr> 814<tr><td>v14.12.0</td> 815<td><p>The <code>buffer</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 816<tr><td>v14.0.0</td> 817<td><p>The <code>buffer</code> parameter won't coerce unsupported input to buffers anymore.</p></td></tr> 818<tr><td>v10.0.0</td> 819<td><p><span>Added in: v10.0.0</span></p></td></tr> 820</tbody></table> 821</details> 822</div> 823<ul> 824<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> | <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></li> 825<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The start position from within <code>buffer</code> where the data 826to write begins. <strong>Default:</strong> <code>0</code></li> 827<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes from <code>buffer</code> to write. <strong>Default:</strong> 828<code>buffer.byteLength</code></li> 829<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The offset from the beginning of the file where the 830data from <code>buffer</code> should be written. If <code>position</code> is not a <code>number</code>, 831the data will be written at the current position. See the POSIX <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a> 832documentation for more detail.</li> 833<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 834</ul> 835<p>Write <code>buffer</code> to the file.</p> 836<p>If <code>buffer</code> is a plain object, it must have an own (not inherited) <code>toString</code> 837function property.</p> 838<p>The promise is resolved with an object containing two properties:</p> 839<ul> 840<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> the number of bytes written</li> 841<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> | <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> a reference to the 842<code>buffer</code> written.</li> 843</ul> 844<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 845without waiting for the promise to be resolved (or rejected). For this 846scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 847<p>On Linux, positional writes do not work when the file is opened in append mode. 848The kernel ignores the position argument and always appends the data to 849the end of the file.</p> 850<h5><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></h5> 851<div class="api_metadata"> 852<details class="changelog"><summary>History</summary> 853<table> 854<tbody><tr><th>Version</th><th>Changes</th></tr> 855<tr><td>v14.12.0</td> 856<td><p>The <code>string</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 857<tr><td>v14.0.0</td> 858<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 859<tr><td>v10.0.0</td> 860<td><p><span>Added in: v10.0.0</span></p></td></tr> 861</tbody></table> 862</details> 863</div> 864<ul> 865<li><code>string</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></li> 866<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The offset from the beginning of the file where the 867data from <code>string</code> should be written. If <code>position</code> is not a <code>number</code> the 868data will be written at the current position. See the POSIX <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a> 869documentation for more detail.</li> 870<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The expected string encoding. <strong>Default:</strong> <code>'utf8'</code></li> 871<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 872</ul> 873<p>Write <code>string</code> to the file. If <code>string</code> is not a string, or an object with an 874own <code>toString</code> function property, the promise is rejected with an error.</p> 875<p>The promise is resolved with an object containing two properties:</p> 876<ul> 877<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> the number of bytes written</li> 878<li><code>buffer</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> a reference to the <code>string</code> written.</li> 879</ul> 880<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 881without waiting for the promise to be resolved (or rejected). For this 882scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 883<p>On Linux, positional writes do not work when the file is opened in append mode. 884The kernel ignores the position argument and always appends the data to 885the end of the file.</p> 886<h5><code>filehandle.writeFile(data, options)</code><span><a class="mark" href="#fs_filehandle_writefile_data_options" id="fs_filehandle_writefile_data_options">#</a></span></h5> 887<div class="api_metadata"> 888<details class="changelog"><summary>History</summary> 889<table> 890<tbody><tr><th>Version</th><th>Changes</th></tr> 891<tr><td>v14.18.0</td> 892<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 893<tr><td>v14.12.0</td> 894<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 895<tr><td>v14.0.0</td> 896<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 897<tr><td>v10.0.0</td> 898<td><p><span>Added in: v10.0.0</span></p></td></tr> 899</tbody></table> 900</details> 901</div> 902<ul> 903<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> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="stream.html#stream_stream" class="type"><Stream></a></li> 904<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> 905<ul> 906<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> The expected character encoding when <code>data</code> is a 907string. <strong>Default:</strong> <code>'utf8'</code></li> 908</ul> 909</li> 910<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 911</ul> 912<p>Asynchronously writes data to a file, replacing the file if it already exists. 913<code>data</code> can be a string, a buffer, an <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> or <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> object, or an 914object with an own <code>toString</code> function 915property. The promise is resolved with no arguments upon success.</p> 916<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 917<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support writing.</p> 918<p>It is unsafe to use <code>filehandle.writeFile()</code> multiple times on the same file 919without waiting for the promise to be resolved (or rejected).</p> 920<p>If one or more <code>filehandle.write()</code> calls are made on a file handle and then a 921<code>filehandle.writeFile()</code> call is made, the data will be written from the 922current position till the end of the file. It doesn't always write from the 923beginning of the file.</p> 924<h5><code>filehandle.writev(buffers[, position])</code><span><a class="mark" href="#fs_filehandle_writev_buffers_position" id="fs_filehandle_writev_buffers_position">#</a></span></h5> 925<div class="api_metadata"> 926<span>Added in: v12.9.0</span> 927</div> 928<ul> 929<li><code>buffers</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> 930<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The offset from the beginning of the file where the 931data from <code>buffers</code> should be written. If <code>position</code> is not a <code>number</code>, 932the data will be written at the current position.</li> 933<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 934</ul> 935<p>Write an array of <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView></a>s to the file.</p> 936<p>The promise is resolved with an object containing a two properties:</p> 937<ul> 938<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> the number of bytes written</li> 939<li><code>buffers</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> a reference to the <code>buffers</code> 940input.</li> 941</ul> 942<p>It is unsafe to call <code>writev()</code> multiple times on the same file without waiting 943for the promise to be resolved (or rejected).</p> 944<p>On Linux, positional writes don't work when the file is opened in append mode. 945The kernel ignores the position argument and always appends the data to 946the end of the file.</p> 947<h4><code>fsPromises.access(path[, mode])</code><span><a class="mark" href="#fs_fspromises_access_path_mode" id="fs_fspromises_access_path_mode">#</a></span></h4> 948<div class="api_metadata"> 949<span>Added in: v10.0.0</span> 950</div> 951<ul> 952<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> 953<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> 954<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 955</ul> 956<p>Tests a user's permissions for the file or directory specified by <code>path</code>. 957The <code>mode</code> argument is an optional integer that specifies the accessibility 958checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values 959of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of 960two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 961<p>If the accessibility check is successful, the promise is resolved with no 962value. If any of the accessibility checks fail, the promise is rejected 963with an <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> object. The following example checks if the file 964<code>/etc/passwd</code> can be read and written by the current process.</p> 965<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { access } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 966<span class="hljs-keyword">import</span> { constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 967 968<span class="hljs-keyword">try</span> { 969 <span class="hljs-keyword">await</span> <span class="hljs-title function_">access</span>(<span class="hljs-string">'/etc/passwd'</span>, constants.<span class="hljs-property">R_OK</span> | constants.<span class="hljs-property">W_OK</span>); 970 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can access'</span>); 971} <span class="hljs-keyword">catch</span> { 972 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'cannot access'</span>); 973}</code></pre> 974<p>Using <code>fsPromises.access()</code> to check for the accessibility of a file before 975calling <code>fsPromises.open()</code> is not recommended. Doing so introduces a race 976condition, since other processes may change the file's state between the two 977calls. Instead, user code should open/read/write the file directly and handle 978the error raised if the file is not accessible.</p> 979<h4><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></h4> 980<div class="api_metadata"> 981<span>Added in: v10.0.0</span> 982</div> 983<ul> 984<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 <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a></li> 985<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> 986<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> 987<ul> 988<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> 989<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> 990<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> 991</ul> 992</li> 993<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 994</ul> 995<p>Asynchronously append data to a file, creating the file if it does not yet 996exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 997<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 998<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 999for more details.</p> 1000<p>The <code>path</code> may be specified as a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> that has been opened 1001for appending (using <code>fsPromises.open()</code>).</p> 1002<h4><code>fsPromises.chmod(path, mode)</code><span><a class="mark" href="#fs_fspromises_chmod_path_mode" id="fs_fspromises_chmod_path_mode">#</a></span></h4> 1003<div class="api_metadata"> 1004<span>Added in: v10.0.0</span> 1005</div> 1006<ul> 1007<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> 1008<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> 1009<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1010</ul> 1011<p>Changes the permissions of a file.</p> 1012<h4><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></h4> 1013<div class="api_metadata"> 1014<span>Added in: v10.0.0</span> 1015</div> 1016<ul> 1017<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> 1018<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1019<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1020<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1021</ul> 1022<p>Changes the ownership of a file.</p> 1023<h4><code>fsPromises.copyFile(src, dest[, mode])</code><span><a class="mark" href="#fs_fspromises_copyfile_src_dest_mode" id="fs_fspromises_copyfile_src_dest_mode">#</a></span></h4> 1024<div class="api_metadata"> 1025<details class="changelog"><summary>History</summary> 1026<table> 1027<tbody><tr><th>Version</th><th>Changes</th></tr> 1028<tr><td>v14.0.0</td> 1029<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 1030<tr><td>v10.0.0</td> 1031<td><p><span>Added in: v10.0.0</span></p></td></tr> 1032</tbody></table> 1033</details> 1034</div> 1035<ul> 1036<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> 1037<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> 1038<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> Optional modifiers that specify the behavior of the copy 1039operation. It is possible to create a mask consisting of the bitwise OR of 1040two or more values (e.g. 1041<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>) 1042<strong>Default:</strong> <code>0</code>. 1043<ul> 1044<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> 1045already exists.</li> 1046<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create 1047a copy-on-write reflink. If the platform does not support copy-on-write, 1048then a fallback copy mechanism is used.</li> 1049<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 1050create a copy-on-write reflink. If the platform does not support 1051copy-on-write, then the operation will fail.</li> 1052</ul> 1053</li> 1054<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1055</ul> 1056<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 1057already exists.</p> 1058<p>No guarantees are made about the atomicity of the copy operation. If an 1059error occurs after the destination file has been opened for writing, an attempt 1060will be made to remove the destination.</p> 1061<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1062<span class="hljs-keyword">import</span> { copyFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1063 1064<span class="hljs-keyword">try</span> { 1065 <span class="hljs-keyword">await</span> <span class="hljs-title function_">copyFile</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>); 1066 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'source.txt was copied to destination.txt'</span>); 1067} <span class="hljs-keyword">catch</span> { 1068 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The file could not be copied'</span>); 1069} 1070 1071<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 1072<span class="hljs-keyword">try</span> { 1073 <span class="hljs-keyword">await</span> <span class="hljs-title function_">copyFile</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, constants.<span class="hljs-property">COPYFILE_EXCL</span>); 1074 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'source.txt was copied to destination.txt'</span>); 1075} <span class="hljs-keyword">catch</span> { 1076 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The file could not be copied'</span>); 1077}</code></pre> 1078<h4><code>fsPromises.lchmod(path, mode)</code><span><a class="mark" href="#fs_fspromises_lchmod_path_mode" id="fs_fspromises_lchmod_path_mode">#</a></span></h4> 1079<div class="api_metadata"> 1080<span>Deprecated since: v10.0.0</span> 1081</div> 1082<ul> 1083<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> 1084<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1085<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1086</ul> 1087<p>Changes the permissions on a symbolic link.</p> 1088<p>This method is only implemented on macOS.</p> 1089<h4><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></h4> 1090<div class="api_metadata"> 1091<details class="changelog"><summary>History</summary> 1092<table> 1093<tbody><tr><th>Version</th><th>Changes</th></tr> 1094<tr><td>v10.6.0</td> 1095<td><p>This API is no longer deprecated.</p></td></tr> 1096<tr><td>v10.0.0</td> 1097<td><p><span>Added in: v10.0.0</span></p></td></tr> 1098</tbody></table> 1099</details> 1100</div> 1101<ul> 1102<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> 1103<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1104<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1105<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1106</ul> 1107<p>Changes the ownership on a symbolic link.</p> 1108<h4><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></h4> 1109<div class="api_metadata"> 1110<span>Added in: v14.5.0, v12.19.0</span> 1111</div> 1112<ul> 1113<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> 1114<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> 1115<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> 1116<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1117</ul> 1118<p>Changes the access and modification times of a file in the same way as 1119<a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes()</code></a>, with the difference that if the path refers to a 1120symbolic link, then the link is not dereferenced: instead, the timestamps of 1121the symbolic link itself are changed.</p> 1122<h4><code>fsPromises.link(existingPath, newPath)</code><span><a class="mark" href="#fs_fspromises_link_existingpath_newpath" id="fs_fspromises_link_existingpath_newpath">#</a></span></h4> 1123<div class="api_metadata"> 1124<span>Added in: v10.0.0</span> 1125</div> 1126<ul> 1127<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> 1128<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> 1129<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1130</ul> 1131<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 1132<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a> documentation for more detail.</p> 1133<h4><code>fsPromises.lstat(path[, options])</code><span><a class="mark" href="#fs_fspromises_lstat_path_options" id="fs_fspromises_lstat_path_options">#</a></span></h4> 1134<div class="api_metadata"> 1135<details class="changelog"><summary>History</summary> 1136<table> 1137<tbody><tr><th>Version</th><th>Changes</th></tr> 1138<tr><td>v10.5.0</td> 1139<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1140<tr><td>v10.0.0</td> 1141<td><p><span>Added in: v10.0.0</span></p></td></tr> 1142</tbody></table> 1143</details> 1144</div> 1145<ul> 1146<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> 1147<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1148<ul> 1149<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 1150<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 1151</ul> 1152</li> 1153<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object for the given 1154symbolic link <code>path</code>.</li> 1155</ul> 1156<p>Equivalent to <a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat()</code></a> unless <code>path</code> refers to a symbolic link, 1157in which case the link itself is stat-ed, not the file that it refers to. 1158Refer to the POSIX <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a> document for more detail.</p> 1159<h4><code>fsPromises.mkdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_mkdir_path_options" id="fs_fspromises_mkdir_path_options">#</a></span></h4> 1160<div class="api_metadata"> 1161<span>Added in: v10.0.0</span> 1162</div> 1163<ul> 1164<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> 1165<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> 1166<ul> 1167<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> 1168<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> 1169</ul> 1170</li> 1171<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Upon success, fulfills with <code>undefined</code> if <code>recursive</code> 1172is <code>false</code>, or the first directory path created if <code>recursive</code> is <code>true</code>.</li> 1173</ul> 1174<p>Asynchronously creates a directory.</p> 1175<p>The optional <code>options</code> argument can be an integer specifying <code>mode</code> (permission 1176and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code> 1177property indicating whether parent directories should be created. Calling 1178<code>fsPromises.mkdir()</code> when <code>path</code> is a directory that exists results in a 1179rejection only when <code>recursive</code> is false.</p> 1180<h4><code>fsPromises.mkdtemp(prefix[, options])</code><span><a class="mark" href="#fs_fspromises_mkdtemp_prefix_options" id="fs_fspromises_mkdtemp_prefix_options">#</a></span></h4> 1181<div class="api_metadata"> 1182<details class="changelog"><summary>History</summary> 1183<table> 1184<tbody><tr><th>Version</th><th>Changes</th></tr> 1185<tr><td>v14.18.0</td> 1186<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 1187<tr><td>v10.0.0</td> 1188<td><p><span>Added in: v10.0.0</span></p></td></tr> 1189</tbody></table> 1190</details> 1191</div> 1192<ul> 1193<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 1194<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> 1195<ul> 1196<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> 1197</ul> 1198</li> 1199<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with a string containing the filesystem path 1200of the newly created temporary directory.</li> 1201</ul> 1202<p>Creates a unique temporary directory. A unique directory name is generated by 1203appending six random characters to the end of the provided <code>prefix</code>. Due to 1204platform inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some 1205platforms, notably the BSDs, can return more than six random characters, and 1206replace trailing <code>X</code> characters in <code>prefix</code> with random characters.</p> 1207<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1208object with an <code>encoding</code> property specifying the character encoding to use.</p> 1209<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { mkdtemp } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1210 1211<span class="hljs-keyword">try</span> { 1212 <span class="hljs-keyword">await</span> <span class="hljs-title function_">mkdtemp</span>(path.<span class="hljs-title function_">join</span>(os.<span class="hljs-title function_">tmpdir</span>(), <span class="hljs-string">'foo-'</span>)); 1213} <span class="hljs-keyword">catch</span> (err) { 1214 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1215}</code></pre> 1216<p>The <code>fsPromises.mkdtemp()</code> method will append the six randomly selected 1217characters directly to the <code>prefix</code> string. For instance, given a directory 1218<code>/tmp</code>, if the intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the 1219<code>prefix</code> must end with a trailing platform-specific path separator 1220(<code>require('path').sep</code>).</p> 1221<h4><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></h4> 1222<div class="api_metadata"> 1223<details class="changelog"><summary>History</summary> 1224<table> 1225<tbody><tr><th>Version</th><th>Changes</th></tr> 1226<tr><td>v11.1.0</td> 1227<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 1228<tr><td>v10.0.0</td> 1229<td><p><span>Added in: v10.0.0</span></p></td></tr> 1230</tbody></table> 1231</details> 1232</div> 1233<ul> 1234<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> 1235<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>. 1236<strong>Default:</strong> <code>'r'</code>.</li> 1237<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> Sets the file mode (permission and sticky bits) 1238if the file is created. <strong>Default:</strong> <code>0o666</code> (readable and writable)</li> 1239<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object.</li> 1240</ul> 1241<p>Opens a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>.</p> 1242<p>Refer to the POSIX <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a> documentation for more detail.</p> 1243<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented 1244by <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 1245a colon, Node.js will open a file system stream, as described by 1246<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p> 1247<h4><code>fsPromises.opendir(path[, options])</code><span><a class="mark" href="#fs_fspromises_opendir_path_options" id="fs_fspromises_opendir_path_options">#</a></span></h4> 1248<div class="api_metadata"> 1249<details class="changelog"><summary>History</summary> 1250<table> 1251<tbody><tr><th>Version</th><th>Changes</th></tr> 1252<tr><td>v13.1.0, v12.16.0</td> 1253<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 1254<tr><td>v12.12.0</td> 1255<td><p><span>Added in: v12.12.0</span></p></td></tr> 1256</tbody></table> 1257</details> 1258</div> 1259<ul> 1260<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> 1261<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1262<ul> 1263<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> 1264<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 1265internally when reading from the directory. Higher values lead to better 1266performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 1267</ul> 1268</li> 1269<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>.</li> 1270</ul> 1271<p>Asynchronously open a directory for iterative scanning. See the POSIX 1272<a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a> documentation for more detail.</p> 1273<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 1274and cleaning up the directory.</p> 1275<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 1276directory and subsequent read operations.</p> 1277<p>Example using async iteration:</p> 1278<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { opendir } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1279 1280<span class="hljs-keyword">try</span> { 1281 <span class="hljs-keyword">const</span> dir = <span class="hljs-keyword">await</span> <span class="hljs-title function_">opendir</span>(<span class="hljs-string">'./'</span>); 1282 <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) 1283 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 1284} <span class="hljs-keyword">catch</span> (err) { 1285 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1286}</code></pre> 1287<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 1288closed after the iterator exits.</p> 1289<h4><code>fsPromises.readdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_readdir_path_options" id="fs_fspromises_readdir_path_options">#</a></span></h4> 1290<div class="api_metadata"> 1291<details class="changelog"><summary>History</summary> 1292<table> 1293<tbody><tr><th>Version</th><th>Changes</th></tr> 1294<tr><td>v10.11.0</td> 1295<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 1296<tr><td>v10.0.0</td> 1297<td><p><span>Added in: v10.0.0</span></p></td></tr> 1298</tbody></table> 1299</details> 1300</div> 1301<ul> 1302<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> 1303<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> 1304<ul> 1305<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> 1306<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> 1307</ul> 1308</li> 1309<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with an array of the names of the files in 1310the directory excluding <code>'.'</code> and <code>'..'</code>.</li> 1311</ul> 1312<p>Reads the contents of a directory.</p> 1313<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1314object with an <code>encoding</code> property specifying the character encoding to use for 1315the filenames. If the <code>encoding</code> is set to <code>'buffer'</code>, the filenames returned 1316will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 1317<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the resolved array will contain 1318<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 1319<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readdir } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1320 1321<span class="hljs-keyword">try</span> { 1322 <span class="hljs-keyword">const</span> files = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readdir</span>(path); 1323 <span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> file <span class="hljs-keyword">of</span> files) 1324 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(file); 1325} <span class="hljs-keyword">catch</span> (err) { 1326 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1327}</code></pre> 1328<h4><code>fsPromises.readFile(path[, options])</code><span><a class="mark" href="#fs_fspromises_readfile_path_options" id="fs_fspromises_readfile_path_options">#</a></span></h4> 1329<div class="api_metadata"> 1330<details class="changelog"><summary>History</summary> 1331<table> 1332<tbody><tr><th>Version</th><th>Changes</th></tr> 1333<tr><td>v14.17.0</td> 1334<td><p>The options argument may include an AbortSignal to abort an ongoing readFile request.</p></td></tr> 1335<tr><td>v10.0.0</td> 1336<td><p><span>Added in: v10.0.0</span></p></td></tr> 1337</tbody></table> 1338</details> 1339</div> 1340<ul> 1341<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> 1342<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> 1343<ul> 1344<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> 1345<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> 1346<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 1347</ul> 1348</li> 1349<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with the contents of the file.</li> 1350</ul> 1351<p>Asynchronously reads the entire contents of a file.</p> 1352<p>If no encoding is specified (using <code>options.encoding</code>), the data is returned 1353as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</p> 1354<p>If <code>options</code> is a string, then it specifies the encoding.</p> 1355<p>When the <code>path</code> is a directory, the behavior of <code>fsPromises.readFile()</code> is 1356platform-specific. On macOS, Linux, and Windows, the promise will be rejected 1357with an error. On FreeBSD, a representation of the directory's contents will be 1358returned.</p> 1359<p>It is possible to abort an ongoing <code>readFile</code> using an <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a>. If a 1360request is aborted the promise returned is rejected with an <code>AbortError</code>:</p> 1361<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1362 1363<span class="hljs-keyword">try</span> { 1364 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1365 <span class="hljs-keyword">const</span> { signal } = controller; 1366 <span class="hljs-keyword">const</span> promise = <span class="hljs-title function_">readFile</span>(fileName, { signal }); 1367 1368 <span class="hljs-comment">// Abort the request before the promise settles.</span> 1369 controller.<span class="hljs-title function_">abort</span>(); 1370 1371 <span class="hljs-keyword">await</span> promise; 1372} <span class="hljs-keyword">catch</span> (err) { 1373 <span class="hljs-comment">// When a request is aborted - err is an AbortError</span> 1374 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1375}</code></pre> 1376<p>Aborting an ongoing request does not abort individual operating 1377system requests but rather the internal buffering <code>fs.readFile</code> performs.</p> 1378<p>Any specified <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 1379<h4><code>fsPromises.readlink(path[, options])</code><span><a class="mark" href="#fs_fspromises_readlink_path_options" id="fs_fspromises_readlink_path_options">#</a></span></h4> 1380<div class="api_metadata"> 1381<span>Added in: v10.0.0</span> 1382</div> 1383<ul> 1384<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> 1385<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> 1386<ul> 1387<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> 1388</ul> 1389</li> 1390<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with the <code>linkString</code> upon success.</li> 1391</ul> 1392<p>Reads the contents of the symbolic link referred to by <code>path</code>. See the POSIX 1393<a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a> documentation for more detail. The promise is resolved with the 1394<code>linkString</code> upon success.</p> 1395<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1396object with an <code>encoding</code> property specifying the character encoding to use for 1397the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, the link path 1398returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1399<h4><code>fsPromises.realpath(path[, options])</code><span><a class="mark" href="#fs_fspromises_realpath_path_options" id="fs_fspromises_realpath_path_options">#</a></span></h4> 1400<div class="api_metadata"> 1401<span>Added in: v10.0.0</span> 1402</div> 1403<ul> 1404<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> 1405<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> 1406<ul> 1407<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> 1408</ul> 1409</li> 1410<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with the resolved path upon success.</li> 1411</ul> 1412<p>Determines the actual location of <code>path</code> using the same semantics as the 1413<code>fs.realpath.native()</code> function.</p> 1414<p>Only paths that can be converted to UTF8 strings are supported.</p> 1415<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1416object with an <code>encoding</code> property specifying the character encoding to use for 1417the path. If the <code>encoding</code> is set to <code>'buffer'</code>, the path returned will be 1418passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1419<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 1420be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 1421this restriction.</p> 1422<h4><code>fsPromises.rename(oldPath, newPath)</code><span><a class="mark" href="#fs_fspromises_rename_oldpath_newpath" id="fs_fspromises_rename_oldpath_newpath">#</a></span></h4> 1423<div class="api_metadata"> 1424<span>Added in: v10.0.0</span> 1425</div> 1426<ul> 1427<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> 1428<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> 1429<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1430</ul> 1431<p>Renames <code>oldPath</code> to <code>newPath</code>.</p> 1432<h4><code>fsPromises.rmdir(path[, options])</code><span><a class="mark" href="#fs_fspromises_rmdir_path_options" id="fs_fspromises_rmdir_path_options">#</a></span></h4> 1433<div class="api_metadata"> 1434<details class="changelog"><summary>History</summary> 1435<table> 1436<tbody><tr><th>Version</th><th>Changes</th></tr> 1437<tr><td>v14.14.0</td> 1438<td><p>The <code>recursive</code> option is deprecated, use <code>fsPromises.rm</code> instead.</p></td></tr> 1439<tr><td>v13.3.0, v12.16.0</td> 1440<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> 1441<tr><td>v12.10.0</td> 1442<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 1443<tr><td>v10.0.0</td> 1444<td><p><span>Added in: v10.0.0</span></p></td></tr> 1445</tbody></table> 1446</details> 1447</div> 1448<ul> 1449<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> 1450<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1451<ul> 1452<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 1453<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 1454backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1455represents the number of retries. This option is ignored if the <code>recursive</code> 1456option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1457<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 1458recursive mode, errors are not reported if <code>path</code> does not exist, and 1459operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1460<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 1461retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1462<strong>Default:</strong> <code>100</code>.</li> 1463</ul> 1464</li> 1465<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1466</ul> 1467<p>Removes the directory identified by <code>path</code>.</p> 1468<p>Using <code>fsPromises.rmdir()</code> on a file (not a directory) results in the 1469promise being rejected with an <code>ENOENT</code> error on Windows and an <code>ENOTDIR</code> 1470error on POSIX.</p> 1471<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 1472<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 1473that represent files will be deleted. The permissive behavior of the 1474<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 1475the future.</p> 1476<h4><code>fsPromises.rm(path[, options])</code><span><a class="mark" href="#fs_fspromises_rm_path_options" id="fs_fspromises_rm_path_options">#</a></span></h4> 1477<div class="api_metadata"> 1478<span>Added in: v14.14.0</span> 1479</div> 1480<ul> 1481<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> 1482<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1483<ul> 1484<li><code>force</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When <code>true</code>, exceptions will be ignored if <code>path</code> does 1485not exist. <strong>Default:</strong> <code>false</code>.</li> 1486<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 1487<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 1488backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1489represents the number of retries. This option is ignored if the <code>recursive</code> 1490option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1491<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 1492recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1493<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 1494retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1495<strong>Default:</strong> <code>100</code>.</li> 1496</ul> 1497</li> 1498<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1499</ul> 1500<p>Removes files and directories (modeled on the standard POSIX <code>rm</code> utility).</p> 1501<h4><code>fsPromises.stat(path[, options])</code><span><a class="mark" href="#fs_fspromises_stat_path_options" id="fs_fspromises_stat_path_options">#</a></span></h4> 1502<div class="api_metadata"> 1503<details class="changelog"><summary>History</summary> 1504<table> 1505<tbody><tr><th>Version</th><th>Changes</th></tr> 1506<tr><td>v10.5.0</td> 1507<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1508<tr><td>v10.0.0</td> 1509<td><p><span>Added in: v10.0.0</span></p></td></tr> 1510</tbody></table> 1511</details> 1512</div> 1513<ul> 1514<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> 1515<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1516<ul> 1517<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 1518<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 1519</ul> 1520</li> 1521<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object for the 1522given <code>path</code>.</li> 1523</ul> 1524<h4><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></h4> 1525<div class="api_metadata"> 1526<span>Added in: v10.0.0</span> 1527</div> 1528<ul> 1529<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> 1530<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> 1531<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> 1532<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1533</ul> 1534<p>Creates a symbolic link.</p> 1535<p>The <code>type</code> argument is only used on Windows platforms and can be one of <code>'dir'</code>, 1536<code>'file'</code>, or <code>'junction'</code>. Windows junction points require the destination path 1537to be absolute. When using <code>'junction'</code>, the <code>target</code> argument will 1538automatically be normalized to absolute path.</p> 1539<h4><code>fsPromises.truncate(path[, len])</code><span><a class="mark" href="#fs_fspromises_truncate_path_len" id="fs_fspromises_truncate_path_len">#</a></span></h4> 1540<div class="api_metadata"> 1541<span>Added in: v10.0.0</span> 1542</div> 1543<ul> 1544<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> 1545<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> 1546<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1547</ul> 1548<p>Truncates (shortens or extends the length) of the content at <code>path</code> to <code>len</code> 1549bytes.</p> 1550<h4><code>fsPromises.unlink(path)</code><span><a class="mark" href="#fs_fspromises_unlink_path" id="fs_fspromises_unlink_path">#</a></span></h4> 1551<div class="api_metadata"> 1552<span>Added in: v10.0.0</span> 1553</div> 1554<ul> 1555<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> 1556<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1557</ul> 1558<p>If <code>path</code> refers to a symbolic link, then the link is removed without affecting 1559the file or directory to which that link refers. If the <code>path</code> refers to a file 1560path that is not a symbolic link, the file is deleted. See the POSIX <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a> 1561documentation for more detail.</p> 1562<h4><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></h4> 1563<div class="api_metadata"> 1564<span>Added in: v10.0.0</span> 1565</div> 1566<ul> 1567<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> 1568<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> 1569<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> 1570<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1571</ul> 1572<p>Change the file system timestamps of the object referenced by <code>path</code>.</p> 1573<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p> 1574<ul> 1575<li>Values can be either numbers representing Unix epoch time, <code>Date</code>s, or a 1576numeric string like <code>'123456789.0'</code>.</li> 1577<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or 1578<code>-Infinity</code>, an <code>Error</code> will be thrown.</li> 1579</ul> 1580<h4><code>fsPromises.watch(filename[, options])</code><span><a class="mark" href="#fs_fspromises_watch_filename_options" id="fs_fspromises_watch_filename_options">#</a></span></h4> 1581<div class="api_metadata"> 1582<span>Added in: v14.18.0</span> 1583</div> 1584<ul> 1585<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> 1586<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> 1587<ul> 1588<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 1589as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li> 1590<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 1591watched, or only the current directory. This applies when a directory is 1592specified, and only on supported platforms (See <a href="#fs_caveats">caveats</a>). <strong>Default:</strong> 1593<code>false</code>.</li> 1594<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 1595filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li> 1596<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> An <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> used to signal when the watcher 1597should stop.</li> 1598</ul> 1599</li> 1600<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> of objects with the properties: 1601<ul> 1602<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</li> 1603<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 name of the file changed.</li> 1604</ul> 1605</li> 1606</ul> 1607<p>Returns an async iterator that watches for changes on <code>filename</code>, where <code>filename</code> 1608is either a file or a directory.</p> 1609<pre><code class="language-js"><span class="hljs-keyword">const</span> { watch } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs/promises'</span>); 1610 1611<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1612<span class="hljs-keyword">const</span> { signal } = ac; 1613<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> ac.<span class="hljs-title function_">abort</span>(), <span class="hljs-number">10000</span>); 1614 1615(<span class="hljs-keyword">async</span> () => { 1616 <span class="hljs-keyword">try</span> { 1617 <span class="hljs-keyword">const</span> watcher = <span class="hljs-title function_">watch</span>(__filename, { signal }); 1618 <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> event <span class="hljs-keyword">of</span> watcher) 1619 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event); 1620 } <span class="hljs-keyword">catch</span> (err) { 1621 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">name</span> === <span class="hljs-string">'AbortError'</span>) 1622 <span class="hljs-keyword">return</span>; 1623 <span class="hljs-keyword">throw</span> err; 1624 } 1625})();</code></pre> 1626<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or 1627disappears in the directory.</p> 1628<p>All the <a href="#fs_caveats">caveats</a> for <code>fs.watch()</code> also apply to <code>fsPromises.watch()</code>.</p> 1629<h4><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></h4> 1630<div class="api_metadata"> 1631<details class="changelog"><summary>History</summary> 1632<table> 1633<tbody><tr><th>Version</th><th>Changes</th></tr> 1634<tr><td>v14.18.0</td> 1635<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 1636<tr><td>v14.17.0</td> 1637<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 1638<tr><td>v14.12.0</td> 1639<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 1640<tr><td>v14.0.0</td> 1641<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 1642<tr><td>v10.0.0</td> 1643<td><p><span>Added in: v10.0.0</span></p></td></tr> 1644</tbody></table> 1645</details> 1646</div> 1647<ul> 1648<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> 1649<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> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="stream.html#stream_stream" class="type"><Stream></a></li> 1650<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> 1651<ul> 1652<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> 1653<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> 1654<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> 1655<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 1656</ul> 1657</li> 1658<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1659</ul> 1660<p>Asynchronously writes data to a file, replacing the file if it already exists. 1661<code>data</code> can be a string, a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>, or, an object with an own (not inherited) 1662<code>toString</code> function property.</p> 1663<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p> 1664<p>If <code>options</code> is a string, then it specifies the encoding.</p> 1665<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 1666for more details.</p> 1667<p>Any specified <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support writing.</p> 1668<p>It is unsafe to use <code>fsPromises.writeFile()</code> multiple times on the same file 1669without waiting for the promise to be settled.</p> 1670<p>Similarly to <code>fsPromises.readFile</code> - <code>fsPromises.writeFile</code> is a convenience 1671method that performs multiple <code>write</code> calls internally to write the buffer 1672passed to it. For performance sensitive code consider using 1673<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 1674<p>It is possible to use an <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> to cancel an <code>fsPromises.writeFile()</code>. 1675Cancelation is "best effort", and some amount of data is likely still 1676to be written.</p> 1677<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { writeFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1678 1679<span class="hljs-keyword">try</span> { 1680 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1681 <span class="hljs-keyword">const</span> { signal } = controller; 1682 <span class="hljs-keyword">const</span> data = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Uint</span>8<span class="hljs-built_in">Array</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Hello Node.js'</span>)); 1683 <span class="hljs-keyword">const</span> promise = <span class="hljs-title function_">writeFile</span>(<span class="hljs-string">'message.txt'</span>, data, { signal }); 1684 1685 <span class="hljs-comment">// Abort the request before the promise settles.</span> 1686 controller.<span class="hljs-title function_">abort</span>(); 1687 1688 <span class="hljs-keyword">await</span> promise; 1689} <span class="hljs-keyword">catch</span> (err) { 1690 <span class="hljs-comment">// When a request is aborted - err is an AbortError</span> 1691 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1692}</code></pre> 1693<p>Aborting an ongoing request does not abort individual operating 1694system requests but rather the internal buffering <code>fs.writeFile</code> performs.</p> 1695</section><section><h3>Callback API<span><a class="mark" href="#fs_callback_api" id="fs_callback_api">#</a></span></h3> 1696<p>The callback APIs perform all operations asynchronously, without blocking the 1697event loop, then invoke a callback function upon completion or error.</p> 1698<p>The callback APIs use the underlying Node.js threadpool to perform file 1699system operations off the event loop thread. These operations are not 1700synchronized or threadsafe. Care must be taken when performing multiple 1701concurrent modifications on the same file or data corruption may occur.</p> 1702<h4><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></h4> 1703<div class="api_metadata"> 1704<details class="changelog"><summary>History</summary> 1705<table> 1706<tbody><tr><th>Version</th><th>Changes</th></tr> 1707<tr><td>v7.6.0</td> 1708<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 1709<tr><td>v6.3.0</td> 1710<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> 1711<tr><td>v0.11.15</td> 1712<td><p><span>Added in: v0.11.15</span></p></td></tr> 1713</tbody></table> 1714</details> 1715</div> 1716<ul> 1717<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> 1718<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> 1719<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1720<ul> 1721<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1722</ul> 1723</li> 1724</ul> 1725<p>Tests a user's permissions for the file or directory specified by <code>path</code>. 1726The <code>mode</code> argument is an optional integer that specifies the accessibility 1727checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values 1728of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of 1729two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 1730<p>The final argument, <code>callback</code>, is a callback function that is invoked with 1731a possible error argument. If any of the accessibility checks fail, the error 1732argument will be an <code>Error</code> object. The following examples check if 1733<code>package.json</code> exists, and if it is readable or writable.</p> 1734<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { access, constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1735 1736<span class="hljs-keyword">const</span> file = <span class="hljs-string">'package.json'</span>; 1737 1738<span class="hljs-comment">// Check if the file exists in the current directory.</span> 1739<span class="hljs-title function_">access</span>(file, constants.<span class="hljs-property">F_OK</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1740 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 1741}); 1742 1743<span class="hljs-comment">// Check if the file is readable.</span> 1744<span class="hljs-title function_">access</span>(file, constants.<span class="hljs-property">R_OK</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1745 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 1746}); 1747 1748<span class="hljs-comment">// Check if the file is writable.</span> 1749<span class="hljs-title function_">access</span>(file, constants.<span class="hljs-property">W_OK</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1750 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<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>); 1751}); 1752 1753<span class="hljs-comment">// Check if the file exists in the current directory, and if it is writable.</span> 1754<span class="hljs-title function_">access</span>(file, constants.<span class="hljs-property">F_OK</span> | constants.<span class="hljs-property">W_OK</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1755 <span class="hljs-keyword">if</span> (err) { 1756 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>( 1757 <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>); 1758 } <span class="hljs-keyword">else</span> { 1759 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`<span class="hljs-subst">${file}</span> exists, and it is writable`</span>); 1760 } 1761});</code></pre> 1762<p>Do not use <code>fs.access()</code> to check for the accessibility of a file before calling 1763<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code>. Doing 1764so introduces a race condition, since other processes may change the file's 1765state between the two calls. Instead, user code should open/read/write the 1766file directly and handle the error raised if the file is not accessible.</p> 1767<p><strong>write (NOT RECOMMENDED)</strong></p> 1768<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { access, open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1769 1770<span class="hljs-title function_">access</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1771 <span class="hljs-keyword">if</span> (!err) { 1772 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 1773 <span class="hljs-keyword">return</span>; 1774 } 1775 1776 <span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 1777 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1778 1779 <span class="hljs-keyword">try</span> { 1780 <span class="hljs-title function_">writeMyData</span>(fd); 1781 } <span class="hljs-keyword">finally</span> { 1782 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1783 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1784 }); 1785 } 1786 }); 1787});</code></pre> 1788<p><strong>write (RECOMMENDED)</strong></p> 1789<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1790 1791<span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 1792 <span class="hljs-keyword">if</span> (err) { 1793 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'EEXIST'</span>) { 1794 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 1795 <span class="hljs-keyword">return</span>; 1796 } 1797 1798 <span class="hljs-keyword">throw</span> err; 1799 } 1800 1801 <span class="hljs-keyword">try</span> { 1802 <span class="hljs-title function_">writeMyData</span>(fd); 1803 } <span class="hljs-keyword">finally</span> { 1804 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1805 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1806 }); 1807 } 1808});</code></pre> 1809<p><strong>read (NOT RECOMMENDED)</strong></p> 1810<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { access, open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1811<span class="hljs-title function_">access</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1812 <span class="hljs-keyword">if</span> (err) { 1813 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 1814 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 1815 <span class="hljs-keyword">return</span>; 1816 } 1817 1818 <span class="hljs-keyword">throw</span> err; 1819 } 1820 1821 <span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 1822 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1823 1824 <span class="hljs-keyword">try</span> { 1825 <span class="hljs-title function_">readMyData</span>(fd); 1826 } <span class="hljs-keyword">finally</span> { 1827 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1828 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1829 }); 1830 } 1831 }); 1832});</code></pre> 1833<p><strong>read (RECOMMENDED)</strong></p> 1834<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1835 1836<span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 1837 <span class="hljs-keyword">if</span> (err) { 1838 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 1839 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 1840 <span class="hljs-keyword">return</span>; 1841 } 1842 1843 <span class="hljs-keyword">throw</span> err; 1844 } 1845 1846 <span class="hljs-keyword">try</span> { 1847 <span class="hljs-title function_">readMyData</span>(fd); 1848 } <span class="hljs-keyword">finally</span> { 1849 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1850 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1851 }); 1852 } 1853});</code></pre> 1854<p>The "not recommended" examples above check for accessibility and then use the 1855file; the "recommended" examples are better because they use the file directly 1856and handle the error, if any.</p> 1857<p>In general, check for the accessibility of a file only if the file will not be 1858used directly, for example when its accessibility is a signal from another 1859process.</p> 1860<p>On Windows, access-control policies (ACLs) on a directory may limit access to 1861a file or directory. The <code>fs.access()</code> function, however, does not check the 1862ACL and therefore may report that a path is accessible even if the ACL restricts 1863the user from reading or writing to it.</p> 1864<h4><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></h4> 1865<div class="api_metadata"> 1866<details class="changelog"><summary>History</summary> 1867<table> 1868<tbody><tr><th>Version</th><th>Changes</th></tr> 1869<tr><td>v10.0.0</td> 1870<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> 1871<tr><td>v7.0.0</td> 1872<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> 1873<tr><td>v7.0.0</td> 1874<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 1875<tr><td>v5.0.0</td> 1876<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 1877<tr><td>v0.6.7</td> 1878<td><p><span>Added in: v0.6.7</span></p></td></tr> 1879</tbody></table> 1880</details> 1881</div> 1882<ul> 1883<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> 1884<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> 1885<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> 1886<ul> 1887<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> 1888<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> 1889<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> 1890</ul> 1891</li> 1892<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1893<ul> 1894<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1895</ul> 1896</li> 1897</ul> 1898<p>Asynchronously append data to a file, creating the file if it does not yet 1899exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 1900<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 1901for more details.</p> 1902<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { appendFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1903 1904<span class="hljs-title function_">appendFile</span>(<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> { 1905 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1906 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The "data to append" was appended to file!'</span>); 1907});</code></pre> 1908<p>If <code>options</code> is a string, then it specifies the encoding:</p> 1909<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { appendFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1910 1911<span class="hljs-title function_">appendFile</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre> 1912<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened 1913for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will 1914not be closed automatically.</p> 1915<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close, appendFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1916 1917<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 1918 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1919 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1920 }); 1921} 1922 1923<span class="hljs-title function_">open</span>(<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> { 1924 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1925 1926 <span class="hljs-keyword">try</span> { 1927 <span class="hljs-title function_">appendFile</span>(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> { 1928 <span class="hljs-title function_">closeFd</span>(fd); 1929 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1930 }); 1931 } <span class="hljs-keyword">catch</span> (err) { 1932 <span class="hljs-title function_">closeFd</span>(fd); 1933 <span class="hljs-keyword">throw</span> err; 1934 } 1935});</code></pre> 1936<h4><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></h4> 1937<div class="api_metadata"> 1938<details class="changelog"><summary>History</summary> 1939<table> 1940<tbody><tr><th>Version</th><th>Changes</th></tr> 1941<tr><td>v10.0.0</td> 1942<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> 1943<tr><td>v7.6.0</td> 1944<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 1945<tr><td>v7.0.0</td> 1946<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> 1947<tr><td>v0.1.30</td> 1948<td><p><span>Added in: v0.1.30</span></p></td></tr> 1949</tbody></table> 1950</details> 1951</div> 1952<ul> 1953<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> 1954<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> 1955<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1956<ul> 1957<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1958</ul> 1959</li> 1960</ul> 1961<p>Asynchronously changes the permissions of a file. No arguments other than a 1962possible exception are given to the completion callback.</p> 1963<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a> documentation for more detail.</p> 1964<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { chmod } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 1965 1966<span class="hljs-title function_">chmod</span>(<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> { 1967 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1968 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The permissions for file "my_file.txt" have been changed!'</span>); 1969});</code></pre> 1970<h5>File modes<span><a class="mark" href="#fs_file_modes" id="fs_file_modes">#</a></span></h5> 1971<p>The <code>mode</code> argument used in both the <code>fs.chmod()</code> and <code>fs.chmodSync()</code> 1972methods is a numeric bitmask created using a logical OR of the following 1973constants:</p> 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029<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> 2030<p>An easier method of constructing the <code>mode</code> is to use a sequence of three 2031octal digits (e.g. <code>765</code>). The left-most digit (<code>7</code> in the example), specifies 2032the permissions for the file owner. The middle digit (<code>6</code> in the example), 2033specifies permissions for the group. The right-most digit (<code>5</code> in the example), 2034specifies the permissions for others.</p> 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076<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> 2077<p>For example, the octal value <code>0o765</code> means:</p> 2078<ul> 2079<li>The owner may read, write and execute the file.</li> 2080<li>The group may read and write the file.</li> 2081<li>Others may read and execute the file.</li> 2082</ul> 2083<p>When using raw numbers where file modes are expected, any value larger than 2084<code>0o777</code> may result in platform-specific behaviors that are not supported to work 2085consistently. Therefore constants like <code>S_ISVTX</code>, <code>S_ISGID</code> or <code>S_ISUID</code> are not 2086exposed in <code>fs.constants</code>.</p> 2087<p>Caveats: on Windows only the write permission can be changed, and the 2088distinction among the permissions of group, owner or others is not 2089implemented.</p> 2090<h4><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></h4> 2091<div class="api_metadata"> 2092<details class="changelog"><summary>History</summary> 2093<table> 2094<tbody><tr><th>Version</th><th>Changes</th></tr> 2095<tr><td>v10.0.0</td> 2096<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> 2097<tr><td>v7.6.0</td> 2098<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2099<tr><td>v7.0.0</td> 2100<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> 2101<tr><td>v0.1.97</td> 2102<td><p><span>Added in: v0.1.97</span></p></td></tr> 2103</tbody></table> 2104</details> 2105</div> 2106<ul> 2107<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> 2108<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2109<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2110<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2111<ul> 2112<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2113</ul> 2114</li> 2115</ul> 2116<p>Asynchronously changes owner and group of a file. No arguments other than a 2117possible exception are given to the completion callback.</p> 2118<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a> documentation for more detail.</p> 2119<h4><code>fs.close(fd[, callback])</code><span><a class="mark" href="#fs_fs_close_fd_callback" id="fs_fs_close_fd_callback">#</a></span></h4> 2120<div class="api_metadata"> 2121<details class="changelog"><summary>History</summary> 2122<table> 2123<tbody><tr><th>Version</th><th>Changes</th></tr> 2124<tr><td>v14.17.0</td> 2125<td><p>A default callback is now used if one is not provided.</p></td></tr> 2126<tr><td>v10.0.0</td> 2127<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> 2128<tr><td>v7.0.0</td> 2129<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> 2130<tr><td>v0.0.2</td> 2131<td><p><span>Added in: v0.0.2</span></p></td></tr> 2132</tbody></table> 2133</details> 2134</div> 2135<ul> 2136<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2137<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2138<ul> 2139<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2140</ul> 2141</li> 2142</ul> 2143<p>Closes the file descriptor. No arguments other than a possible exception are 2144given to the completion callback.</p> 2145<p>Calling <code>fs.close()</code> on any file descriptor (<code>fd</code>) that is currently in use 2146through any other <code>fs</code> operation may lead to undefined behavior.</p> 2147<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/close.2.html"><code>close(2)</code></a> documentation for more detail.</p> 2148<h4><code>fs.copyFile(src, dest[, mode], callback)</code><span><a class="mark" href="#fs_fs_copyfile_src_dest_mode_callback" id="fs_fs_copyfile_src_dest_mode_callback">#</a></span></h4> 2149<div class="api_metadata"> 2150<details class="changelog"><summary>History</summary> 2151<table> 2152<tbody><tr><th>Version</th><th>Changes</th></tr> 2153<tr><td>v14.0.0</td> 2154<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 2155<tr><td>v8.5.0</td> 2156<td><p><span>Added in: v8.5.0</span></p></td></tr> 2157</tbody></table> 2158</details> 2159</div> 2160<ul> 2161<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> 2162<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> 2163<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> modifiers for copy operation. <strong>Default:</strong> <code>0</code>.</li> 2164<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 2165</ul> 2166<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 2167already exists. No arguments other than a possible exception are given to the 2168callback function. Node.js makes no guarantees about the atomicity of the copy 2169operation. If an error occurs after the destination file has been opened for 2170writing, Node.js will attempt to remove the destination.</p> 2171<p><code>mode</code> is an optional integer that specifies the behavior 2172of the copy operation. It is possible to create a mask consisting of the bitwise 2173OR of two or more values (e.g. 2174<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p> 2175<ul> 2176<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already 2177exists.</li> 2178<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a 2179copy-on-write reflink. If the platform does not support copy-on-write, then a 2180fallback copy mechanism is used.</li> 2181<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 2182create a copy-on-write reflink. If the platform does not support 2183copy-on-write, then the operation will fail.</li> 2184</ul> 2185<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { copyFile, constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2186 2187<span class="hljs-keyword">function</span> <span class="hljs-title function_">callback</span>(<span class="hljs-params">err</span>) { 2188 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2189 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'source.txt was copied to destination.txt'</span>); 2190} 2191 2192<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span> 2193<span class="hljs-title function_">copyFile</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, callback); 2194 2195<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 2196<span class="hljs-title function_">copyFile</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, constants.<span class="hljs-property">COPYFILE_EXCL</span>, callback);</code></pre> 2197<h4><code>fs.createReadStream(path[, options])</code><span><a class="mark" href="#fs_fs_createreadstream_path_options" id="fs_fs_createreadstream_path_options">#</a></span></h4> 2198<div class="api_metadata"> 2199<details class="changelog"><summary>History</summary> 2200<table> 2201<tbody><tr><th>Version</th><th>Changes</th></tr> 2202<tr><td>v14.0.0</td> 2203<td><p>Change <code>emitClose</code> default to <code>true</code>.</p></td></tr> 2204<tr><td>v13.6.0, v12.17.0</td> 2205<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr> 2206<tr><td>v12.10.0</td> 2207<td><p>Enable <code>emitClose</code> option.</p></td></tr> 2208<tr><td>v11.0.0</td> 2209<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> 2210<tr><td>v7.6.0</td> 2211<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2212<tr><td>v7.0.0</td> 2213<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 2214<tr><td>v2.3.0</td> 2215<td><p>The passed <code>options</code> object can be a string now.</p></td></tr> 2216<tr><td>v0.1.31</td> 2217<td><p><span>Added in: v0.1.31</span></p></td></tr> 2218</tbody></table> 2219</details> 2220</div> 2221<ul> 2222<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> 2223<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> 2224<ul> 2225<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> 2226<code>'r'</code>.</li> 2227<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> 2228<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> 2229<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> 2230<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> 2231<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>true</code></li> 2232<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2233<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> 2234<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> 2235<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> 2236</ul> 2237</li> 2238<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> 2239</ul> 2240<p>Unlike the 16 kb default <code>highWaterMark</code> for a readable stream, the stream 2241returned by this method has a default <code>highWaterMark</code> of 64 kb.</p> 2242<p><code>options</code> can include <code>start</code> and <code>end</code> values to read a range of bytes from 2243the file instead of the entire file. Both <code>start</code> and <code>end</code> are inclusive and 2244start counting at 0, allowed values are in the 2245[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 2246omitted or <code>undefined</code>, <code>fs.createReadStream()</code> reads sequentially from the 2247current file position. The <code>encoding</code> can be any one of those accepted by 2248<a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 2249<p>If <code>fd</code> is specified, <code>ReadStream</code> will ignore the <code>path</code> argument and will use 2250the specified file descriptor. This means that no <code>'open'</code> event will be 2251emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s should be passed to 2252<a href="net.html#net_class_net_socket" class="type"><net.Socket></a>.</p> 2253<p>If <code>fd</code> points to a character device that only supports blocking reads 2254(such as keyboard or sound card), read operations do not finish until data is 2255available. This can prevent the process from exiting and the stream from 2256closing naturally.</p> 2257<p>By default, the stream will emit a <code>'close'</code> event after it has been 2258destroyed, like most <code>Readable</code> streams. Set the <code>emitClose</code> option to 2259<code>false</code> to change this behavior.</p> 2260<p>By providing the <code>fs</code> option, it is possible to override the corresponding <code>fs</code> 2261implementations for <code>open</code>, <code>read</code>, and <code>close</code>. When providing the <code>fs</code> option, 2262overrides for <code>open</code>, <code>read</code>, and <code>close</code> are required.</p> 2263<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { createReadStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2264 2265<span class="hljs-comment">// Create a stream from some character device.</span> 2266<span class="hljs-keyword">const</span> stream = <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'/dev/input/event0'</span>); 2267<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> { 2268 stream.<span class="hljs-title function_">close</span>(); <span class="hljs-comment">// This may not close the stream.</span> 2269 <span class="hljs-comment">// Artificially marking end-of-stream, as if the underlying resource had</span> 2270 <span class="hljs-comment">// indicated end-of-file by itself, allows the stream to close.</span> 2271 <span class="hljs-comment">// This does not cancel pending read operations, and if there is such an</span> 2272 <span class="hljs-comment">// operation, the process may still not be able to exit successfully</span> 2273 <span class="hljs-comment">// until it finishes.</span> 2274 stream.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 2275 stream.<span class="hljs-title function_">read</span>(<span class="hljs-number">0</span>); 2276}, <span class="hljs-number">100</span>);</code></pre> 2277<p>If <code>autoClose</code> is false, then the file descriptor won't be closed, even if 2278there's an error. It is the application's responsibility to close it and make 2279sure there's no file descriptor leak. If <code>autoClose</code> is set to true (default 2280behavior), on <code>'error'</code> or <code>'end'</code> the file descriptor will be closed 2281automatically.</p> 2282<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the 2283file was created.</p> 2284<p>An example to read the last 10 bytes of a file which is 100 bytes long:</p> 2285<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { createReadStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2286 2287<span class="hljs-title function_">createReadStream</span>(<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> 2288<p>If <code>options</code> is a string, then it specifies the encoding.</p> 2289<h4><code>fs.createWriteStream(path[, options])</code><span><a class="mark" href="#fs_fs_createwritestream_path_options" id="fs_fs_createwritestream_path_options">#</a></span></h4> 2290<div class="api_metadata"> 2291<details class="changelog"><summary>History</summary> 2292<table> 2293<tbody><tr><th>Version</th><th>Changes</th></tr> 2294<tr><td>v14.0.0</td> 2295<td><p>Change <code>emitClose</code> default to <code>true</code>.</p></td></tr> 2296<tr><td>v13.6.0, v12.17.0</td> 2297<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr> 2298<tr><td>v12.10.0</td> 2299<td><p>Enable <code>emitClose</code> option.</p></td></tr> 2300<tr><td>v7.6.0</td> 2301<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2302<tr><td>v7.0.0</td> 2303<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 2304<tr><td>v5.5.0</td> 2305<td><p>The <code>autoClose</code> option is supported now.</p></td></tr> 2306<tr><td>v2.3.0</td> 2307<td><p>The passed <code>options</code> object can be a string now.</p></td></tr> 2308<tr><td>v0.1.31</td> 2309<td><p><span>Added in: v0.1.31</span></p></td></tr> 2310</tbody></table> 2311</details> 2312</div> 2313<ul> 2314<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> 2315<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> 2316<ul> 2317<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> 2318<code>'w'</code>.</li> 2319<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> 2320<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> 2321<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> 2322<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> 2323<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>true</code></li> 2324<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2325<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> 2326</ul> 2327</li> 2328<li>Returns: <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> See <a href="stream.html#stream_class_stream_writable">Writable Stream</a>.</li> 2329</ul> 2330<p><code>options</code> may also include a <code>start</code> option to allow writing data at some 2331position past the beginning of the file, allowed values are in the 2332[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 2333it may require the <code>flags</code> option to be set to <code>r+</code> rather than the default <code>w</code>. 2334The <code>encoding</code> can be any one of those accepted by <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 2335<p>If <code>autoClose</code> is set to true (default behavior) on <code>'error'</code> or <code>'finish'</code> 2336the file descriptor will be closed automatically. If <code>autoClose</code> is false, 2337then the file descriptor won't be closed, even if there's an error. 2338It is the application's responsibility to close it and make sure there's no 2339file descriptor leak.</p> 2340<p>By default, the stream will emit a <code>'close'</code> event after it has been 2341destroyed, like most <code>Writable</code> streams. Set the <code>emitClose</code> option to 2342<code>false</code> to change this behavior.</p> 2343<p>By providing the <code>fs</code> option it is possible to override the corresponding <code>fs</code> 2344implementations for <code>open</code>, <code>write</code>, <code>writev</code> and <code>close</code>. Overriding <code>write()</code> 2345without <code>writev()</code> can reduce performance as some optimizations (<code>_writev()</code>) 2346will be disabled. When providing the <code>fs</code> option, overrides for <code>open</code>, 2347<code>close</code>, and at least one of <code>write</code> and <code>writev</code> are required.</p> 2348<p>Like <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>, if <code>fd</code> is specified, <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> will ignore the 2349<code>path</code> argument and will use the specified file descriptor. This means that no 2350<code>'open'</code> event will be emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s 2351should be passed to <a href="net.html#net_class_net_socket" class="type"><net.Socket></a>.</p> 2352<p>If <code>options</code> is a string, then it specifies the encoding.</p> 2353<h4><code>fs.exists(path, callback)</code><span><a class="mark" href="#fs_fs_exists_path_callback" id="fs_fs_exists_path_callback">#</a></span></h4> 2354<div class="api_metadata"> 2355<details class="changelog"><summary>History</summary> 2356<table> 2357<tbody><tr><th>Version</th><th>Changes</th></tr> 2358<tr><td>v7.6.0</td> 2359<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2360<tr><td>v1.0.0</td> 2361<td><p><span>Deprecated since: v1.0.0</span></p></td></tr> 2362<tr><td>v0.0.2</td> 2363<td><p><span>Added in: v0.0.2</span></p></td></tr> 2364</tbody></table> 2365</details> 2366</div> 2367<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> 2368<ul> 2369<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> 2370<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2371<ul> 2372<li><code>exists</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 2373</ul> 2374</li> 2375</ul> 2376<p>Test whether or not the given path exists by checking with the file system. 2377Then call the <code>callback</code> argument with either true or false:</p> 2378<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { exists } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2379 2380<span class="hljs-title function_">exists</span>(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> { 2381 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(e ? <span class="hljs-string">'it exists'</span> : <span class="hljs-string">'no passwd!'</span>); 2382});</code></pre> 2383<p><strong>The parameters for this callback are not consistent with other Node.js 2384callbacks.</strong> Normally, the first parameter to a Node.js callback is an <code>err</code> 2385parameter, optionally followed by other parameters. The <code>fs.exists()</code> callback 2386has only one boolean parameter. This is one reason <code>fs.access()</code> is recommended 2387instead of <code>fs.exists()</code>.</p> 2388<p>Using <code>fs.exists()</code> to check for the existence of a file before calling 2389<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended. Doing 2390so introduces a race condition, since other processes may change the file's 2391state between the two calls. Instead, user code should open/read/write the 2392file directly and handle the error raised if the file does not exist.</p> 2393<p><strong>write (NOT RECOMMENDED)</strong></p> 2394<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { exists, open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2395 2396<span class="hljs-title function_">exists</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> { 2397 <span class="hljs-keyword">if</span> (e) { 2398 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 2399 } <span class="hljs-keyword">else</span> { 2400 <span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 2401 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2402 2403 <span class="hljs-keyword">try</span> { 2404 <span class="hljs-title function_">writeMyData</span>(fd); 2405 } <span class="hljs-keyword">finally</span> { 2406 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2407 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2408 }); 2409 } 2410 }); 2411 } 2412});</code></pre> 2413<p><strong>write (RECOMMENDED)</strong></p> 2414<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2415<span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'wx'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 2416 <span class="hljs-keyword">if</span> (err) { 2417 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'EEXIST'</span>) { 2418 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 2419 <span class="hljs-keyword">return</span>; 2420 } 2421 2422 <span class="hljs-keyword">throw</span> err; 2423 } 2424 2425 <span class="hljs-keyword">try</span> { 2426 <span class="hljs-title function_">writeMyData</span>(fd); 2427 } <span class="hljs-keyword">finally</span> { 2428 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2429 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2430 }); 2431 } 2432});</code></pre> 2433<p><strong>read (NOT RECOMMENDED)</strong></p> 2434<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close, exists } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2435 2436<span class="hljs-title function_">exists</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> { 2437 <span class="hljs-keyword">if</span> (e) { 2438 <span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 2439 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2440 2441 <span class="hljs-keyword">try</span> { 2442 <span class="hljs-title function_">readMyData</span>(fd); 2443 } <span class="hljs-keyword">finally</span> { 2444 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2445 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2446 }); 2447 } 2448 }); 2449 } <span class="hljs-keyword">else</span> { 2450 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 2451 } 2452});</code></pre> 2453<p><strong>read (RECOMMENDED)</strong></p> 2454<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2455 2456<span class="hljs-title function_">open</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-string">'r'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 2457 <span class="hljs-keyword">if</span> (err) { 2458 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 2459 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 2460 <span class="hljs-keyword">return</span>; 2461 } 2462 2463 <span class="hljs-keyword">throw</span> err; 2464 } 2465 2466 <span class="hljs-keyword">try</span> { 2467 <span class="hljs-title function_">readMyData</span>(fd); 2468 } <span class="hljs-keyword">finally</span> { 2469 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2470 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2471 }); 2472 } 2473});</code></pre> 2474<p>The "not recommended" examples above check for existence and then use the 2475file; the "recommended" examples are better because they use the file directly 2476and handle the error, if any.</p> 2477<p>In general, check for the existence of a file only if the file won’t be 2478used directly, for example when its existence is a signal from another 2479process.</p> 2480<h4><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></h4> 2481<div class="api_metadata"> 2482<details class="changelog"><summary>History</summary> 2483<table> 2484<tbody><tr><th>Version</th><th>Changes</th></tr> 2485<tr><td>v10.0.0</td> 2486<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> 2487<tr><td>v7.0.0</td> 2488<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> 2489<tr><td>v0.4.7</td> 2490<td><p><span>Added in: v0.4.7</span></p></td></tr> 2491</tbody></table> 2492</details> 2493</div> 2494<ul> 2495<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2496<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> 2497<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2498<ul> 2499<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2500</ul> 2501</li> 2502</ul> 2503<p>Sets the permissions on the file. No arguments other than a possible exception 2504are given to the completion callback.</p> 2505<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fchmod.2.html"><code>fchmod(2)</code></a> documentation for more detail.</p> 2506<h4><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></h4> 2507<div class="api_metadata"> 2508<details class="changelog"><summary>History</summary> 2509<table> 2510<tbody><tr><th>Version</th><th>Changes</th></tr> 2511<tr><td>v10.0.0</td> 2512<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> 2513<tr><td>v7.0.0</td> 2514<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> 2515<tr><td>v0.4.7</td> 2516<td><p><span>Added in: v0.4.7</span></p></td></tr> 2517</tbody></table> 2518</details> 2519</div> 2520<ul> 2521<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2522<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2523<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2524<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2525<ul> 2526<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2527</ul> 2528</li> 2529</ul> 2530<p>Sets the owner of the file. No arguments other than a possible exception are 2531given to the completion callback.</p> 2532<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fchown.2.html"><code>fchown(2)</code></a> documentation for more detail.</p> 2533<h4><code>fs.fdatasync(fd, callback)</code><span><a class="mark" href="#fs_fs_fdatasync_fd_callback" id="fs_fs_fdatasync_fd_callback">#</a></span></h4> 2534<div class="api_metadata"> 2535<details class="changelog"><summary>History</summary> 2536<table> 2537<tbody><tr><th>Version</th><th>Changes</th></tr> 2538<tr><td>v10.0.0</td> 2539<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> 2540<tr><td>v7.0.0</td> 2541<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> 2542<tr><td>v0.1.96</td> 2543<td><p><span>Added in: v0.1.96</span></p></td></tr> 2544</tbody></table> 2545</details> 2546</div> 2547<ul> 2548<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2549<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2550<ul> 2551<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2552</ul> 2553</li> 2554</ul> 2555<p>Forces all currently queued I/O operations associated with the file to the 2556operating system's synchronized I/O completion state. Refer to the POSIX 2557<a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a> documentation for details. No arguments other than a possible 2558exception are given to the completion callback.</p> 2559<h4><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></h4> 2560<div class="api_metadata"> 2561<details class="changelog"><summary>History</summary> 2562<table> 2563<tbody><tr><th>Version</th><th>Changes</th></tr> 2564<tr><td>v10.5.0</td> 2565<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 2566<tr><td>v10.0.0</td> 2567<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> 2568<tr><td>v7.0.0</td> 2569<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> 2570<tr><td>v0.1.95</td> 2571<td><p><span>Added in: v0.1.95</span></p></td></tr> 2572</tbody></table> 2573</details> 2574</div> 2575<ul> 2576<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2577<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 2578<ul> 2579<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 2580<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 2581</ul> 2582</li> 2583<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2584<ul> 2585<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2586<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 2587</ul> 2588</li> 2589</ul> 2590<p>Invokes the callback with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file descriptor.</p> 2591<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fstat.2.html"><code>fstat(2)</code></a> documentation for more detail.</p> 2592<h4><code>fs.fsync(fd, callback)</code><span><a class="mark" href="#fs_fs_fsync_fd_callback" id="fs_fs_fsync_fd_callback">#</a></span></h4> 2593<div class="api_metadata"> 2594<details class="changelog"><summary>History</summary> 2595<table> 2596<tbody><tr><th>Version</th><th>Changes</th></tr> 2597<tr><td>v10.0.0</td> 2598<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> 2599<tr><td>v7.0.0</td> 2600<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> 2601<tr><td>v0.1.96</td> 2602<td><p><span>Added in: v0.1.96</span></p></td></tr> 2603</tbody></table> 2604</details> 2605</div> 2606<ul> 2607<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2608<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2609<ul> 2610<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2611</ul> 2612</li> 2613</ul> 2614<p>Request that all data for the open file descriptor is flushed to the storage 2615device. The specific implementation is operating system and device specific. 2616Refer to the POSIX <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a> documentation for more detail. No arguments other 2617than a possible exception are given to the completion callback.</p> 2618<h4><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></h4> 2619<div class="api_metadata"> 2620<details class="changelog"><summary>History</summary> 2621<table> 2622<tbody><tr><th>Version</th><th>Changes</th></tr> 2623<tr><td>v10.0.0</td> 2624<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> 2625<tr><td>v7.0.0</td> 2626<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> 2627<tr><td>v0.8.6</td> 2628<td><p><span>Added in: v0.8.6</span></p></td></tr> 2629</tbody></table> 2630</details> 2631</div> 2632<ul> 2633<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2634<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> 2635<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2636<ul> 2637<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2638</ul> 2639</li> 2640</ul> 2641<p>Truncates the file descriptor. No arguments other than a possible exception are 2642given to the completion callback.</p> 2643<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/ftruncate.2.html"><code>ftruncate(2)</code></a> documentation for more detail.</p> 2644<p>If the file referred to by the file descriptor was larger than <code>len</code> bytes, only 2645the first <code>len</code> bytes will be retained in the file.</p> 2646<p>For example, the following program retains only the first four bytes of the 2647file:</p> 2648<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close, ftruncate } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2649 2650<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 2651 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2652 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2653 }); 2654} 2655 2656<span class="hljs-title function_">open</span>(<span class="hljs-string">'temp.txt'</span>, <span class="hljs-string">'r+'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 2657 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2658 2659 <span class="hljs-keyword">try</span> { 2660 <span class="hljs-title function_">ftruncate</span>(fd, <span class="hljs-number">4</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2661 <span class="hljs-title function_">closeFd</span>(fd); 2662 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2663 }); 2664 } <span class="hljs-keyword">catch</span> (err) { 2665 <span class="hljs-title function_">closeFd</span>(fd); 2666 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2667 } 2668});</code></pre> 2669<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the 2670extended part is filled with null bytes (<code>'\0'</code>):</p> 2671<p>If <code>len</code> is negative then <code>0</code> will be used.</p> 2672<h4><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></h4> 2673<div class="api_metadata"> 2674<details class="changelog"><summary>History</summary> 2675<table> 2676<tbody><tr><th>Version</th><th>Changes</th></tr> 2677<tr><td>v10.0.0</td> 2678<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> 2679<tr><td>v7.0.0</td> 2680<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> 2681<tr><td>v4.1.0</td> 2682<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 2683<tr><td>v0.4.2</td> 2684<td><p><span>Added in: v0.4.2</span></p></td></tr> 2685</tbody></table> 2686</details> 2687</div> 2688<ul> 2689<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2690<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> 2691<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> 2692<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2693<ul> 2694<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2695</ul> 2696</li> 2697</ul> 2698<p>Change the file system timestamps of the object referenced by the supplied file 2699descriptor. See <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p> 2700<p>This function does not work on AIX versions before 7.1, it will return the 2701error <code>UV_ENOSYS</code>.</p> 2702<h4><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></h4> 2703<div class="api_metadata"> 2704<details class="changelog"><summary>History</summary> 2705<table> 2706<tbody><tr><th>Version</th><th>Changes</th></tr> 2707<tr><td>v10.0.0</td> 2708<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> 2709<tr><td>v7.0.0</td> 2710<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> 2711<tr><td>v0.4.7</td> 2712<td><p><span>Deprecated since: v0.4.7</span></p></td></tr> 2713</tbody></table> 2714</details> 2715</div> 2716<ul> 2717<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> 2718<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2719<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2720<ul> 2721<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2722</ul> 2723</li> 2724</ul> 2725<p>Changes the permissions on a symbolic link. No arguments other than a possible 2726exception are given to the completion callback.</p> 2727<p>This method is only implemented on macOS.</p> 2728<p>See the POSIX <a href="https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2"><code>lchmod(2)</code></a> documentation for more detail.</p> 2729<h4><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></h4> 2730<div class="api_metadata"> 2731<details class="changelog"><summary>History</summary> 2732<table> 2733<tbody><tr><th>Version</th><th>Changes</th></tr> 2734<tr><td>v10.6.0</td> 2735<td><p>This API is no longer deprecated.</p></td></tr> 2736<tr><td>v10.0.0</td> 2737<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> 2738<tr><td>v7.0.0</td> 2739<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> 2740<tr><td>v0.4.7</td> 2741<td><p>Documentation-only deprecation.</p></td></tr> 2742</tbody></table> 2743</details> 2744</div> 2745<ul> 2746<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> 2747<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2748<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2749<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2750<ul> 2751<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2752</ul> 2753</li> 2754</ul> 2755<p>Set the owner of the symbolic link. No arguments other than a possible 2756exception are given to the completion callback.</p> 2757<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/lchown.2.html"><code>lchown(2)</code></a> documentation for more detail.</p> 2758<h4><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></h4> 2759<div class="api_metadata"> 2760<span>Added in: v14.5.0, v12.19.0</span> 2761</div> 2762<ul> 2763<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> 2764<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> 2765<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> 2766<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2767<ul> 2768<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2769</ul> 2770</li> 2771</ul> 2772<p>Changes the access and modification times of a file in the same way as 2773<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 2774link, then the link is not dereferenced: instead, the timestamps of the 2775symbolic link itself are changed.</p> 2776<p>No arguments other than a possible exception are given to the completion 2777callback.</p> 2778<h4><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></h4> 2779<div class="api_metadata"> 2780<details class="changelog"><summary>History</summary> 2781<table> 2782<tbody><tr><th>Version</th><th>Changes</th></tr> 2783<tr><td>v10.0.0</td> 2784<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> 2785<tr><td>v7.6.0</td> 2786<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> 2787<tr><td>v7.0.0</td> 2788<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> 2789<tr><td>v0.1.31</td> 2790<td><p><span>Added in: v0.1.31</span></p></td></tr> 2791</tbody></table> 2792</details> 2793</div> 2794<ul> 2795<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> 2796<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> 2797<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2798<ul> 2799<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2800</ul> 2801</li> 2802</ul> 2803<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 2804<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a> documentation for more detail. No arguments other than a possible 2805exception are given to the completion callback.</p> 2806<h4><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></h4> 2807<div class="api_metadata"> 2808<details class="changelog"><summary>History</summary> 2809<table> 2810<tbody><tr><th>Version</th><th>Changes</th></tr> 2811<tr><td>v10.5.0</td> 2812<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 2813<tr><td>v10.0.0</td> 2814<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> 2815<tr><td>v7.6.0</td> 2816<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2817<tr><td>v7.0.0</td> 2818<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> 2819<tr><td>v0.1.30</td> 2820<td><p><span>Added in: v0.1.30</span></p></td></tr> 2821</tbody></table> 2822</details> 2823</div> 2824<ul> 2825<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> 2826<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 2827<ul> 2828<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 2829<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 2830</ul> 2831</li> 2832<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2833<ul> 2834<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2835<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 2836</ul> 2837</li> 2838</ul> 2839<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the symbolic link referred to by the path. 2840The callback gets two arguments <code>(err, stats)</code> where <code>stats</code> is a <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> 2841object. <code>lstat()</code> is identical to <code>stat()</code>, except that if <code>path</code> is a symbolic 2842link, then the link itself is stat-ed, not the file that it refers to.</p> 2843<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a> documentation for more details.</p> 2844<h4><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></h4> 2845<div class="api_metadata"> 2846<details class="changelog"><summary>History</summary> 2847<table> 2848<tbody><tr><th>Version</th><th>Changes</th></tr> 2849<tr><td>v13.11.0, v12.17.0</td> 2850<td><p>In <code>recursive</code> mode, the callback now receives the first created path as an argument.</p></td></tr> 2851<tr><td>v10.12.0</td> 2852<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> 2853<tr><td>v10.0.0</td> 2854<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> 2855<tr><td>v7.6.0</td> 2856<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2857<tr><td>v7.0.0</td> 2858<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> 2859<tr><td>v0.1.8</td> 2860<td><p><span>Added in: v0.1.8</span></p></td></tr> 2861</tbody></table> 2862</details> 2863</div> 2864<ul> 2865<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> 2866<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> 2867<ul> 2868<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> 2869<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> 2870</ul> 2871</li> 2872<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2873<ul> 2874<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2875</ul> 2876</li> 2877</ul> 2878<p>Asynchronously creates a directory.</p> 2879<p>The callback is given a possible exception and, if <code>recursive</code> is <code>true</code>, the 2880first directory path created, <code>(err, [path])</code>. 2881<code>path</code> can still be <code>undefined</code> when <code>recursive</code> is <code>true</code>, if no directory was 2882created.</p> 2883<p>The optional <code>options</code> argument can be an integer specifying <code>mode</code> (permission 2884and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code> 2885property indicating whether parent directories should be created. Calling 2886<code>fs.mkdir()</code> when <code>path</code> is a directory that exists results in an error only 2887when <code>recursive</code> is false.</p> 2888<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { mkdir } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2889 2890<span class="hljs-comment">// Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist.</span> 2891<span class="hljs-title function_">mkdir</span>(<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> { 2892 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2893});</code></pre> 2894<p>On Windows, using <code>fs.mkdir()</code> on the root directory even with recursion will 2895result in an error:</p> 2896<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { mkdir } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2897 2898<span class="hljs-title function_">mkdir</span>(<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> { 2899 <span class="hljs-comment">// => [Error: EPERM: operation not permitted, mkdir 'C:\']</span> 2900});</code></pre> 2901<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"><code>mkdir(2)</code></a> documentation for more details.</p> 2902<h4><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></h4> 2903<div class="api_metadata"> 2904<details class="changelog"><summary>History</summary> 2905<table> 2906<tbody><tr><th>Version</th><th>Changes</th></tr> 2907<tr><td>v14.18.0</td> 2908<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 2909<tr><td>v10.0.0</td> 2910<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> 2911<tr><td>v7.0.0</td> 2912<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> 2913<tr><td>v6.2.1</td> 2914<td><p>The <code>callback</code> parameter is optional now.</p></td></tr> 2915<tr><td>v5.10.0</td> 2916<td><p><span>Added in: v5.10.0</span></p></td></tr> 2917</tbody></table> 2918</details> 2919</div> 2920<ul> 2921<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 2922<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> 2923<ul> 2924<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> 2925</ul> 2926</li> 2927<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2928<ul> 2929<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2930<li><code>directory</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 2931</ul> 2932</li> 2933</ul> 2934<p>Creates a unique temporary directory.</p> 2935<p>Generates six random characters to be appended behind a required 2936<code>prefix</code> to create a unique temporary directory. Due to platform 2937inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some platforms, 2938notably the BSDs, can return more than six random characters, and replace 2939trailing <code>X</code> characters in <code>prefix</code> with random characters.</p> 2940<p>The created directory path is passed as a string to the callback's second 2941parameter.</p> 2942<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 2943object with an <code>encoding</code> property specifying the character encoding to use.</p> 2944<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { mkdtemp } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2945 2946<span class="hljs-title function_">mkdtemp</span>(path.<span class="hljs-title function_">join</span>(os.<span class="hljs-title function_">tmpdir</span>(), <span class="hljs-string">'foo-'</span>), <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> { 2947 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2948 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2949 <span class="hljs-comment">// Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2</span> 2950});</code></pre> 2951<p>The <code>fs.mkdtemp()</code> method will append the six randomly selected characters 2952directly to the <code>prefix</code> string. For instance, given a directory <code>/tmp</code>, if the 2953intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the <code>prefix</code> 2954must end with a trailing platform-specific path separator 2955(<code>require('path').sep</code>).</p> 2956<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { tmpdir } <span class="hljs-keyword">from</span> <span class="hljs-string">'os'</span>; 2957<span class="hljs-keyword">import</span> { mkdtemp } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2958 2959<span class="hljs-comment">// The parent directory for the new temporary directory</span> 2960<span class="hljs-keyword">const</span> tmpDir = <span class="hljs-title function_">tmpdir</span>(); 2961 2962<span class="hljs-comment">// This method is *INCORRECT*:</span> 2963<span class="hljs-title function_">mkdtemp</span>(tmpDir, <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> { 2964 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2965 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2966 <span class="hljs-comment">// Will print something similar to `/tmpabc123`.</span> 2967 <span class="hljs-comment">// A new temporary directory is created at the file system root</span> 2968 <span class="hljs-comment">// rather than *within* the /tmp directory.</span> 2969}); 2970 2971<span class="hljs-comment">// This method is *CORRECT*:</span> 2972<span class="hljs-keyword">import</span> { sep } <span class="hljs-keyword">from</span> <span class="hljs-string">'path'</span>; 2973<span class="hljs-title function_">mkdtemp</span>(<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> { 2974 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2975 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2976 <span class="hljs-comment">// Will print something similar to `/tmp/abc123`.</span> 2977 <span class="hljs-comment">// A new temporary directory is created within</span> 2978 <span class="hljs-comment">// the /tmp directory.</span> 2979});</code></pre> 2980<h4><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></h4> 2981<div class="api_metadata"> 2982<details class="changelog"><summary>History</summary> 2983<table> 2984<tbody><tr><th>Version</th><th>Changes</th></tr> 2985<tr><td>v11.1.0</td> 2986<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 2987<tr><td>v9.9.0</td> 2988<td><p>The <code>as</code> and <code>as+</code> flags are supported now.</p></td></tr> 2989<tr><td>v7.6.0</td> 2990<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2991<tr><td>v0.0.2</td> 2992<td><p><span>Added in: v0.0.2</span></p></td></tr> 2993</tbody></table> 2994</details> 2995</div> 2996<ul> 2997<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> 2998<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>. 2999<strong>Default:</strong> <code>'r'</code>.</li> 3000<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> 3001<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3002<ul> 3003<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3004<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3005</ul> 3006</li> 3007</ul> 3008<p>Asynchronous file open. See the POSIX <a href="http://man7.org/linux/man-pages/man2/open.2.html"><code>open(2)</code></a> documentation for more details.</p> 3009<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the file was 3010created. On Windows, only the write permission can be manipulated; see 3011<a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p> 3012<p>The callback gets two arguments <code>(err, fd)</code>.</p> 3013<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented 3014by <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 3015a colon, Node.js will open a file system stream, as described by 3016<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p> 3017<p>Functions based on <code>fs.open()</code> exhibit this behavior as well: 3018<code>fs.writeFile()</code>, <code>fs.readFile()</code>, etc.</p> 3019<h4><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></h4> 3020<div class="api_metadata"> 3021<details class="changelog"><summary>History</summary> 3022<table> 3023<tbody><tr><th>Version</th><th>Changes</th></tr> 3024<tr><td>v13.1.0, v12.16.0</td> 3025<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 3026<tr><td>v12.12.0</td> 3027<td><p><span>Added in: v12.12.0</span></p></td></tr> 3028</tbody></table> 3029</details> 3030</div> 3031<ul> 3032<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> 3033<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3034<ul> 3035<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> 3036<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 3037internally when reading from the directory. Higher values lead to better 3038performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 3039</ul> 3040</li> 3041<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3042<ul> 3043<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3044<li><code>dir</code> <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li> 3045</ul> 3046</li> 3047</ul> 3048<p>Asynchronously open a directory. See the POSIX <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a> documentation for 3049more details.</p> 3050<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 3051and cleaning up the directory.</p> 3052<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 3053directory and subsequent read operations.</p> 3054<h4><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></h4> 3055<div class="api_metadata"> 3056<details class="changelog"><summary>History</summary> 3057<table> 3058<tbody><tr><th>Version</th><th>Changes</th></tr> 3059<tr><td>v10.10.0</td> 3060<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code>, or a <code>DataView</code>.</p></td></tr> 3061<tr><td>v7.4.0</td> 3062<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 3063<tr><td>v6.0.0</td> 3064<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr> 3065<tr><td>v0.0.2</td> 3066<td><p><span>Added in: v0.0.2</span></p></td></tr> 3067</tbody></table> 3068</details> 3069</div> 3070<ul> 3071<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3072<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> The buffer that the data will be 3073written to. <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li> 3074<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The position in <code>buffer</code> to write the data to. <strong>Default:</strong> 3075<code>0</code></li> 3076<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The number of bytes to read. <strong>Default:</strong> 3077<code>buffer.byteLength</code></li> 3078<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a> Specifies where to begin reading from in the 3079file. If <code>position</code> is <code>null</code> or <code>-1 </code>, data will be read from the current 3080file position, and the file position will be updated. If <code>position</code> is an 3081integer, the file position will be unchanged.</li> 3082<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3083<ul> 3084<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3085<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3086<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li> 3087</ul> 3088</li> 3089</ul> 3090<p>Read data from the file specified by <code>fd</code>.</p> 3091<p>The callback is given the three arguments, <code>(err, bytesRead, buffer)</code>.</p> 3092<p>If the file is not modified concurrently, the end-of-file is reached when the 3093number of bytes read is zero.</p> 3094<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 3095a promise for an <code>Object</code> with <code>bytesRead</code> and <code>buffer</code> properties.</p> 3096<h4><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></h4> 3097<div class="api_metadata"> 3098<details class="changelog"><summary>History</summary> 3099<table> 3100<tbody><tr><th>Version</th><th>Changes</th></tr> 3101<tr><td>v13.11.0, v12.17.0</td> 3102<td><p><span>Added in: v13.11.0, v12.17.0</span></p></td></tr> 3103<tr><td>v13.11.0, v12.17.0</td> 3104<td><p>Options object can be passed in to make Buffer, offset, length and position optional.</p></td></tr> 3105</tbody></table> 3106</details> 3107</div> 3108<ul> 3109<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3110<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3111<ul> 3112<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> 3113<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> 3114<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.byteLength</code></li> 3115<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a> <strong>Default:</strong> <code>null</code></li> 3116</ul> 3117</li> 3118<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3119<ul> 3120<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3121<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3122<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li> 3123</ul> 3124</li> 3125</ul> 3126<p>Similar to the <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a> function, this version takes an optional 3127<code>options</code> object. If no <code>options</code> object is specified, it will default with the 3128above values.</p> 3129<h4><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></h4> 3130<div class="api_metadata"> 3131<details class="changelog"><summary>History</summary> 3132<table> 3133<tbody><tr><th>Version</th><th>Changes</th></tr> 3134<tr><td>v10.10.0</td> 3135<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 3136<tr><td>v10.0.0</td> 3137<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> 3138<tr><td>v7.6.0</td> 3139<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3140<tr><td>v7.0.0</td> 3141<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> 3142<tr><td>v6.0.0</td> 3143<td><p>The <code>options</code> parameter was added.</p></td></tr> 3144<tr><td>v0.1.8</td> 3145<td><p><span>Added in: v0.1.8</span></p></td></tr> 3146</tbody></table> 3147</details> 3148</div> 3149<ul> 3150<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> 3151<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> 3152<ul> 3153<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> 3154<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> 3155</ul> 3156</li> 3157<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3158<ul> 3159<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3160<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> 3161</ul> 3162</li> 3163</ul> 3164<p>Reads the contents of a directory. The callback gets two arguments <code>(err, files)</code> 3165where <code>files</code> is an array of the names of the files in the directory excluding 3166<code>'.'</code> and <code>'..'</code>.</p> 3167<p>See the POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more details.</p> 3168<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3169object with an <code>encoding</code> property specifying the character encoding to use for 3170the filenames passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3171the filenames returned will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 3172<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the <code>files</code> array will contain 3173<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 3174<h4><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></h4> 3175<div class="api_metadata"> 3176<details class="changelog"><summary>History</summary> 3177<table> 3178<tbody><tr><th>Version</th><th>Changes</th></tr> 3179<tr><td>v14.17.0</td> 3180<td><p>The options argument may include an AbortSignal to abort an ongoing readFile request.</p></td></tr> 3181<tr><td>v10.0.0</td> 3182<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> 3183<tr><td>v7.6.0</td> 3184<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3185<tr><td>v7.0.0</td> 3186<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> 3187<tr><td>v5.1.0</td> 3188<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> 3189<tr><td>v5.0.0</td> 3190<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr> 3191<tr><td>v0.1.29</td> 3192<td><p><span>Added in: v0.1.29</span></p></td></tr> 3193</tbody></table> 3194</details> 3195</div> 3196<ul> 3197<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> 3198<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> 3199<ul> 3200<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> 3201<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> 3202<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 3203</ul> 3204</li> 3205<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3206<ul> 3207<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3208<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> 3209</ul> 3210</li> 3211</ul> 3212<p>Asynchronously reads the entire contents of a file.</p> 3213<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3214 3215<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> { 3216 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3217 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(data); 3218});</code></pre> 3219<p>The callback is passed two arguments <code>(err, data)</code>, where <code>data</code> is the 3220contents of the file.</p> 3221<p>If no encoding is specified, then the raw buffer is returned.</p> 3222<p>If <code>options</code> is a string, then it specifies the encoding:</p> 3223<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3224 3225<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre> 3226<p>When the path is a directory, the behavior of <code>fs.readFile()</code> and 3227<a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync()</code></a> is platform-specific. On macOS, Linux, and Windows, an 3228error will be returned. On FreeBSD, a representation of the directory's contents 3229will be returned.</p> 3230<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3231 3232<span class="hljs-comment">// macOS, Linux, and Windows</span> 3233<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'<directory>'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> { 3234 <span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span> 3235}); 3236 3237<span class="hljs-comment">// FreeBSD</span> 3238<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'<directory>'</span>, <span class="hljs-function">(<span class="hljs-params">err, data</span>) =></span> { 3239 <span class="hljs-comment">// => null, <data></span> 3240});</code></pre> 3241<p>It is possible to abort an ongoing request using an <code>AbortSignal</code>. If a 3242request is aborted the callback is called with an <code>AbortError</code>:</p> 3243<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3244 3245<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 3246<span class="hljs-keyword">const</span> signal = controller.<span class="hljs-property">signal</span>; 3247<span class="hljs-title function_">readFile</span>(fileInfo[<span class="hljs-number">0</span>].<span class="hljs-property">name</span>, { signal }, <span class="hljs-function">(<span class="hljs-params">err, buf</span>) =></span> { 3248 <span class="hljs-comment">// ...</span> 3249}); 3250<span class="hljs-comment">// When you want to abort the request</span> 3251controller.<span class="hljs-title function_">abort</span>();</code></pre> 3252<p>The <code>fs.readFile()</code> function buffers the entire file. To minimize memory costs, 3253when possible prefer streaming via <code>fs.createReadStream()</code>.</p> 3254<p>Aborting an ongoing request does not abort individual operating 3255system requests but rather the internal buffering <code>fs.readFile</code> performs.</p> 3256<h5>File descriptors<span><a class="mark" href="#fs_file_descriptors" id="fs_file_descriptors">#</a></span></h5> 3257<ol> 3258<li>Any specified file descriptor has to support reading.</li> 3259<li>If a file descriptor is specified as the <code>path</code>, it will not be closed 3260automatically.</li> 3261<li>The reading will begin at the current position. For example, if the file 3262already had <code>'Hello World</code>' and six bytes are read with the file descriptor, 3263the call to <code>fs.readFile()</code> with the same file descriptor, would give 3264<code>'World'</code>, rather than <code>'Hello World'</code>.</li> 3265</ol> 3266<h5>Performance Considerations<span><a class="mark" href="#fs_performance_considerations" id="fs_performance_considerations">#</a></span></h5> 3267<p>The <code>fs.readFile()</code> method asynchronously reads the contents of a file into 3268memory one chunk at a time, allowing the event loop to turn between each chunk. 3269This allows the read operation to have less impact on other activity that may 3270be using the underlying libuv thread pool but means that it will take longer 3271to read a complete file into memory.</p> 3272<p>The additional read overhead can vary broadly on different systems and depends 3273on the type of file being read. If the file type is not a regular file (a pipe 3274for instance) and Node.js is unable to determine an actual file size, each read 3275operation will load on 64kb of data. For regular files, each read will process 3276512kb of data.</p> 3277<p>For applications that require as-fast-as-possible reading of file contents, it 3278is better to use <code>fs.read()</code> directly and for application code to manage 3279reading the full contents of the file itself.</p> 3280<p>The Node.js GitHub issue <a href="https://github.com/nodejs/node/issues/25741">#25741</a> provides more information and a detailed 3281analysis on the performance of <code>fs.readFile()</code> for multiple file sizes in 3282different Node.js versions.</p> 3283<h4><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></h4> 3284<div class="api_metadata"> 3285<details class="changelog"><summary>History</summary> 3286<table> 3287<tbody><tr><th>Version</th><th>Changes</th></tr> 3288<tr><td>v10.0.0</td> 3289<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> 3290<tr><td>v7.6.0</td> 3291<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3292<tr><td>v7.0.0</td> 3293<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> 3294<tr><td>v0.1.31</td> 3295<td><p><span>Added in: v0.1.31</span></p></td></tr> 3296</tbody></table> 3297</details> 3298</div> 3299<ul> 3300<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> 3301<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> 3302<ul> 3303<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> 3304</ul> 3305</li> 3306<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3307<ul> 3308<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3309<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> 3310</ul> 3311</li> 3312</ul> 3313<p>Reads the contents of the symbolic link referred to by <code>path</code>. The callback gets 3314two arguments <code>(err, linkString)</code>.</p> 3315<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a> documentation for more details.</p> 3316<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3317object with an <code>encoding</code> property specifying the character encoding to use for 3318the link path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3319the link path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3320<h4><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></h4> 3321<div class="api_metadata"> 3322<span>Added in: v13.13.0, v12.17.0</span> 3323</div> 3324<ul> 3325<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3326<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 3327<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3328<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3329<ul> 3330<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3331<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3332<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 3333</ul> 3334</li> 3335</ul> 3336<p>Read from a file specified by <code>fd</code> and write to an array of <code>ArrayBufferView</code>s 3337using <code>readv()</code>.</p> 3338<p><code>position</code> is the offset from the beginning of the file from where data 3339should be read. If <code>typeof position !== 'number'</code>, the data will be read 3340from the current position.</p> 3341<p>The callback will be given three arguments: <code>err</code>, <code>bytesRead</code>, and 3342<code>buffers</code>. <code>bytesRead</code> is how many bytes were read from the file.</p> 3343<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 3344a promise for an <code>Object</code> with <code>bytesRead</code> and <code>buffers</code> properties.</p> 3345<h4><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></h4> 3346<div class="api_metadata"> 3347<details class="changelog"><summary>History</summary> 3348<table> 3349<tbody><tr><th>Version</th><th>Changes</th></tr> 3350<tr><td>v10.0.0</td> 3351<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> 3352<tr><td>v8.0.0</td> 3353<td><p>Pipe/Socket resolve support was added.</p></td></tr> 3354<tr><td>v7.6.0</td> 3355<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3356<tr><td>v7.0.0</td> 3357<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> 3358<tr><td>v6.4.0</td> 3359<td><p>Calling <code>realpath</code> now works again for various edge cases on Windows.</p></td></tr> 3360<tr><td>v6.0.0</td> 3361<td><p>The <code>cache</code> parameter was removed.</p></td></tr> 3362<tr><td>v0.1.31</td> 3363<td><p><span>Added in: v0.1.31</span></p></td></tr> 3364</tbody></table> 3365</details> 3366</div> 3367<ul> 3368<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> 3369<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> 3370<ul> 3371<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> 3372</ul> 3373</li> 3374<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3375<ul> 3376<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3377<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> 3378</ul> 3379</li> 3380</ul> 3381<p>Asynchronously computes the canonical pathname by resolving <code>.</code>, <code>..</code> and 3382symbolic links.</p> 3383<p>A canonical pathname is not necessarily unique. Hard links and bind mounts can 3384expose a file system entity through many pathnames.</p> 3385<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> 3386<ol> 3387<li> 3388<p>No case conversion is performed on case-insensitive file systems.</p> 3389</li> 3390<li> 3391<p>The maximum number of symbolic links is platform-independent and generally 3392(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> 3393</li> 3394</ol> 3395<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>. May use <code>process.cwd</code> 3396to resolve relative paths.</p> 3397<p>Only paths that can be converted to UTF8 strings are supported.</p> 3398<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3399object with an <code>encoding</code> property specifying the character encoding to use for 3400the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3401the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3402<p>If <code>path</code> resolves to a socket or a pipe, the function will return a system 3403dependent name for that object.</p> 3404<h4><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></h4> 3405<div class="api_metadata"> 3406<span>Added in: v9.2.0</span> 3407</div> 3408<ul> 3409<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> 3410<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> 3411<ul> 3412<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> 3413</ul> 3414</li> 3415<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3416<ul> 3417<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3418<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> 3419</ul> 3420</li> 3421</ul> 3422<p>Asynchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p> 3423<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>.</p> 3424<p>Only paths that can be converted to UTF8 strings are supported.</p> 3425<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3426object with an <code>encoding</code> property specifying the character encoding to use for 3427the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3428the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3429<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 3430be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 3431this restriction.</p> 3432<h4><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></h4> 3433<div class="api_metadata"> 3434<details class="changelog"><summary>History</summary> 3435<table> 3436<tbody><tr><th>Version</th><th>Changes</th></tr> 3437<tr><td>v10.0.0</td> 3438<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> 3439<tr><td>v7.6.0</td> 3440<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> 3441<tr><td>v7.0.0</td> 3442<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> 3443<tr><td>v0.0.2</td> 3444<td><p><span>Added in: v0.0.2</span></p></td></tr> 3445</tbody></table> 3446</details> 3447</div> 3448<ul> 3449<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> 3450<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> 3451<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3452<ul> 3453<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3454</ul> 3455</li> 3456</ul> 3457<p>Asynchronously rename file at <code>oldPath</code> to the pathname provided 3458as <code>newPath</code>. In the case that <code>newPath</code> already exists, it will 3459be overwritten. If there is a directory at <code>newPath</code>, an error will 3460be raised instead. No arguments other than a possible exception are 3461given to the completion callback.</p> 3462<p>See also: <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a>.</p> 3463<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { rename } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3464 3465<span class="hljs-title function_">rename</span>(<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> { 3466 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3467 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Rename complete!'</span>); 3468});</code></pre> 3469<h4><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></h4> 3470<div class="api_metadata"> 3471<details class="changelog"><summary>History</summary> 3472<table> 3473<tbody><tr><th>Version</th><th>Changes</th></tr> 3474<tr><td>v14.14.0</td> 3475<td><p>The <code>recursive</code> option is deprecated, use <code>fs.rm</code> instead.</p></td></tr> 3476<tr><td>v13.3.0, v12.16.0</td> 3477<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> 3478<tr><td>v12.10.0</td> 3479<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 3480<tr><td>v10.0.0</td> 3481<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> 3482<tr><td>v7.6.0</td> 3483<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3484<tr><td>v7.0.0</td> 3485<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> 3486<tr><td>v0.0.2</td> 3487<td><p><span>Added in: v0.0.2</span></p></td></tr> 3488</tbody></table> 3489</details> 3490</div> 3491<ul> 3492<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> 3493<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3494<ul> 3495<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 3496<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 3497backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 3498represents the number of retries. This option is ignored if the <code>recursive</code> 3499option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 3500<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 3501recursive mode, errors are not reported if <code>path</code> does not exist, and 3502operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 3503<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 3504retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 3505<strong>Default:</strong> <code>100</code>.</li> 3506</ul> 3507</li> 3508<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3509<ul> 3510<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3511</ul> 3512</li> 3513</ul> 3514<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 3515to the completion callback.</p> 3516<p>Using <code>fs.rmdir()</code> on a file (not a directory) results in an <code>ENOENT</code> error on 3517Windows and an <code>ENOTDIR</code> error on POSIX.</p> 3518<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 3519<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 3520that represent files will be deleted. The permissive behavior of the 3521<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 3522the future.</p> 3523<h4><code>fs.rm(path[, options], callback)</code><span><a class="mark" href="#fs_fs_rm_path_options_callback" id="fs_fs_rm_path_options_callback">#</a></span></h4> 3524<div class="api_metadata"> 3525<span>Added in: v14.14.0</span> 3526</div> 3527<ul> 3528<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> 3529<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3530<ul> 3531<li><code>force</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When <code>true</code>, exceptions will be ignored if <code>path</code> does 3532not exist. <strong>Default:</strong> <code>false</code>.</li> 3533<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 3534<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 3535backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 3536represents the number of retries. This option is ignored if the <code>recursive</code> 3537option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 3538<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 removal. In 3539recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 3540<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 3541retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 3542<strong>Default:</strong> <code>100</code>.</li> 3543</ul> 3544</li> 3545<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3546<ul> 3547<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3548</ul> 3549</li> 3550</ul> 3551<p>Asynchronously removes files and directories (modeled on the standard POSIX <code>rm</code> 3552utility). No arguments other than a possible exception are given to the 3553completion callback.</p> 3554<h4><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></h4> 3555<div class="api_metadata"> 3556<details class="changelog"><summary>History</summary> 3557<table> 3558<tbody><tr><th>Version</th><th>Changes</th></tr> 3559<tr><td>v10.5.0</td> 3560<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 3561<tr><td>v10.0.0</td> 3562<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> 3563<tr><td>v7.6.0</td> 3564<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3565<tr><td>v7.0.0</td> 3566<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> 3567<tr><td>v0.0.2</td> 3568<td><p><span>Added in: v0.0.2</span></p></td></tr> 3569</tbody></table> 3570</details> 3571</div> 3572<ul> 3573<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> 3574<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3575<ul> 3576<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 3577<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 3578</ul> 3579</li> 3580<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3581<ul> 3582<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3583<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3584</ul> 3585</li> 3586</ul> 3587<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 3588<code>stats</code> is an <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object.</p> 3589<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> 3590<p>Using <code>fs.stat()</code> to check for the existence of a file before calling 3591<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended. 3592Instead, user code should open/read/write the file directly and handle the 3593error raised if the file is not available.</p> 3594<p>To check if a file exists without manipulating it afterwards, <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a> 3595is recommended.</p> 3596<p>For example, given the following directory structure:</p> 3597<pre><code class="language-text">- txtDir 3598-- file.txt 3599- app.js</code></pre> 3600<p>The next program will check for the stats of the given paths:</p> 3601<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3602 3603<span class="hljs-keyword">const</span> pathsToCheck = [<span class="hljs-string">'./txtDir'</span>, <span class="hljs-string">'./txtDir/file.txt'</span>]; 3604 3605<span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i < pathsToCheck.<span class="hljs-property">length</span>; i++) { 3606 <span class="hljs-title function_">stat</span>(pathsToCheck[i], <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> { 3607 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(stats.<span class="hljs-title function_">isDirectory</span>()); 3608 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(stats); 3609 }); 3610}</code></pre> 3611<p>The resulting output will resemble:</p> 3612<pre><code class="language-console">true 3613Stats { 3614 dev: 16777220, 3615 mode: 16877, 3616 nlink: 3, 3617 uid: 501, 3618 gid: 20, 3619 rdev: 0, 3620 blksize: 4096, 3621 ino: 14214262, 3622 size: 96, 3623 blocks: 0, 3624 atimeMs: 1561174653071.963, 3625 mtimeMs: 1561174614583.3518, 3626 ctimeMs: 1561174626623.5366, 3627 birthtimeMs: 1561174126937.2893, 3628 atime: 2019-06-22T03:37:33.072Z, 3629 mtime: 2019-06-22T03:36:54.583Z, 3630 ctime: 2019-06-22T03:37:06.624Z, 3631 birthtime: 2019-06-22T03:28:46.937Z 3632} 3633false 3634Stats { 3635 dev: 16777220, 3636 mode: 33188, 3637 nlink: 1, 3638 uid: 501, 3639 gid: 20, 3640 rdev: 0, 3641 blksize: 4096, 3642 ino: 14214074, 3643 size: 8, 3644 blocks: 8, 3645 atimeMs: 1561174616618.8555, 3646 mtimeMs: 1561174614584, 3647 ctimeMs: 1561174614583.8145, 3648 birthtimeMs: 1561174007710.7478, 3649 atime: 2019-06-22T03:36:56.619Z, 3650 mtime: 2019-06-22T03:36:54.584Z, 3651 ctime: 2019-06-22T03:36:54.584Z, 3652 birthtime: 2019-06-22T03:26:47.711Z 3653}</code></pre> 3654<h4><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></h4> 3655<div class="api_metadata"> 3656<details class="changelog"><summary>History</summary> 3657<table> 3658<tbody><tr><th>Version</th><th>Changes</th></tr> 3659<tr><td>v12.0.0</td> 3660<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> 3661<tr><td>v7.6.0</td> 3662<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> 3663<tr><td>v0.1.31</td> 3664<td><p><span>Added in: v0.1.31</span></p></td></tr> 3665</tbody></table> 3666</details> 3667</div> 3668<ul> 3669<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> 3670<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> 3671<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 3672<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3673<ul> 3674<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3675</ul> 3676</li> 3677</ul> 3678<p>Creates the link called <code>path</code> pointing to <code>target</code>. No arguments other than a 3679possible exception are given to the completion callback.</p> 3680<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/symlink.2.html"><code>symlink(2)</code></a> documentation for more details.</p> 3681<p>The <code>type</code> argument is only available on Windows and ignored on other platforms. 3682It can be set to <code>'dir'</code>, <code>'file'</code>, or <code>'junction'</code>. If the <code>type</code> argument is 3683not set, Node.js will autodetect <code>target</code> type and use <code>'file'</code> or <code>'dir'</code>. If 3684the <code>target</code> does not exist, <code>'file'</code> will be used. Windows junction points 3685require the destination path to be absolute. When using <code>'junction'</code>, the 3686<code>target</code> argument will automatically be normalized to absolute path.</p> 3687<p>Relative targets are relative to the link’s parent directory.</p> 3688<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { symlink } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3689 3690<span class="hljs-title function_">symlink</span>(<span class="hljs-string">'./mew'</span>, <span class="hljs-string">'./example/mewtwo'</span>, callback);</code></pre> 3691<p>The above example creates a symbolic link <code>mewtwo</code> in the <code>example</code> which points 3692to <code>mew</code> in the same directory:</p> 3693<pre><code class="language-bash">$ tree example/ 3694example/ 3695├── mew 3696└── mewtwo -> ./mew</code></pre> 3697<h4><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></h4> 3698<div class="api_metadata"> 3699<details class="changelog"><summary>History</summary> 3700<table> 3701<tbody><tr><th>Version</th><th>Changes</th></tr> 3702<tr><td>v10.0.0</td> 3703<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> 3704<tr><td>v7.0.0</td> 3705<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> 3706<tr><td>v0.8.6</td> 3707<td><p><span>Added in: v0.8.6</span></p></td></tr> 3708</tbody></table> 3709</details> 3710</div> 3711<ul> 3712<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> 3713<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> 3714<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3715<ul> 3716<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3717</ul> 3718</li> 3719</ul> 3720<p>Truncates the file. No arguments other than a possible exception are 3721given to the completion callback. A file descriptor can also be passed as the 3722first argument. In this case, <code>fs.ftruncate()</code> is called.</p> 3723 3724<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { truncate } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3725<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3726<span class="hljs-title function_">truncate</span>(<span class="hljs-string">'path/file.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 3727 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3728 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was truncated'</span>); 3729});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { truncate } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs'</span>); 3730<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3731<span class="hljs-title function_">truncate</span>(<span class="hljs-string">'path/file.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 3732 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3733 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was truncated'</span>); 3734});</code></pre> 3735<p>Passing a file descriptor is deprecated and may result in an error being thrown 3736in the future.</p> 3737<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/truncate.2.html"><code>truncate(2)</code></a> documentation for more details.</p> 3738<h4><code>fs.unlink(path, callback)</code><span><a class="mark" href="#fs_fs_unlink_path_callback" id="fs_fs_unlink_path_callback">#</a></span></h4> 3739<div class="api_metadata"> 3740<details class="changelog"><summary>History</summary> 3741<table> 3742<tbody><tr><th>Version</th><th>Changes</th></tr> 3743<tr><td>v10.0.0</td> 3744<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> 3745<tr><td>v7.6.0</td> 3746<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3747<tr><td>v7.0.0</td> 3748<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> 3749<tr><td>v0.0.2</td> 3750<td><p><span>Added in: v0.0.2</span></p></td></tr> 3751</tbody></table> 3752</details> 3753</div> 3754<ul> 3755<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> 3756<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3757<ul> 3758<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3759</ul> 3760</li> 3761</ul> 3762<p>Asynchronously removes a file or symbolic link. No arguments other than a 3763possible exception are given to the completion callback.</p> 3764<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { unlink } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3765<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3766<span class="hljs-title function_">unlink</span>(<span class="hljs-string">'path/file.txt'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 3767 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3768 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was deleted'</span>); 3769});</code></pre> 3770<p><code>fs.unlink()</code> will not work on a directory, empty or otherwise. To remove a 3771directory, use <a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir()</code></a>.</p> 3772<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a> documentation for more details.</p> 3773<h4><code>fs.unwatchFile(filename[, listener])</code><span><a class="mark" href="#fs_fs_unwatchfile_filename_listener" id="fs_fs_unwatchfile_filename_listener">#</a></span></h4> 3774<div class="api_metadata"> 3775<span>Added in: v0.1.31</span> 3776</div> 3777<ul> 3778<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> 3779<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 3780<code>fs.watchFile()</code></li> 3781</ul> 3782<p>Stop watching for changes on <code>filename</code>. If <code>listener</code> is specified, only that 3783particular listener is removed. Otherwise, <em>all</em> listeners are removed, 3784effectively stopping watching of <code>filename</code>.</p> 3785<p>Calling <code>fs.unwatchFile()</code> with a filename that is not being watched is a 3786no-op, not an error.</p> 3787<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile()</code> and 3788<code>fs.unwatchFile()</code>. <code>fs.watch()</code> should be used instead of <code>fs.watchFile()</code> 3789and <code>fs.unwatchFile()</code> when possible.</p> 3790<h4><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></h4> 3791<div class="api_metadata"> 3792<details class="changelog"><summary>History</summary> 3793<table> 3794<tbody><tr><th>Version</th><th>Changes</th></tr> 3795<tr><td>v10.0.0</td> 3796<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> 3797<tr><td>v8.0.0</td> 3798<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr> 3799<tr><td>v7.6.0</td> 3800<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3801<tr><td>v7.0.0</td> 3802<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> 3803<tr><td>v4.1.0</td> 3804<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 3805<tr><td>v0.4.2</td> 3806<td><p><span>Added in: v0.4.2</span></p></td></tr> 3807</tbody></table> 3808</details> 3809</div> 3810<ul> 3811<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> 3812<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> 3813<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> 3814<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3815<ul> 3816<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3817</ul> 3818</li> 3819</ul> 3820<p>Change the file system timestamps of the object referenced by <code>path</code>.</p> 3821<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p> 3822<ul> 3823<li>Values can be either numbers representing Unix epoch time in seconds, 3824<code>Date</code>s, or a numeric string like <code>'123456789.0'</code>.</li> 3825<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or 3826<code>-Infinity</code>, an <code>Error</code> will be thrown.</li> 3827</ul> 3828<h4><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></h4> 3829<div class="api_metadata"> 3830<details class="changelog"><summary>History</summary> 3831<table> 3832<tbody><tr><th>Version</th><th>Changes</th></tr> 3833<tr><td>v14.17.0</td> 3834<td><p>Added support for closing the watcher with an AbortSignal.</p></td></tr> 3835<tr><td>v7.6.0</td> 3836<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3837<tr><td>v7.0.0</td> 3838<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 3839<tr><td>v0.5.10</td> 3840<td><p><span>Added in: v0.5.10</span></p></td></tr> 3841</tbody></table> 3842</details> 3843</div> 3844<ul> 3845<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> 3846<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> 3847<ul> 3848<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 3849as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li> 3850<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 3851watched, or only the current directory. This applies when a directory is 3852specified, and only on supported platforms (See <a href="#fs_caveats">caveats</a>). <strong>Default:</strong> 3853<code>false</code>.</li> 3854<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 3855filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li> 3856<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows closing the watcher with an AbortSignal.</li> 3857</ul> 3858</li> 3859<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> 3860<ul> 3861<li><code>eventType</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 3862<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> 3863</ul> 3864</li> 3865<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 3866</ul> 3867<p>Watch for changes on <code>filename</code>, where <code>filename</code> is either a file or a 3868directory.</p> 3869<p>The second argument is optional. If <code>options</code> is provided as a string, it 3870specifies the <code>encoding</code>. Otherwise <code>options</code> should be passed as an object.</p> 3871<p>The listener callback gets two arguments <code>(eventType, filename)</code>. <code>eventType</code> 3872is either <code>'rename'</code> or <code>'change'</code>, and <code>filename</code> is the name of the file 3873which triggered the event.</p> 3874<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or 3875disappears in the directory.</p> 3876<p>The listener callback is attached to the <code>'change'</code> event fired by 3877<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>, but it is not the same thing as the <code>'change'</code> value of 3878<code>eventType</code>.</p> 3879<p>If a <code>signal</code> is passed, aborting the corresponding AbortController will close 3880the returned <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>.</p> 3881<h5>Caveats<span><a class="mark" href="#fs_caveats" id="fs_caveats">#</a></span></h5> 3882 3883<p>The <code>fs.watch</code> API is not 100% consistent across platforms, and is 3884unavailable in some situations.</p> 3885<p>The recursive option is only supported on macOS and Windows. 3886An <code>ERR_FEATURE_UNAVAILABLE_ON_PLATFORM</code> exception will be thrown 3887when the option is used on a platform that does not support it.</p> 3888<p>On Windows, no events will be emitted if the watched directory is moved or 3889renamed. An <code>EPERM</code> error is reported when the watched directory is deleted.</p> 3890<h6>Availability<span><a class="mark" href="#fs_availability" id="fs_availability">#</a></span></h6> 3891 3892<p>This feature depends on the underlying operating system providing a way 3893to be notified of filesystem changes.</p> 3894<ul> 3895<li>On Linux systems, this uses <a href="https://man7.org/linux/man-pages/man7/inotify.7.html"><code>inotify(7)</code></a>.</li> 3896<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> 3897<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 3898directories.</li> 3899<li>On SunOS systems (including Solaris and SmartOS), this uses <a href="https://illumos.org/man/port_create"><code>event ports</code></a>.</li> 3900<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> 3901<li>On AIX systems, this feature depends on <a href="https://developer.ibm.com/articles/au-aix_event_infrastructure/"><code>AHAFS</code></a>, which must be enabled.</li> 3902<li>On IBM i systems, this feature is not supported.</li> 3903</ul> 3904<p>If the underlying functionality is not available for some reason, then 3905<code>fs.watch()</code> will not be able to function and may throw an exception. 3906For example, watching files or directories can be unreliable, and in some 3907cases impossible, on network file systems (NFS, SMB, etc) or host file systems 3908when using virtualization software such as Vagrant or Docker.</p> 3909<p>It is still possible to use <code>fs.watchFile()</code>, which uses stat polling, but 3910this method is slower and less reliable.</p> 3911<h6>Inodes<span><a class="mark" href="#fs_inodes" id="fs_inodes">#</a></span></h6> 3912 3913<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 3914watches the inode. If the watched path is deleted and recreated, it is assigned 3915a new inode. The watch will emit an event for the delete but will continue 3916watching the <em>original</em> inode. Events for the new inode will not be emitted. 3917This is expected behavior.</p> 3918<p>AIX files retain the same inode for the lifetime of a file. Saving and closing a 3919watched file on AIX will result in two notifications (one for adding new 3920content, and one for truncation).</p> 3921<h6>Filename argument<span><a class="mark" href="#fs_filename_argument" id="fs_filename_argument">#</a></span></h6> 3922 3923<p>Providing <code>filename</code> argument in the callback is only supported on Linux, 3924macOS, Windows, and AIX. Even on supported platforms, <code>filename</code> is not always 3925guaranteed to be provided. Therefore, don't assume that <code>filename</code> argument is 3926always provided in the callback, and have some fallback logic if it is <code>null</code>.</p> 3927<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { watch } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3928<span class="hljs-title function_">watch</span>(<span class="hljs-string">'somedir'</span>, <span class="hljs-function">(<span class="hljs-params">eventType, filename</span>) =></span> { 3929 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`event type is: <span class="hljs-subst">${eventType}</span>`</span>); 3930 <span class="hljs-keyword">if</span> (filename) { 3931 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`filename provided: <span class="hljs-subst">${filename}</span>`</span>); 3932 } <span class="hljs-keyword">else</span> { 3933 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'filename not provided'</span>); 3934 } 3935});</code></pre> 3936<h4><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></h4> 3937<div class="api_metadata"> 3938<details class="changelog"><summary>History</summary> 3939<table> 3940<tbody><tr><th>Version</th><th>Changes</th></tr> 3941<tr><td>v10.5.0</td> 3942<td><p>The <code>bigint</code> option is now supported.</p></td></tr> 3943<tr><td>v7.6.0</td> 3944<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3945<tr><td>v0.1.31</td> 3946<td><p><span>Added in: v0.1.31</span></p></td></tr> 3947</tbody></table> 3948</details> 3949</div> 3950<ul> 3951<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> 3952<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3953<ul> 3954<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> 3955<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> 3956<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> 3957</ul> 3958</li> 3959<li><code>listener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3960<ul> 3961<li><code>current</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3962<li><code>previous</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3963</ul> 3964</li> 3965<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 3966</ul> 3967<p>Watch for changes on <code>filename</code>. The callback <code>listener</code> will be called each 3968time the file is accessed.</p> 3969<p>The <code>options</code> argument may be omitted. If provided, it should be an object. The 3970<code>options</code> object may contain a boolean named <code>persistent</code> that indicates 3971whether the process should continue to run as long as files are being watched. 3972The <code>options</code> object may specify an <code>interval</code> property indicating how often the 3973target should be polled in milliseconds.</p> 3974<p>The <code>listener</code> gets two arguments the current stat object and the previous 3975stat object:</p> 3976<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { watchFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 3977 3978<span class="hljs-title function_">watchFile</span>(<span class="hljs-string">'message.text'</span>, <span class="hljs-function">(<span class="hljs-params">curr, prev</span>) =></span> { 3979 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`the current mtime is: <span class="hljs-subst">${curr.mtime}</span>`</span>); 3980 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`the previous mtime was: <span class="hljs-subst">${prev.mtime}</span>`</span>); 3981});</code></pre> 3982<p>These stat objects are instances of <code>fs.Stat</code>. If the <code>bigint</code> option is <code>true</code>, 3983the numeric values in these objects are specified as <code>BigInt</code>s.</p> 3984<p>To be notified when the file was modified, not just accessed, it is necessary 3985to compare <code>curr.mtime</code> and <code>prev.mtime</code>.</p> 3986<p>When an <code>fs.watchFile</code> operation results in an <code>ENOENT</code> error, it 3987will invoke the listener once, with all the fields zeroed (or, for dates, the 3988Unix Epoch). If the file is created later on, the listener will be called 3989again, with the latest stat objects. This is a change in functionality since 3990v0.10.</p> 3991<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile</code> and 3992<code>fs.unwatchFile</code>. <code>fs.watch</code> should be used instead of <code>fs.watchFile</code> and 3993<code>fs.unwatchFile</code> when possible.</p> 3994<p>When a file being watched by <code>fs.watchFile()</code> disappears and reappears, 3995then the contents of <code>previous</code> in the second callback event (the file's 3996reappearance) will be the same as the contents of <code>previous</code> in the first 3997callback event (its disappearance).</p> 3998<p>This happens when:</p> 3999<ul> 4000<li>the file is deleted, followed by a restore</li> 4001<li>the file is renamed and then renamed a second time back to its original name</li> 4002</ul> 4003<h4><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></h4> 4004<div class="api_metadata"> 4005<details class="changelog"><summary>History</summary> 4006<table> 4007<tbody><tr><th>Version</th><th>Changes</th></tr> 4008<tr><td>v14.12.0</td> 4009<td><p>The <code>buffer</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4010<tr><td>v14.0.0</td> 4011<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4012<tr><td>v10.10.0</td> 4013<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4014<tr><td>v10.0.0</td> 4015<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> 4016<tr><td>v7.4.0</td> 4017<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4018<tr><td>v7.2.0</td> 4019<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 4020<tr><td>v7.0.0</td> 4021<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> 4022<tr><td>v0.0.2</td> 4023<td><p><span>Added in: v0.0.2</span></p></td></tr> 4024</tbody></table> 4025</details> 4026</div> 4027<ul> 4028<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4029<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> | <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></li> 4030<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4031<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4032<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4033<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4034<ul> 4035<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4036<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4037<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> 4038</ul> 4039</li> 4040</ul> 4041<p>Write <code>buffer</code> to the file specified by <code>fd</code>. If <code>buffer</code> is a normal object, it 4042must have an own <code>toString</code> function property.</p> 4043<p><code>offset</code> determines the part of the buffer to be written, and <code>length</code> is 4044an integer specifying the number of bytes to write.</p> 4045<p><code>position</code> refers to the offset from the beginning of the file where this data 4046should be written. If <code>typeof position !== 'number'</code>, the data will be written 4047at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4048<p>The callback will be given three arguments <code>(err, bytesWritten, buffer)</code> where 4049<code>bytesWritten</code> specifies how many <em>bytes</em> were written from <code>buffer</code>.</p> 4050<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 4051a promise for an <code>Object</code> with <code>bytesWritten</code> and <code>buffer</code> properties.</p> 4052<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4053for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4054recommended.</p> 4055<p>On Linux, positional writes don't work when the file is opened in append mode. 4056The kernel ignores the position argument and always appends the data to 4057the end of the file.</p> 4058<h4><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></h4> 4059<div class="api_metadata"> 4060<details class="changelog"><summary>History</summary> 4061<table> 4062<tbody><tr><th>Version</th><th>Changes</th></tr> 4063<tr><td>v14.12.0</td> 4064<td><p>The <code>string</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4065<tr><td>v14.0.0</td> 4066<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4067<tr><td>v10.0.0</td> 4068<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> 4069<tr><td>v7.2.0</td> 4070<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 4071<tr><td>v7.0.0</td> 4072<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> 4073<tr><td>v0.11.5</td> 4074<td><p><span>Added in: v0.11.5</span></p></td></tr> 4075</tbody></table> 4076</details> 4077</div> 4078<ul> 4079<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4080<li><code>string</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></li> 4081<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4082<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> 4083<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4084<ul> 4085<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4086<li><code>written</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4087<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4088</ul> 4089</li> 4090</ul> 4091<p>Write <code>string</code> to the file specified by <code>fd</code>. If <code>string</code> is not a string, or an 4092object with an own <code>toString</code> function property, then an exception is thrown.</p> 4093<p><code>position</code> refers to the offset from the beginning of the file where this data 4094should be written. If <code>typeof position !== 'number'</code> the data will be written at 4095the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4096<p><code>encoding</code> is the expected string encoding.</p> 4097<p>The callback will receive the arguments <code>(err, written, string)</code> where <code>written</code> 4098specifies how many <em>bytes</em> the passed string required to be written. Bytes 4099written is not necessarily the same as string characters written. See 4100<a href="buffer.html#buffer_static_method_buffer_bytelength_string_encoding"><code>Buffer.byteLength</code></a>.</p> 4101<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4102for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4103recommended.</p> 4104<p>On Linux, positional writes don't work when the file is opened in append mode. 4105The kernel ignores the position argument and always appends the data to 4106the end of the file.</p> 4107<p>On Windows, if the file descriptor is connected to the console (e.g. <code>fd == 1</code> 4108or <code>stdout</code>) a string containing non-ASCII characters will not be rendered 4109properly by default, regardless of the encoding used. 4110It is possible to configure the console to render UTF-8 properly by changing the 4111active codepage with the <code>chcp 65001</code> command. See the <a href="https://ss64.com/nt/chcp.html">chcp</a> docs for more 4112details.</p> 4113<h4><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></h4> 4114<div class="api_metadata"> 4115<details class="changelog"><summary>History</summary> 4116<table> 4117<tbody><tr><th>Version</th><th>Changes</th></tr> 4118<tr><td>v14.17.0</td> 4119<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 4120<tr><td>v14.12.0</td> 4121<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4122<tr><td>v14.0.0</td> 4123<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4124<tr><td>v10.10.0</td> 4125<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4126<tr><td>v10.0.0</td> 4127<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> 4128<tr><td>v7.4.0</td> 4129<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4130<tr><td>v7.0.0</td> 4131<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> 4132<tr><td>v5.0.0</td> 4133<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4134<tr><td>v0.1.29</td> 4135<td><p><span>Added in: v0.1.29</span></p></td></tr> 4136</tbody></table> 4137</details> 4138</div> 4139<ul> 4140<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> 4141<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> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 4142<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> 4143<ul> 4144<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> 4145<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> 4146<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> 4147<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 4148</ul> 4149</li> 4150<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4151<ul> 4152<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4153</ul> 4154</li> 4155</ul> 4156<p>When <code>file</code> is a filename, asynchronously writes data to the file, replacing the 4157file if it already exists. <code>data</code> can be a string or a buffer.</p> 4158<p>When <code>file</code> is a file descriptor, the behavior is similar to calling 4159<code>fs.write()</code> directly (which is recommended). See the notes below on using 4160a file descriptor.</p> 4161<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p> 4162<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 4163for more details.</p> 4164<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 4165function property.</p> 4166<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { writeFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4167 4168<span class="hljs-keyword">const</span> data = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Uint</span>8<span class="hljs-built_in">Array</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Hello Node.js'</span>)); 4169<span class="hljs-title function_">writeFile</span>(<span class="hljs-string">'message.txt'</span>, data, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 4170 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 4171 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The file has been saved!'</span>); 4172});</code></pre> 4173<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4174<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { writeFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4175 4176<span class="hljs-title function_">writeFile</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'Hello Node.js'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre> 4177<p>It is unsafe to use <code>fs.writeFile()</code> multiple times on the same file without 4178waiting for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4179recommended.</p> 4180<p>Similarly to <code>fs.readFile</code> - <code>fs.writeFile</code> is a convenience method that 4181performs multiple <code>write</code> calls internally to write the buffer passed to it. 4182For performance sensitive code consider using <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4183<p>It is possible to use an <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> to cancel an <code>fs.writeFile()</code>. 4184Cancelation is "best effort", and some amount of data is likely still 4185to be written.</p> 4186<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { writeFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4187 4188<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 4189<span class="hljs-keyword">const</span> { signal } = controller; 4190<span class="hljs-keyword">const</span> data = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Uint</span>8<span class="hljs-built_in">Array</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'Hello Node.js'</span>)); 4191<span class="hljs-title function_">writeFile</span>(<span class="hljs-string">'message.txt'</span>, data, { signal }, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 4192 <span class="hljs-comment">// When a request is aborted - the callback is called with an AbortError</span> 4193}); 4194<span class="hljs-comment">// When the request should be aborted</span> 4195controller.<span class="hljs-title function_">abort</span>();</code></pre> 4196<p>Aborting an ongoing request does not abort individual operating 4197system requests but rather the internal buffering <code>fs.writeFile</code> performs.</p> 4198<h5>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></h5> 4199<p>When <code>file</code> is a file descriptor, the behavior is almost identical to directly 4200calling <code>fs.write()</code> like:</p> 4201<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { write } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4202 4203<span class="hljs-title function_">write</span>(fd, <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(data, options.<span class="hljs-property">encoding</span>), callback);</code></pre> 4204<p>The difference from directly calling <code>fs.write()</code> is that under some unusual 4205conditions, <code>fs.write()</code> might write only part of the buffer and need to be 4206retried to write the remaining data, whereas <code>fs.writeFile()</code> retries until 4207the data is entirely written (or an error occurs).</p> 4208<p>The implications of this are a common source of confusion. In 4209the file descriptor case, the file is not replaced! The data is not necessarily 4210written to the beginning of the file, and the file's original data may remain 4211before and/or after the newly written data.</p> 4212<p>For example, if <code>fs.writeFile()</code> is called twice in a row, first to write the 4213string <code>'Hello'</code>, then to write the string <code>', World'</code>, the file would contain 4214<code>'Hello, World'</code>, and might contain some of the file's original data (depending 4215on the size of the original file, and the position of the file descriptor). If 4216a file name had been used instead of a descriptor, the file would be guaranteed 4217to contain only <code>', World'</code>.</p> 4218<h4><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></h4> 4219<div class="api_metadata"> 4220<span>Added in: v12.9.0</span> 4221</div> 4222<ul> 4223<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4224<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4225<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4226<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4227<ul> 4228<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4229<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4230<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4231</ul> 4232</li> 4233</ul> 4234<p>Write an array of <code>ArrayBufferView</code>s to the file specified by <code>fd</code> using 4235<code>writev()</code>.</p> 4236<p><code>position</code> is the offset from the beginning of the file where this data 4237should be written. If <code>typeof position !== 'number'</code>, the data will be written 4238at the current position.</p> 4239<p>The callback will be given three arguments: <code>err</code>, <code>bytesWritten</code>, and 4240<code>buffers</code>. <code>bytesWritten</code> is how many bytes were written from <code>buffers</code>.</p> 4241<p>If this method is <a href="util.html#util_util_promisify_original"><code>util.promisify()</code></a>ed, it returns a promise for an 4242<code>Object</code> with <code>bytesWritten</code> and <code>buffers</code> properties.</p> 4243<p>It is unsafe to use <code>fs.writev()</code> multiple times on the same file without 4244waiting for the callback. For this scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4245<p>On Linux, positional writes don't work when the file is opened in append mode. 4246The kernel ignores the position argument and always appends the data to 4247the end of the file.</p> 4248</section><section><h3>Synchronous API<span><a class="mark" href="#fs_synchronous_api" id="fs_synchronous_api">#</a></span></h3> 4249<p>The synchronous APIs perform all operations synchronously, blocking the 4250event loop until the operation completes or fails.</p> 4251<h4><code>fs.accessSync(path[, mode])</code><span><a class="mark" href="#fs_fs_accesssync_path_mode" id="fs_fs_accesssync_path_mode">#</a></span></h4> 4252<div class="api_metadata"> 4253<details class="changelog"><summary>History</summary> 4254<table> 4255<tbody><tr><th>Version</th><th>Changes</th></tr> 4256<tr><td>v7.6.0</td> 4257<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4258<tr><td>v0.11.15</td> 4259<td><p><span>Added in: v0.11.15</span></p></td></tr> 4260</tbody></table> 4261</details> 4262</div> 4263<ul> 4264<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> 4265<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> 4266</ul> 4267<p>Synchronously tests a user's permissions for the file or directory specified 4268by <code>path</code>. The <code>mode</code> argument is an optional integer that specifies the 4269accessibility checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for 4270possible values of <code>mode</code>. It is possible to create a mask consisting of 4271the bitwise OR of two or more values 4272(e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 4273<p>If any of the accessibility checks fail, an <code>Error</code> will be thrown. Otherwise, 4274the method will return <code>undefined</code>.</p> 4275<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { accessSync, constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4276 4277<span class="hljs-keyword">try</span> { 4278 <span class="hljs-title function_">accessSync</span>(<span class="hljs-string">'etc/passwd'</span>, constants.<span class="hljs-property">R_OK</span> | constants.<span class="hljs-property">W_OK</span>); 4279 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can read/write'</span>); 4280} <span class="hljs-keyword">catch</span> (err) { 4281 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'no access!'</span>); 4282}</code></pre> 4283<h4><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></h4> 4284<div class="api_metadata"> 4285<details class="changelog"><summary>History</summary> 4286<table> 4287<tbody><tr><th>Version</th><th>Changes</th></tr> 4288<tr><td>v7.0.0</td> 4289<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 4290<tr><td>v5.0.0</td> 4291<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4292<tr><td>v0.6.7</td> 4293<td><p><span>Added in: v0.6.7</span></p></td></tr> 4294</tbody></table> 4295</details> 4296</div> 4297<ul> 4298<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> 4299<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> 4300<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> 4301<ul> 4302<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> 4303<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> 4304<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> 4305</ul> 4306</li> 4307</ul> 4308<p>Synchronously append data to a file, creating the file if it does not yet 4309exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 4310<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 4311for more details.</p> 4312<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { appendFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4313 4314<span class="hljs-keyword">try</span> { 4315 <span class="hljs-title function_">appendFileSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>); 4316 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The "data to append" was appended to file!'</span>); 4317} <span class="hljs-keyword">catch</span> (err) { 4318 <span class="hljs-comment">/* Handle the error */</span> 4319}</code></pre> 4320<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4321<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { appendFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4322 4323<span class="hljs-title function_">appendFileSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>);</code></pre> 4324<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened 4325for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will 4326not be closed automatically.</p> 4327<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { openSync, closeSync, appendFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4328 4329<span class="hljs-keyword">let</span> fd; 4330 4331<span class="hljs-keyword">try</span> { 4332 fd = <span class="hljs-title function_">openSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'a'</span>); 4333 <span class="hljs-title function_">appendFileSync</span>(fd, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>); 4334} <span class="hljs-keyword">catch</span> (err) { 4335 <span class="hljs-comment">/* Handle the error */</span> 4336} <span class="hljs-keyword">finally</span> { 4337 <span class="hljs-keyword">if</span> (fd !== <span class="hljs-literal">undefined</span>) 4338 <span class="hljs-title function_">closeSync</span>(fd); 4339}</code></pre> 4340<h4><code>fs.chmodSync(path, mode)</code><span><a class="mark" href="#fs_fs_chmodsync_path_mode" id="fs_fs_chmodsync_path_mode">#</a></span></h4> 4341<div class="api_metadata"> 4342<details class="changelog"><summary>History</summary> 4343<table> 4344<tbody><tr><th>Version</th><th>Changes</th></tr> 4345<tr><td>v7.6.0</td> 4346<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4347<tr><td>v0.6.7</td> 4348<td><p><span>Added in: v0.6.7</span></p></td></tr> 4349</tbody></table> 4350</details> 4351</div> 4352<ul> 4353<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> 4354<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> 4355</ul> 4356<p>For detailed information, see the documentation of the asynchronous version of 4357this API: <a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p> 4358<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/chmod.2.html"><code>chmod(2)</code></a> documentation for more detail.</p> 4359<h4><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></h4> 4360<div class="api_metadata"> 4361<details class="changelog"><summary>History</summary> 4362<table> 4363<tbody><tr><th>Version</th><th>Changes</th></tr> 4364<tr><td>v7.6.0</td> 4365<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4366<tr><td>v0.1.97</td> 4367<td><p><span>Added in: v0.1.97</span></p></td></tr> 4368</tbody></table> 4369</details> 4370</div> 4371<ul> 4372<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> 4373<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4374<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4375</ul> 4376<p>Synchronously changes owner and group of a file. Returns <code>undefined</code>. 4377This is the synchronous version of <a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown()</code></a>.</p> 4378<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/chown.2.html"><code>chown(2)</code></a> documentation for more detail.</p> 4379<h4><code>fs.closeSync(fd)</code><span><a class="mark" href="#fs_fs_closesync_fd" id="fs_fs_closesync_fd">#</a></span></h4> 4380<div class="api_metadata"> 4381<span>Added in: v0.1.21</span> 4382</div> 4383<ul> 4384<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4385</ul> 4386<p>Closes the file descriptor. Returns <code>undefined</code>.</p> 4387<p>Calling <code>fs.closeSync()</code> on any file descriptor (<code>fd</code>) that is currently in use 4388through any other <code>fs</code> operation may lead to undefined behavior.</p> 4389<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/close.2.html"><code>close(2)</code></a> documentation for more detail.</p> 4390<h4><code>fs.copyFileSync(src, dest[, mode])</code><span><a class="mark" href="#fs_fs_copyfilesync_src_dest_mode" id="fs_fs_copyfilesync_src_dest_mode">#</a></span></h4> 4391<div class="api_metadata"> 4392<details class="changelog"><summary>History</summary> 4393<table> 4394<tbody><tr><th>Version</th><th>Changes</th></tr> 4395<tr><td>v14.0.0</td> 4396<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 4397<tr><td>v8.5.0</td> 4398<td><p><span>Added in: v8.5.0</span></p></td></tr> 4399</tbody></table> 4400</details> 4401</div> 4402<ul> 4403<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> 4404<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> 4405<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> modifiers for copy operation. <strong>Default:</strong> <code>0</code>.</li> 4406</ul> 4407<p>Synchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 4408already exists. Returns <code>undefined</code>. Node.js makes no guarantees about the 4409atomicity of the copy operation. If an error occurs after the destination file 4410has been opened for writing, Node.js will attempt to remove the destination.</p> 4411<p><code>mode</code> is an optional integer that specifies the behavior 4412of the copy operation. It is possible to create a mask consisting of the bitwise 4413OR of two or more values (e.g. 4414<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p> 4415<ul> 4416<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already 4417exists.</li> 4418<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a 4419copy-on-write reflink. If the platform does not support copy-on-write, then a 4420fallback copy mechanism is used.</li> 4421<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 4422create a copy-on-write reflink. If the platform does not support 4423copy-on-write, then the operation will fail.</li> 4424</ul> 4425<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { copyFileSync, constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4426 4427<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span> 4428<span class="hljs-title function_">copyFileSync</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>); 4429<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'source.txt was copied to destination.txt'</span>); 4430 4431<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 4432<span class="hljs-title function_">copyFileSync</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, constants.<span class="hljs-property">COPYFILE_EXCL</span>);</code></pre> 4433<h4><code>fs.existsSync(path)</code><span><a class="mark" href="#fs_fs_existssync_path" id="fs_fs_existssync_path">#</a></span></h4> 4434<div class="api_metadata"> 4435<details class="changelog"><summary>History</summary> 4436<table> 4437<tbody><tr><th>Version</th><th>Changes</th></tr> 4438<tr><td>v7.6.0</td> 4439<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4440<tr><td>v0.1.21</td> 4441<td><p><span>Added in: v0.1.21</span></p></td></tr> 4442</tbody></table> 4443</details> 4444</div> 4445<ul> 4446<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> 4447<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 4448</ul> 4449<p>Returns <code>true</code> if the path exists, <code>false</code> otherwise.</p> 4450<p>For detailed information, see the documentation of the asynchronous version of 4451this API: <a href="#fs_fs_exists_path_callback"><code>fs.exists()</code></a>.</p> 4452<p><code>fs.exists()</code> is deprecated, but <code>fs.existsSync()</code> is not. The <code>callback</code> 4453parameter to <code>fs.exists()</code> accepts parameters that are inconsistent with other 4454Node.js callbacks. <code>fs.existsSync()</code> does not use a callback.</p> 4455<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { existsSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4456 4457<span class="hljs-keyword">if</span> (<span class="hljs-title function_">existsSync</span>(<span class="hljs-string">'/etc/passwd'</span>)) 4458 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The path exists.'</span>);</code></pre> 4459<h4><code>fs.fchmodSync(fd, mode)</code><span><a class="mark" href="#fs_fs_fchmodsync_fd_mode" id="fs_fs_fchmodsync_fd_mode">#</a></span></h4> 4460<div class="api_metadata"> 4461<span>Added in: v0.4.7</span> 4462</div> 4463<ul> 4464<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4465<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> 4466</ul> 4467<p>Sets the permissions on the file. Returns <code>undefined</code>.</p> 4468<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fchmod.2.html"><code>fchmod(2)</code></a> documentation for more detail.</p> 4469<h4><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></h4> 4470<div class="api_metadata"> 4471<span>Added in: v0.4.7</span> 4472</div> 4473<ul> 4474<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4475<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new owner's user id.</li> 4476<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new group's group id.</li> 4477</ul> 4478<p>Sets the owner of the file. Returns <code>undefined</code>.</p> 4479<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fchown.2.html"><code>fchown(2)</code></a> documentation for more detail.</p> 4480<h4><code>fs.fdatasyncSync(fd)</code><span><a class="mark" href="#fs_fs_fdatasyncsync_fd" id="fs_fs_fdatasyncsync_fd">#</a></span></h4> 4481<div class="api_metadata"> 4482<span>Added in: v0.1.96</span> 4483</div> 4484<ul> 4485<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4486</ul> 4487<p>Forces all currently queued I/O operations associated with the file to the 4488operating system's synchronized I/O completion state. Refer to the POSIX 4489<a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a> documentation for details. Returns <code>undefined</code>.</p> 4490<h4><code>fs.fstatSync(fd[, options])</code><span><a class="mark" href="#fs_fs_fstatsync_fd_options" id="fs_fs_fstatsync_fd_options">#</a></span></h4> 4491<div class="api_metadata"> 4492<details class="changelog"><summary>History</summary> 4493<table> 4494<tbody><tr><th>Version</th><th>Changes</th></tr> 4495<tr><td>v10.5.0</td> 4496<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4497<tr><td>v0.1.95</td> 4498<td><p><span>Added in: v0.1.95</span></p></td></tr> 4499</tbody></table> 4500</details> 4501</div> 4502<ul> 4503<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4504<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4505<ul> 4506<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 4507<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 4508</ul> 4509</li> 4510<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4511</ul> 4512<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file descriptor.</p> 4513<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/fstat.2.html"><code>fstat(2)</code></a> documentation for more detail.</p> 4514<h4><code>fs.fsyncSync(fd)</code><span><a class="mark" href="#fs_fs_fsyncsync_fd" id="fs_fs_fsyncsync_fd">#</a></span></h4> 4515<div class="api_metadata"> 4516<span>Added in: v0.1.96</span> 4517</div> 4518<ul> 4519<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4520</ul> 4521<p>Request that all data for the open file descriptor is flushed to the storage 4522device. The specific implementation is operating system and device specific. 4523Refer to the POSIX <a href="http://man7.org/linux/man-pages/man2/fsync.2.html"><code>fsync(2)</code></a> documentation for more detail. Returns <code>undefined</code>.</p> 4524<h4><code>fs.ftruncateSync(fd[, len])</code><span><a class="mark" href="#fs_fs_ftruncatesync_fd_len" id="fs_fs_ftruncatesync_fd_len">#</a></span></h4> 4525<div class="api_metadata"> 4526<span>Added in: v0.8.6</span> 4527</div> 4528<ul> 4529<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4530<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> 4531</ul> 4532<p>Truncates the file descriptor. Returns <code>undefined</code>.</p> 4533<p>For detailed information, see the documentation of the asynchronous version of 4534this API: <a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate()</code></a>.</p> 4535<h4><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></h4> 4536<div class="api_metadata"> 4537<details class="changelog"><summary>History</summary> 4538<table> 4539<tbody><tr><th>Version</th><th>Changes</th></tr> 4540<tr><td>v4.1.0</td> 4541<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 4542<tr><td>v0.4.2</td> 4543<td><p><span>Added in: v0.4.2</span></p></td></tr> 4544</tbody></table> 4545</details> 4546</div> 4547<ul> 4548<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4549<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> 4550<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> 4551</ul> 4552<p>Synchronous version of <a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes()</code></a>. Returns <code>undefined</code>.</p> 4553<h4><code>fs.lchmodSync(path, mode)</code><span><a class="mark" href="#fs_fs_lchmodsync_path_mode" id="fs_fs_lchmodsync_path_mode">#</a></span></h4> 4554<div class="api_metadata"> 4555<span>Deprecated since: v0.4.7</span> 4556</div> 4557<ul> 4558<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> 4559<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4560</ul> 4561<p>Changes the permissions on a symbolic link. Returns <code>undefined</code>.</p> 4562<p>This method is only implemented on macOS.</p> 4563<p>See the POSIX <a href="https://www.freebsd.org/cgi/man.cgi?query=lchmod&sektion=2"><code>lchmod(2)</code></a> documentation for more detail.</p> 4564<h4><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></h4> 4565<div class="api_metadata"> 4566<details class="changelog"><summary>History</summary> 4567<table> 4568<tbody><tr><th>Version</th><th>Changes</th></tr> 4569<tr><td>v10.6.0</td> 4570<td><p>This API is no longer deprecated.</p></td></tr> 4571<tr><td>v0.4.7</td> 4572<td><p>Documentation-only deprecation.</p></td></tr> 4573</tbody></table> 4574</details> 4575</div> 4576<ul> 4577<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> 4578<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new owner's user id.</li> 4579<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> The file's new group's group id.</li> 4580</ul> 4581<p>Set the owner for the path. Returns <code>undefined</code>.</p> 4582<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/lchown.2.html"><code>lchown(2)</code></a> documentation for more details.</p> 4583<h4><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></h4> 4584<div class="api_metadata"> 4585<span>Added in: v14.5.0, v12.19.0</span> 4586</div> 4587<ul> 4588<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> 4589<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> 4590<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> 4591</ul> 4592<p>Change the file system timestamps of the symbolic link referenced by <code>path</code>. 4593Returns <code>undefined</code>, or throws an exception when parameters are incorrect or 4594the operation fails. This is the synchronous version of <a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes()</code></a>.</p> 4595<h4><code>fs.linkSync(existingPath, newPath)</code><span><a class="mark" href="#fs_fs_linksync_existingpath_newpath" id="fs_fs_linksync_existingpath_newpath">#</a></span></h4> 4596<div class="api_metadata"> 4597<details class="changelog"><summary>History</summary> 4598<table> 4599<tbody><tr><th>Version</th><th>Changes</th></tr> 4600<tr><td>v7.6.0</td> 4601<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> 4602<tr><td>v0.1.31</td> 4603<td><p><span>Added in: v0.1.31</span></p></td></tr> 4604</tbody></table> 4605</details> 4606</div> 4607<ul> 4608<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> 4609<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> 4610</ul> 4611<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 4612<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a> documentation for more detail. Returns <code>undefined</code>.</p> 4613<h4><code>fs.lstatSync(path[, options])</code><span><a class="mark" href="#fs_fs_lstatsync_path_options" id="fs_fs_lstatsync_path_options">#</a></span></h4> 4614<div class="api_metadata"> 4615<details class="changelog"><summary>History</summary> 4616<table> 4617<tbody><tr><th>Version</th><th>Changes</th></tr> 4618<tr><td>v14.17.0</td> 4619<td><p>Accepts a <code>throwIfNoEntry</code> option to specify whether an exception should be thrown if the entry does not exist.</p></td></tr> 4620<tr><td>v10.5.0</td> 4621<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4622<tr><td>v7.6.0</td> 4623<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4624<tr><td>v0.1.30</td> 4625<td><p><span>Added in: v0.1.30</span></p></td></tr> 4626</tbody></table> 4627</details> 4628</div> 4629<ul> 4630<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> 4631<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4632<ul> 4633<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 4634<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 4635<li><code>throwIfNoEntry</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether an exception will be thrown 4636if no file system entry exists, rather than returning <code>undefined</code>. 4637<strong>Default:</strong> <code>true</code>.</li> 4638</ul> 4639</li> 4640<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4641</ul> 4642<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the symbolic link referred to by <code>path</code>.</p> 4643<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/lstat.2.html"><code>lstat(2)</code></a> documentation for more details.</p> 4644<h4><code>fs.mkdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_mkdirsync_path_options" id="fs_fs_mkdirsync_path_options">#</a></span></h4> 4645<div class="api_metadata"> 4646<details class="changelog"><summary>History</summary> 4647<table> 4648<tbody><tr><th>Version</th><th>Changes</th></tr> 4649<tr><td>v13.11.0, v12.17.0</td> 4650<td><p>In <code>recursive</code> mode, the first created path is returned now.</p></td></tr> 4651<tr><td>v10.12.0</td> 4652<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> 4653<tr><td>v7.6.0</td> 4654<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4655<tr><td>v0.1.21</td> 4656<td><p><span>Added in: v0.1.21</span></p></td></tr> 4657</tbody></table> 4658</details> 4659</div> 4660<ul> 4661<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> 4662<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> 4663<ul> 4664<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> 4665<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> 4666</ul> 4667</li> 4668<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> 4669</ul> 4670<p>Synchronously creates a directory. Returns <code>undefined</code>, or if <code>recursive</code> is 4671<code>true</code>, the first directory path created. 4672This is the synchronous version of <a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir()</code></a>.</p> 4673<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"><code>mkdir(2)</code></a> documentation for more details.</p> 4674<h4><code>fs.mkdtempSync(prefix[, options])</code><span><a class="mark" href="#fs_fs_mkdtempsync_prefix_options" id="fs_fs_mkdtempsync_prefix_options">#</a></span></h4> 4675<div class="api_metadata"> 4676<details class="changelog"><summary>History</summary> 4677<table> 4678<tbody><tr><th>Version</th><th>Changes</th></tr> 4679<tr><td>v14.18.0</td> 4680<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 4681<tr><td>v5.10.0</td> 4682<td><p><span>Added in: v5.10.0</span></p></td></tr> 4683</tbody></table> 4684</details> 4685</div> 4686<ul> 4687<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4688<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> 4689<ul> 4690<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> 4691</ul> 4692</li> 4693<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4694</ul> 4695<p>Returns the created directory path.</p> 4696<p>For detailed information, see the documentation of the asynchronous version of 4697this API: <a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp()</code></a>.</p> 4698<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4699object with an <code>encoding</code> property specifying the character encoding to use.</p> 4700<h4><code>fs.opendirSync(path[, options])</code><span><a class="mark" href="#fs_fs_opendirsync_path_options" id="fs_fs_opendirsync_path_options">#</a></span></h4> 4701<div class="api_metadata"> 4702<details class="changelog"><summary>History</summary> 4703<table> 4704<tbody><tr><th>Version</th><th>Changes</th></tr> 4705<tr><td>v13.1.0, v12.16.0</td> 4706<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 4707<tr><td>v12.12.0</td> 4708<td><p><span>Added in: v12.12.0</span></p></td></tr> 4709</tbody></table> 4710</details> 4711</div> 4712<ul> 4713<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> 4714<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4715<ul> 4716<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> 4717<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 4718internally when reading from the directory. Higher values lead to better 4719performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 4720</ul> 4721</li> 4722<li>Returns: <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li> 4723</ul> 4724<p>Synchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p> 4725<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 4726and cleaning up the directory.</p> 4727<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 4728directory and subsequent read operations.</p> 4729<h4><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></h4> 4730<div class="api_metadata"> 4731<details class="changelog"><summary>History</summary> 4732<table> 4733<tbody><tr><th>Version</th><th>Changes</th></tr> 4734<tr><td>v11.1.0</td> 4735<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 4736<tr><td>v9.9.0</td> 4737<td><p>The <code>as</code> and <code>as+</code> flags are supported now.</p></td></tr> 4738<tr><td>v7.6.0</td> 4739<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4740<tr><td>v0.1.21</td> 4741<td><p><span>Added in: v0.1.21</span></p></td></tr> 4742</tbody></table> 4743</details> 4744</div> 4745<ul> 4746<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> 4747<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>. 4748See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.</li> 4749<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> 4750<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4751</ul> 4752<p>Returns an integer representing the file descriptor.</p> 4753<p>For detailed information, see the documentation of the asynchronous version of 4754this API: <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a>.</p> 4755<h4><code>fs.readdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_readdirsync_path_options" id="fs_fs_readdirsync_path_options">#</a></span></h4> 4756<div class="api_metadata"> 4757<details class="changelog"><summary>History</summary> 4758<table> 4759<tbody><tr><th>Version</th><th>Changes</th></tr> 4760<tr><td>v10.10.0</td> 4761<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 4762<tr><td>v7.6.0</td> 4763<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4764<tr><td>v0.1.21</td> 4765<td><p><span>Added in: v0.1.21</span></p></td></tr> 4766</tbody></table> 4767</details> 4768</div> 4769<ul> 4770<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> 4771<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> 4772<ul> 4773<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> 4774<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> 4775</ul> 4776</li> 4777<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> 4778</ul> 4779<p>Reads the contents of the directory.</p> 4780<p>See the POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more details.</p> 4781<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4782object with an <code>encoding</code> property specifying the character encoding to use for 4783the filenames returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4784the filenames returned will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 4785<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the result will contain 4786<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 4787<h4><code>fs.readFileSync(path[, options])</code><span><a class="mark" href="#fs_fs_readfilesync_path_options" id="fs_fs_readfilesync_path_options">#</a></span></h4> 4788<div class="api_metadata"> 4789<details class="changelog"><summary>History</summary> 4790<table> 4791<tbody><tr><th>Version</th><th>Changes</th></tr> 4792<tr><td>v7.6.0</td> 4793<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4794<tr><td>v5.0.0</td> 4795<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr> 4796<tr><td>v0.1.8</td> 4797<td><p><span>Added in: v0.1.8</span></p></td></tr> 4798</tbody></table> 4799</details> 4800</div> 4801<ul> 4802<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> 4803<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> 4804<ul> 4805<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> 4806<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> 4807</ul> 4808</li> 4809<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> 4810</ul> 4811<p>Returns the contents of the <code>path</code>.</p> 4812<p>For detailed information, see the documentation of the asynchronous version of 4813this API: <a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile()</code></a>.</p> 4814<p>If the <code>encoding</code> option is specified then this function returns a 4815string. Otherwise it returns a buffer.</p> 4816<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 4817<code>fs.readFileSync()</code> is platform-specific.</p> 4818<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 4819 4820<span class="hljs-comment">// macOS, Linux, and Windows</span> 4821<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); 4822<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span> 4823 4824<span class="hljs-comment">// FreeBSD</span> 4825<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); <span class="hljs-comment">// => <data></span></code></pre> 4826<h4><code>fs.readlinkSync(path[, options])</code><span><a class="mark" href="#fs_fs_readlinksync_path_options" id="fs_fs_readlinksync_path_options">#</a></span></h4> 4827<div class="api_metadata"> 4828<details class="changelog"><summary>History</summary> 4829<table> 4830<tbody><tr><th>Version</th><th>Changes</th></tr> 4831<tr><td>v7.6.0</td> 4832<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4833<tr><td>v0.1.31</td> 4834<td><p><span>Added in: v0.1.31</span></p></td></tr> 4835</tbody></table> 4836</details> 4837</div> 4838<ul> 4839<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> 4840<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> 4841<ul> 4842<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> 4843</ul> 4844</li> 4845<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> 4846</ul> 4847<p>Returns the symbolic link's string value.</p> 4848<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/readlink.2.html"><code>readlink(2)</code></a> documentation for more details.</p> 4849<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4850object with an <code>encoding</code> property specifying the character encoding to use for 4851the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4852the link path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4853<h4><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></h4> 4854<div class="api_metadata"> 4855<details class="changelog"><summary>History</summary> 4856<table> 4857<tbody><tr><th>Version</th><th>Changes</th></tr> 4858<tr><td>v10.10.0</td> 4859<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4860<tr><td>v6.0.0</td> 4861<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr> 4862<tr><td>v0.1.21</td> 4863<td><p><span>Added in: v0.1.21</span></p></td></tr> 4864</tbody></table> 4865</details> 4866</div> 4867<ul> 4868<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4869<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> 4870<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4871<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4872<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 4873<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4874</ul> 4875<p>Returns the number of <code>bytesRead</code>.</p> 4876<p>For detailed information, see the documentation of the asynchronous version of 4877this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4878<h4><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></h4> 4879<div class="api_metadata"> 4880<details class="changelog"><summary>History</summary> 4881<table> 4882<tbody><tr><th>Version</th><th>Changes</th></tr> 4883<tr><td>v13.13.0, v12.17.0</td> 4884<td><p><span>Added in: v13.13.0, v12.17.0</span></p></td></tr> 4885<tr><td>v13.13.0, v12.17.0</td> 4886<td><p>Options object can be passed in to make offset, length and position optional.</p></td></tr> 4887</tbody></table> 4888</details> 4889</div> 4890<ul> 4891<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4892<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> 4893<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4894<ul> 4895<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> 4896<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.byteLength</code></li> 4897<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a> <strong>Default:</strong> <code>null</code></li> 4898</ul> 4899</li> 4900<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4901</ul> 4902<p>Returns the number of <code>bytesRead</code>.</p> 4903<p>Similar to the above <code>fs.readSync</code> function, this version takes an optional <code>options</code> object. 4904If no <code>options</code> object is specified, it will default with the above values.</p> 4905<p>For detailed information, see the documentation of the asynchronous version of 4906this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4907<h4><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></h4> 4908<div class="api_metadata"> 4909<span>Added in: v13.13.0, v12.17.0</span> 4910</div> 4911<ul> 4912<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4913<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4914<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4915<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> 4916</ul> 4917<p>For detailed information, see the documentation of the asynchronous version of 4918this API: <a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv()</code></a>.</p> 4919<h4><code>fs.realpathSync(path[, options])</code><span><a class="mark" href="#fs_fs_realpathsync_path_options" id="fs_fs_realpathsync_path_options">#</a></span></h4> 4920<div class="api_metadata"> 4921<details class="changelog"><summary>History</summary> 4922<table> 4923<tbody><tr><th>Version</th><th>Changes</th></tr> 4924<tr><td>v8.0.0</td> 4925<td><p>Pipe/Socket resolve support was added.</p></td></tr> 4926<tr><td>v7.6.0</td> 4927<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4928<tr><td>v6.4.0</td> 4929<td><p>Calling <code>realpathSync</code> now works again for various edge cases on Windows.</p></td></tr> 4930<tr><td>v6.0.0</td> 4931<td><p>The <code>cache</code> parameter was removed.</p></td></tr> 4932<tr><td>v0.1.31</td> 4933<td><p><span>Added in: v0.1.31</span></p></td></tr> 4934</tbody></table> 4935</details> 4936</div> 4937<ul> 4938<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> 4939<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> 4940<ul> 4941<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> 4942</ul> 4943</li> 4944<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> 4945</ul> 4946<p>Returns the resolved pathname.</p> 4947<p>For detailed information, see the documentation of the asynchronous version of 4948this API: <a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath()</code></a>.</p> 4949<h4><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></h4> 4950<div class="api_metadata"> 4951<span>Added in: v9.2.0</span> 4952</div> 4953<ul> 4954<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> 4955<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> 4956<ul> 4957<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> 4958</ul> 4959</li> 4960<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> 4961</ul> 4962<p>Synchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p> 4963<p>Only paths that can be converted to UTF8 strings are supported.</p> 4964<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4965object with an <code>encoding</code> property specifying the character encoding to use for 4966the path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4967the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4968<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 4969be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 4970this restriction.</p> 4971<h4><code>fs.renameSync(oldPath, newPath)</code><span><a class="mark" href="#fs_fs_renamesync_oldpath_newpath" id="fs_fs_renamesync_oldpath_newpath">#</a></span></h4> 4972<div class="api_metadata"> 4973<details class="changelog"><summary>History</summary> 4974<table> 4975<tbody><tr><th>Version</th><th>Changes</th></tr> 4976<tr><td>v7.6.0</td> 4977<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> 4978<tr><td>v0.1.21</td> 4979<td><p><span>Added in: v0.1.21</span></p></td></tr> 4980</tbody></table> 4981</details> 4982</div> 4983<ul> 4984<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> 4985<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> 4986</ul> 4987<p>Renames the file from <code>oldPath</code> to <code>newPath</code>. Returns <code>undefined</code>.</p> 4988<p>See the POSIX <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a> documentation for more details.</p> 4989<h4><code>fs.rmdirSync(path[, options])</code><span><a class="mark" href="#fs_fs_rmdirsync_path_options" id="fs_fs_rmdirsync_path_options">#</a></span></h4> 4990<div class="api_metadata"> 4991<details class="changelog"><summary>History</summary> 4992<table> 4993<tbody><tr><th>Version</th><th>Changes</th></tr> 4994<tr><td>v14.14.0</td> 4995<td><p>The <code>recursive</code> option is deprecated, use <code>fs.rmSync</code> instead.</p></td></tr> 4996<tr><td>v13.3.0, v12.16.0</td> 4997<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> 4998<tr><td>v12.10.0</td> 4999<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 5000<tr><td>v7.6.0</td> 5001<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5002<tr><td>v0.1.21</td> 5003<td><p><span>Added in: v0.1.21</span></p></td></tr> 5004</tbody></table> 5005</details> 5006</div> 5007<ul> 5008<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> 5009<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5010<ul> 5011<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 5012<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 5013backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5014represents the number of retries. This option is ignored if the <code>recursive</code> 5015option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5016<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 5017recursive mode, errors are not reported if <code>path</code> does not exist, and 5018operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5019<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 5020retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5021<strong>Default:</strong> <code>100</code>.</li> 5022</ul> 5023</li> 5024</ul> 5025<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"><code>rmdir(2)</code></a>. Returns <code>undefined</code>.</p> 5026<p>Using <code>fs.rmdirSync()</code> on a file (not a directory) results in an <code>ENOENT</code> error 5027on Windows and an <code>ENOTDIR</code> error on POSIX.</p> 5028<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 5029<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 5030that represent files will be deleted. The permissive behavior of the 5031<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 5032the future.</p> 5033<h4><code>fs.rmSync(path[, options])</code><span><a class="mark" href="#fs_fs_rmsync_path_options" id="fs_fs_rmsync_path_options">#</a></span></h4> 5034<div class="api_metadata"> 5035<span>Added in: v14.14.0</span> 5036</div> 5037<ul> 5038<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> 5039<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5040<ul> 5041<li><code>force</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When <code>true</code>, exceptions will be ignored if <code>path</code> does 5042not exist. <strong>Default:</strong> <code>false</code>.</li> 5043<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 5044<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 5045backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5046represents the number of retries. This option is ignored if the <code>recursive</code> 5047option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5048<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 5049recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5050<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 5051retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5052<strong>Default:</strong> <code>100</code>.</li> 5053</ul> 5054</li> 5055</ul> 5056<p>Synchronously removes files and directories (modeled on the standard POSIX <code>rm</code> 5057utility). Returns <code>undefined</code>.</p> 5058<h4><code>fs.statSync(path[, options])</code><span><a class="mark" href="#fs_fs_statsync_path_options" id="fs_fs_statsync_path_options">#</a></span></h4> 5059<div class="api_metadata"> 5060<details class="changelog"><summary>History</summary> 5061<table> 5062<tbody><tr><th>Version</th><th>Changes</th></tr> 5063<tr><td>v14.17.0</td> 5064<td><p>Accepts a <code>throwIfNoEntry</code> option to specify whether an exception should be thrown if the entry does not exist.</p></td></tr> 5065<tr><td>v10.5.0</td> 5066<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 5067<tr><td>v7.6.0</td> 5068<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5069<tr><td>v0.1.21</td> 5070<td><p><span>Added in: v0.1.21</span></p></td></tr> 5071</tbody></table> 5072</details> 5073</div> 5074<ul> 5075<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> 5076<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5077<ul> 5078<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 5079<a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object should be <code>bigint</code>. <strong>Default:</strong> <code>false</code>.</li> 5080<li><code>throwIfNoEntry</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether an exception will be thrown 5081if no file system entry exists, rather than returning <code>undefined</code>. 5082<strong>Default:</strong> <code>true</code>.</li> 5083</ul> 5084</li> 5085<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 5086</ul> 5087<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the path.</p> 5088<h4><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></h4> 5089<div class="api_metadata"> 5090<details class="changelog"><summary>History</summary> 5091<table> 5092<tbody><tr><th>Version</th><th>Changes</th></tr> 5093<tr><td>v12.0.0</td> 5094<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> 5095<tr><td>v7.6.0</td> 5096<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> 5097<tr><td>v0.1.31</td> 5098<td><p><span>Added in: v0.1.31</span></p></td></tr> 5099</tbody></table> 5100</details> 5101</div> 5102<ul> 5103<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> 5104<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> 5105<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5106</ul> 5107<p>Returns <code>undefined</code>.</p> 5108<p>For detailed information, see the documentation of the asynchronous version of 5109this API: <a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink()</code></a>.</p> 5110<h4><code>fs.truncateSync(path[, len])</code><span><a class="mark" href="#fs_fs_truncatesync_path_len" id="fs_fs_truncatesync_path_len">#</a></span></h4> 5111<div class="api_metadata"> 5112<span>Added in: v0.8.6</span> 5113</div> 5114<ul> 5115<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> 5116<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> 5117</ul> 5118<p>Truncates the file. Returns <code>undefined</code>. A file descriptor can also be 5119passed as the first argument. In this case, <code>fs.ftruncateSync()</code> is called.</p> 5120<p>Passing a file descriptor is deprecated and may result in an error being thrown 5121in the future.</p> 5122<h4><code>fs.unlinkSync(path)</code><span><a class="mark" href="#fs_fs_unlinksync_path" id="fs_fs_unlinksync_path">#</a></span></h4> 5123<div class="api_metadata"> 5124<details class="changelog"><summary>History</summary> 5125<table> 5126<tbody><tr><th>Version</th><th>Changes</th></tr> 5127<tr><td>v7.6.0</td> 5128<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5129<tr><td>v0.1.21</td> 5130<td><p><span>Added in: v0.1.21</span></p></td></tr> 5131</tbody></table> 5132</details> 5133</div> 5134<ul> 5135<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> 5136</ul> 5137<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>. Returns <code>undefined</code>.</p> 5138<h4><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></h4> 5139<div class="api_metadata"> 5140<details class="changelog"><summary>History</summary> 5141<table> 5142<tbody><tr><th>Version</th><th>Changes</th></tr> 5143<tr><td>v8.0.0</td> 5144<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr> 5145<tr><td>v7.6.0</td> 5146<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5147<tr><td>v4.1.0</td> 5148<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 5149<tr><td>v0.4.2</td> 5150<td><p><span>Added in: v0.4.2</span></p></td></tr> 5151</tbody></table> 5152</details> 5153</div> 5154<ul> 5155<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> 5156<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> 5157<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> 5158</ul> 5159<p>Returns <code>undefined</code>.</p> 5160<p>For detailed information, see the documentation of the asynchronous version of 5161this API: <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p> 5162<h4><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></h4> 5163<div class="api_metadata"> 5164<details class="changelog"><summary>History</summary> 5165<table> 5166<tbody><tr><th>Version</th><th>Changes</th></tr> 5167<tr><td>v14.12.0</td> 5168<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 5169<tr><td>v14.0.0</td> 5170<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5171<tr><td>v10.10.0</td> 5172<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5173<tr><td>v7.4.0</td> 5174<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5175<tr><td>v5.0.0</td> 5176<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 5177<tr><td>v0.1.29</td> 5178<td><p><span>Added in: v0.1.29</span></p></td></tr> 5179</tbody></table> 5180</details> 5181</div> 5182<ul> 5183<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> 5184<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> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 5185<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> 5186<ul> 5187<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> 5188<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> 5189<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> 5190</ul> 5191</li> 5192</ul> 5193<p>Returns <code>undefined</code>.</p> 5194<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 5195function property.</p> 5196<p>The <code>mode</code> option only affects the newly created file. See <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a> 5197for more details.</p> 5198<p>For detailed information, see the documentation of the asynchronous version of 5199this API: <a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile()</code></a>.</p> 5200<h4><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></h4> 5201<div class="api_metadata"> 5202<details class="changelog"><summary>History</summary> 5203<table> 5204<tbody><tr><th>Version</th><th>Changes</th></tr> 5205<tr><td>v14.12.0</td> 5206<td><p>The <code>buffer</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 5207<tr><td>v14.0.0</td> 5208<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5209<tr><td>v10.10.0</td> 5210<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5211<tr><td>v7.4.0</td> 5212<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5213<tr><td>v7.2.0</td> 5214<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 5215<tr><td>v0.1.21</td> 5216<td><p><span>Added in: v0.1.21</span></p></td></tr> 5217</tbody></table> 5218</details> 5219</div> 5220<ul> 5221<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5222<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> | <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></li> 5223<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5224<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5225<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5226<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> 5227</ul> 5228<p>If <code>buffer</code> is a plain object, it must have an own (not inherited) <code>toString</code> 5229function property.</p> 5230<p>For detailed information, see the documentation of the asynchronous version of 5231this API: <a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer...)</code></a>.</p> 5232<h4><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></h4> 5233<div class="api_metadata"> 5234<details class="changelog"><summary>History</summary> 5235<table> 5236<tbody><tr><th>Version</th><th>Changes</th></tr> 5237<tr><td>v14.12.0</td> 5238<td><p>The <code>string</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 5239<tr><td>v14.0.0</td> 5240<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5241<tr><td>v7.2.0</td> 5242<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 5243<tr><td>v0.11.5</td> 5244<td><p><span>Added in: v0.11.5</span></p></td></tr> 5245</tbody></table> 5246</details> 5247</div> 5248<ul> 5249<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5250<li><code>string</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></li> 5251<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5252<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5253<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> 5254</ul> 5255<p>If <code>string</code> is a plain object, it must have an own (not inherited) <code>toString</code> 5256function property.</p> 5257<p>For detailed information, see the documentation of the asynchronous version of 5258this API: <a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string...)</code></a>.</p> 5259<h4><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></h4> 5260<div class="api_metadata"> 5261<span>Added in: v12.9.0</span> 5262</div> 5263<ul> 5264<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5265<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 5266<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5267<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> 5268</ul> 5269<p>For detailed information, see the documentation of the asynchronous version of 5270this API: <a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev()</code></a>.</p> 5271</section><section><h3>Common Objects<span><a class="mark" href="#fs_common_objects" id="fs_common_objects">#</a></span></h3> 5272<p>The common objects are shared by all of the file system API variants 5273(promise, callback, and synchronous).</p> 5274<h4>Class: <code>fs.Dir</code><span><a class="mark" href="#fs_class_fs_dir" id="fs_class_fs_dir">#</a></span></h4> 5275<div class="api_metadata"> 5276<span>Added in: v12.12.0</span> 5277</div> 5278<p>A class representing a directory stream.</p> 5279<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 5280<a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir()</code></a>.</p> 5281<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { opendir } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 5282 5283<span class="hljs-keyword">try</span> { 5284 <span class="hljs-keyword">const</span> dir = <span class="hljs-keyword">await</span> <span class="hljs-title function_">opendir</span>(<span class="hljs-string">'./'</span>); 5285 <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) 5286 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 5287} <span class="hljs-keyword">catch</span> (err) { 5288 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 5289}</code></pre> 5290<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 5291closed after the iterator exits.</p> 5292<h5><code>dir.close()</code><span><a class="mark" href="#fs_dir_close" id="fs_dir_close">#</a></span></h5> 5293<div class="api_metadata"> 5294<span>Added in: v12.12.0</span> 5295</div> 5296<ul> 5297<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 5298</ul> 5299<p>Asynchronously close the directory's underlying resource handle. 5300Subsequent reads will result in errors.</p> 5301<p>A promise is returned that will be resolved after the resource has been 5302closed.</p> 5303<h5><code>dir.close(callback)</code><span><a class="mark" href="#fs_dir_close_callback" id="fs_dir_close_callback">#</a></span></h5> 5304<div class="api_metadata"> 5305<span>Added in: v12.12.0</span> 5306</div> 5307<ul> 5308<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5309<ul> 5310<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5311</ul> 5312</li> 5313</ul> 5314<p>Asynchronously close the directory's underlying resource handle. 5315Subsequent reads will result in errors.</p> 5316<p>The <code>callback</code> will be called after the resource handle has been closed.</p> 5317<h5><code>dir.closeSync()</code><span><a class="mark" href="#fs_dir_closesync" id="fs_dir_closesync">#</a></span></h5> 5318<div class="api_metadata"> 5319<span>Added in: v12.12.0</span> 5320</div> 5321<p>Synchronously close the directory's underlying resource handle. 5322Subsequent reads will result in errors.</p> 5323<h5><code>dir.path</code><span><a class="mark" href="#fs_dir_path" id="fs_dir_path">#</a></span></h5> 5324<div class="api_metadata"> 5325<span>Added in: v12.12.0</span> 5326</div> 5327<ul> 5328<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5329</ul> 5330<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>, 5331<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> 5332<h5><code>dir.read()</code><span><a class="mark" href="#fs_dir_read" id="fs_dir_read">#</a></span></h5> 5333<div class="api_metadata"> 5334<span>Added in: v12.12.0</span> 5335</div> 5336<ul> 5337<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> 5338</ul> 5339<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 5340<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5341<p>A promise is returned that will be resolved with an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>, or <code>null</code> 5342if there are no more directory entries to read.</p> 5343<p>Directory entries returned by this function are in no particular order as 5344provided by the operating system's underlying directory mechanisms. 5345Entries added or removed while iterating over the directory might not be 5346included in the iteration results.</p> 5347<h5><code>dir.read(callback)</code><span><a class="mark" href="#fs_dir_read_callback" id="fs_dir_read_callback">#</a></span></h5> 5348<div class="api_metadata"> 5349<span>Added in: v12.12.0</span> 5350</div> 5351<ul> 5352<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5353<ul> 5354<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5355<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> 5356</ul> 5357</li> 5358</ul> 5359<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 5360<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5361<p>After the read is completed, the <code>callback</code> will be called with an 5362<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>, or <code>null</code> if there are no more directory entries to read.</p> 5363<p>Directory entries returned by this function are in no particular order as 5364provided by the operating system's underlying directory mechanisms. 5365Entries added or removed while iterating over the directory might not be 5366included in the iteration results.</p> 5367<h5><code>dir.readSync()</code><span><a class="mark" href="#fs_dir_readsync" id="fs_dir_readsync">#</a></span></h5> 5368<div class="api_metadata"> 5369<span>Added in: v12.12.0</span> 5370</div> 5371<ul> 5372<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> 5373</ul> 5374<p>Synchronously read the next directory entry as an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. See the 5375POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more detail.</p> 5376<p>If there are no more directory entries to read, <code>null</code> will be returned.</p> 5377<p>Directory entries returned by this function are in no particular order as 5378provided by the operating system's underlying directory mechanisms. 5379Entries added or removed while iterating over the directory might not be 5380included in the iteration results.</p> 5381<h5><code>dir[Symbol.asyncIterator]()</code><span><a class="mark" href="#fs_dir_symbol_asynciterator" id="fs_dir_symbol_asynciterator">#</a></span></h5> 5382<div class="api_metadata"> 5383<span>Added in: v12.12.0</span> 5384</div> 5385<ul> 5386<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> 5387</ul> 5388<p>Asynchronously iterates over the directory until all entries have 5389been read. Refer to the POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more detail.</p> 5390<p>Entries returned by the async iterator are always an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. 5391The <code>null</code> case from <code>dir.read()</code> is handled internally.</p> 5392<p>See <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> for an example.</p> 5393<p>Directory entries returned by this iterator are in no particular order as 5394provided by the operating system's underlying directory mechanisms. 5395Entries added or removed while iterating over the directory might not be 5396included in the iteration results.</p> 5397<h4>Class: <code>fs.Dirent</code><span><a class="mark" href="#fs_class_fs_dirent" id="fs_class_fs_dirent">#</a></span></h4> 5398<div class="api_metadata"> 5399<span>Added in: v10.10.0</span> 5400</div> 5401<p>A representation of a directory entry, which can be a file or a subdirectory 5402within the directory, as returned by reading from an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>. The 5403directory entry is a combination of the file name and file type pairs.</p> 5404<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 5405the <code>withFileTypes</code> option set to <code>true</code>, the resulting array is filled with 5406<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects, rather than strings or <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>s.</p> 5407<h5><code>dirent.isBlockDevice()</code><span><a class="mark" href="#fs_dirent_isblockdevice" id="fs_dirent_isblockdevice">#</a></span></h5> 5408<div class="api_metadata"> 5409<span>Added in: v10.10.0</span> 5410</div> 5411<ul> 5412<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5413</ul> 5414<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a block device.</p> 5415<h5><code>dirent.isCharacterDevice()</code><span><a class="mark" href="#fs_dirent_ischaracterdevice" id="fs_dirent_ischaracterdevice">#</a></span></h5> 5416<div class="api_metadata"> 5417<span>Added in: v10.10.0</span> 5418</div> 5419<ul> 5420<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5421</ul> 5422<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a character device.</p> 5423<h5><code>dirent.isDirectory()</code><span><a class="mark" href="#fs_dirent_isdirectory" id="fs_dirent_isdirectory">#</a></span></h5> 5424<div class="api_metadata"> 5425<span>Added in: v10.10.0</span> 5426</div> 5427<ul> 5428<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5429</ul> 5430<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a file system 5431directory.</p> 5432<h5><code>dirent.isFIFO()</code><span><a class="mark" href="#fs_dirent_isfifo" id="fs_dirent_isfifo">#</a></span></h5> 5433<div class="api_metadata"> 5434<span>Added in: v10.10.0</span> 5435</div> 5436<ul> 5437<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5438</ul> 5439<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a first-in-first-out 5440(FIFO) pipe.</p> 5441<h5><code>dirent.isFile()</code><span><a class="mark" href="#fs_dirent_isfile" id="fs_dirent_isfile">#</a></span></h5> 5442<div class="api_metadata"> 5443<span>Added in: v10.10.0</span> 5444</div> 5445<ul> 5446<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5447</ul> 5448<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a regular file.</p> 5449<h5><code>dirent.isSocket()</code><span><a class="mark" href="#fs_dirent_issocket" id="fs_dirent_issocket">#</a></span></h5> 5450<div class="api_metadata"> 5451<span>Added in: v10.10.0</span> 5452</div> 5453<ul> 5454<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5455</ul> 5456<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a socket.</p> 5457<h5><code>dirent.isSymbolicLink()</code><span><a class="mark" href="#fs_dirent_issymboliclink" id="fs_dirent_issymboliclink">#</a></span></h5> 5458<div class="api_metadata"> 5459<span>Added in: v10.10.0</span> 5460</div> 5461<ul> 5462<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5463</ul> 5464<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object describes a symbolic link.</p> 5465<h5><code>dirent.name</code><span><a class="mark" href="#fs_dirent_name" id="fs_dirent_name">#</a></span></h5> 5466<div class="api_metadata"> 5467<span>Added in: v10.10.0</span> 5468</div> 5469<ul> 5470<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> 5471</ul> 5472<p>The file name that this <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> object refers to. The type of this 5473value is determined by the <code>options.encoding</code> passed to <a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir()</code></a> or 5474<a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync()</code></a>.</p> 5475<h4>Class: <code>fs.FSWatcher</code><span><a class="mark" href="#fs_class_fs_fswatcher" id="fs_class_fs_fswatcher">#</a></span></h4> 5476<div class="api_metadata"> 5477<span>Added in: v0.5.8</span> 5478</div> 5479<ul> 5480<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5481</ul> 5482<p>A successful call to <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> method will return a new <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> 5483object.</p> 5484<p>All <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> objects emit a <code>'change'</code> event whenever a specific watched 5485file is modified.</p> 5486<h5>Event: <code>'change'</code><span><a class="mark" href="#fs_event_change" id="fs_event_change">#</a></span></h5> 5487<div class="api_metadata"> 5488<span>Added in: v0.5.8</span> 5489</div> 5490<ul> 5491<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> 5492<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> 5493</ul> 5494<p>Emitted when something changes in a watched directory or file. 5495See more details in <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a>.</p> 5496<p>The <code>filename</code> argument may not be provided depending on operating system 5497support. If <code>filename</code> is provided, it will be provided as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> if 5498<code>fs.watch()</code> is called with its <code>encoding</code> option set to <code>'buffer'</code>, otherwise 5499<code>filename</code> will be a UTF-8 string.</p> 5500<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { watch } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 5501<span class="hljs-comment">// Example when handled through fs.watch() listener</span> 5502<span class="hljs-title function_">watch</span>(<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> { 5503 <span class="hljs-keyword">if</span> (filename) { 5504 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(filename); 5505 <span class="hljs-comment">// Prints: <Buffer ...></span> 5506 } 5507});</code></pre> 5508<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close" id="fs_event_close">#</a></span></h5> 5509<div class="api_metadata"> 5510<span>Added in: v10.0.0</span> 5511</div> 5512<p>Emitted when the watcher stops watching for changes. The closed 5513<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5514<h5>Event: <code>'error'</code><span><a class="mark" href="#fs_event_error" id="fs_event_error">#</a></span></h5> 5515<div class="api_metadata"> 5516<span>Added in: v0.5.8</span> 5517</div> 5518<ul> 5519<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5520</ul> 5521<p>Emitted when an error occurs while watching the file. The errored 5522<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5523<h5><code>watcher.close()</code><span><a class="mark" href="#fs_watcher_close" id="fs_watcher_close">#</a></span></h5> 5524<div class="api_metadata"> 5525<span>Added in: v0.5.8</span> 5526</div> 5527<p>Stop watching for changes on the given <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>. Once stopped, the 5528<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable.</p> 5529<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref" id="fs_watcher_ref">#</a></span></h5> 5530<div class="api_metadata"> 5531<span>Added in: v14.3.0, v12.20.0</span> 5532</div> 5533<ul> 5534<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5535</ul> 5536<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5537<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5538no effect.</p> 5539<p>By default, all <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> objects are "ref'ed", making it normally 5540unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5541called previously.</p> 5542<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref" id="fs_watcher_unref">#</a></span></h5> 5543<div class="api_metadata"> 5544<span>Added in: v14.3.0, v12.20.0</span> 5545</div> 5546<ul> 5547<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5548</ul> 5549<p>When called, the active <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object will not require the Node.js 5550event loop to remain active. If there is no other activity keeping the 5551event loop running, the process may exit before the <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object's 5552callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5553no effect.</p> 5554<h4>Class: <code>fs.StatWatcher</code><span><a class="mark" href="#fs_class_fs_statwatcher" id="fs_class_fs_statwatcher">#</a></span></h4> 5555<div class="api_metadata"> 5556<span>Added in: v14.3.0, v12.20.0</span> 5557</div> 5558<ul> 5559<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5560</ul> 5561<p>A successful call to <code>fs.watchFile()</code> method will return a new <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> 5562object.</p> 5563<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref_1" id="fs_watcher_ref_1">#</a></span></h5> 5564<div class="api_metadata"> 5565<span>Added in: v14.3.0, v12.20.0</span> 5566</div> 5567<ul> 5568<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5569</ul> 5570<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5571<a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5572no effect.</p> 5573<p>By default, all <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> objects are "ref'ed", making it normally 5574unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5575called previously.</p> 5576<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref_1" id="fs_watcher_unref_1">#</a></span></h5> 5577<div class="api_metadata"> 5578<span>Added in: v14.3.0, v12.20.0</span> 5579</div> 5580<ul> 5581<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5582</ul> 5583<p>When called, the active <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> object will not require the Node.js 5584event loop to remain active. If there is no other activity keeping the 5585event loop running, the process may exit before the <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> object's 5586callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5587no effect.</p> 5588<h4>Class: <code>fs.ReadStream</code><span><a class="mark" href="#fs_class_fs_readstream" id="fs_class_fs_readstream">#</a></span></h4> 5589<div class="api_metadata"> 5590<span>Added in: v0.1.93</span> 5591</div> 5592<ul> 5593<li>Extends: <a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li> 5594</ul> 5595<p>Instances of <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> are created and returned using the 5596<a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream()</code></a> function.</p> 5597<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_1" id="fs_event_close_1">#</a></span></h5> 5598<div class="api_metadata"> 5599<span>Added in: v0.1.93</span> 5600</div> 5601<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>'s underlying file descriptor has been closed.</p> 5602<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open" id="fs_event_open">#</a></span></h5> 5603<div class="api_metadata"> 5604<span>Added in: v0.1.93</span> 5605</div> 5606<ul> 5607<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 <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>.</li> 5608</ul> 5609<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>'s file descriptor has been opened.</p> 5610<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready" id="fs_event_ready">#</a></span></h5> 5611<div class="api_metadata"> 5612<span>Added in: v9.11.0</span> 5613</div> 5614<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> is ready to be used.</p> 5615<p>Fires immediately after <code>'open'</code>.</p> 5616<h5><code>readStream.bytesRead</code><span><a class="mark" href="#fs_readstream_bytesread" id="fs_readstream_bytesread">#</a></span></h5> 5617<div class="api_metadata"> 5618<span>Added in: v6.4.0</span> 5619</div> 5620<ul> 5621<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 5622</ul> 5623<p>The number of bytes that have been read so far.</p> 5624<h5><code>readStream.path</code><span><a class="mark" href="#fs_readstream_path" id="fs_readstream_path">#</a></span></h5> 5625<div class="api_metadata"> 5626<span>Added in: v0.1.93</span> 5627</div> 5628<ul> 5629<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> 5630</ul> 5631<p>The path to the file the stream is reading from as specified in the first 5632argument to <code>fs.createReadStream()</code>. If <code>path</code> is passed as a string, then 5633<code>readStream.path</code> will be a string. If <code>path</code> is passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>, then 5634<code>readStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 5635<h5><code>readStream.pending</code><span><a class="mark" href="#fs_readstream_pending" id="fs_readstream_pending">#</a></span></h5> 5636<div class="api_metadata"> 5637<span>Added in: v11.2.0, v10.16.0</span> 5638</div> 5639<ul> 5640<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5641</ul> 5642<p>This property is <code>true</code> if the underlying file has not been opened yet, 5643i.e. before the <code>'ready'</code> event is emitted.</p> 5644<h4>Class: <code>fs.Stats</code><span><a class="mark" href="#fs_class_fs_stats" id="fs_class_fs_stats">#</a></span></h4> 5645<div class="api_metadata"> 5646<details class="changelog"><summary>History</summary> 5647<table> 5648<tbody><tr><th>Version</th><th>Changes</th></tr> 5649<tr><td>v8.1.0</td> 5650<td><p>Added times as numbers.</p></td></tr> 5651<tr><td>v0.1.21</td> 5652<td><p><span>Added in: v0.1.21</span></p></td></tr> 5653</tbody></table> 5654</details> 5655</div> 5656<p>A <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object provides information about a file.</p> 5657<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 5658their synchronous counterparts are of this type. 5659If <code>bigint</code> in the <code>options</code> passed to those methods is true, the numeric values 5660will be <code>bigint</code> instead of <code>number</code>, and the object will contain additional 5661nanosecond-precision properties suffixed with <code>Ns</code>.</p> 5662<pre><code class="language-console">Stats { 5663 dev: 2114, 5664 ino: 48064969, 5665 mode: 33188, 5666 nlink: 1, 5667 uid: 85, 5668 gid: 100, 5669 rdev: 0, 5670 size: 527, 5671 blksize: 4096, 5672 blocks: 8, 5673 atimeMs: 1318289051000.1, 5674 mtimeMs: 1318289051000.1, 5675 ctimeMs: 1318289051000.1, 5676 birthtimeMs: 1318289051000.1, 5677 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5678 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5679 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5680 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5681<p><code>bigint</code> version:</p> 5682<pre><code class="language-console">BigIntStats { 5683 dev: 2114n, 5684 ino: 48064969n, 5685 mode: 33188n, 5686 nlink: 1n, 5687 uid: 85n, 5688 gid: 100n, 5689 rdev: 0n, 5690 size: 527n, 5691 blksize: 4096n, 5692 blocks: 8n, 5693 atimeMs: 1318289051000n, 5694 mtimeMs: 1318289051000n, 5695 ctimeMs: 1318289051000n, 5696 birthtimeMs: 1318289051000n, 5697 atimeNs: 1318289051000000000n, 5698 mtimeNs: 1318289051000000000n, 5699 ctimeNs: 1318289051000000000n, 5700 birthtimeNs: 1318289051000000000n, 5701 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5702 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5703 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5704 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5705<h5><code>stats.isBlockDevice()</code><span><a class="mark" href="#fs_stats_isblockdevice" id="fs_stats_isblockdevice">#</a></span></h5> 5706<div class="api_metadata"> 5707<span>Added in: v0.1.10</span> 5708</div> 5709<ul> 5710<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5711</ul> 5712<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a block device.</p> 5713<h5><code>stats.isCharacterDevice()</code><span><a class="mark" href="#fs_stats_ischaracterdevice" id="fs_stats_ischaracterdevice">#</a></span></h5> 5714<div class="api_metadata"> 5715<span>Added in: v0.1.10</span> 5716</div> 5717<ul> 5718<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5719</ul> 5720<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a character device.</p> 5721<h5><code>stats.isDirectory()</code><span><a class="mark" href="#fs_stats_isdirectory" id="fs_stats_isdirectory">#</a></span></h5> 5722<div class="api_metadata"> 5723<span>Added in: v0.1.10</span> 5724</div> 5725<ul> 5726<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5727</ul> 5728<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a file system directory.</p> 5729<p>If the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object was obtained from <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a>, this method will 5730always return <code>false</code>. This is because <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a> returns information 5731about a symbolic link itself and not the path it resolves to.</p> 5732<h5><code>stats.isFIFO()</code><span><a class="mark" href="#fs_stats_isfifo" id="fs_stats_isfifo">#</a></span></h5> 5733<div class="api_metadata"> 5734<span>Added in: v0.1.10</span> 5735</div> 5736<ul> 5737<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5738</ul> 5739<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a first-in-first-out (FIFO) 5740pipe.</p> 5741<h5><code>stats.isFile()</code><span><a class="mark" href="#fs_stats_isfile" id="fs_stats_isfile">#</a></span></h5> 5742<div class="api_metadata"> 5743<span>Added in: v0.1.10</span> 5744</div> 5745<ul> 5746<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5747</ul> 5748<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a regular file.</p> 5749<h5><code>stats.isSocket()</code><span><a class="mark" href="#fs_stats_issocket" id="fs_stats_issocket">#</a></span></h5> 5750<div class="api_metadata"> 5751<span>Added in: v0.1.10</span> 5752</div> 5753<ul> 5754<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5755</ul> 5756<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a socket.</p> 5757<h5><code>stats.isSymbolicLink()</code><span><a class="mark" href="#fs_stats_issymboliclink" id="fs_stats_issymboliclink">#</a></span></h5> 5758<div class="api_metadata"> 5759<span>Added in: v0.1.10</span> 5760</div> 5761<ul> 5762<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5763</ul> 5764<p>Returns <code>true</code> if the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object describes a symbolic link.</p> 5765<p>This method is only valid when using <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a>.</p> 5766<h5><code>stats.dev</code><span><a class="mark" href="#fs_stats_dev" id="fs_stats_dev">#</a></span></h5> 5767<ul> 5768<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> 5769</ul> 5770<p>The numeric identifier of the device containing the file.</p> 5771<h5><code>stats.ino</code><span><a class="mark" href="#fs_stats_ino" id="fs_stats_ino">#</a></span></h5> 5772<ul> 5773<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> 5774</ul> 5775<p>The file system specific "Inode" number for the file.</p> 5776<h5><code>stats.mode</code><span><a class="mark" href="#fs_stats_mode" id="fs_stats_mode">#</a></span></h5> 5777<ul> 5778<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> 5779</ul> 5780<p>A bit-field describing the file type and mode.</p> 5781<h5><code>stats.nlink</code><span><a class="mark" href="#fs_stats_nlink" id="fs_stats_nlink">#</a></span></h5> 5782<ul> 5783<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> 5784</ul> 5785<p>The number of hard-links that exist for the file.</p> 5786<h5><code>stats.uid</code><span><a class="mark" href="#fs_stats_uid" id="fs_stats_uid">#</a></span></h5> 5787<ul> 5788<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> 5789</ul> 5790<p>The numeric user identifier of the user that owns the file (POSIX).</p> 5791<h5><code>stats.gid</code><span><a class="mark" href="#fs_stats_gid" id="fs_stats_gid">#</a></span></h5> 5792<ul> 5793<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> 5794</ul> 5795<p>The numeric group identifier of the group that owns the file (POSIX).</p> 5796<h5><code>stats.rdev</code><span><a class="mark" href="#fs_stats_rdev" id="fs_stats_rdev">#</a></span></h5> 5797<ul> 5798<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> 5799</ul> 5800<p>A numeric device identifier if the file represents a device.</p> 5801<h5><code>stats.size</code><span><a class="mark" href="#fs_stats_size" id="fs_stats_size">#</a></span></h5> 5802<ul> 5803<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> 5804</ul> 5805<p>The size of the file in bytes.</p> 5806<h5><code>stats.blksize</code><span><a class="mark" href="#fs_stats_blksize" id="fs_stats_blksize">#</a></span></h5> 5807<ul> 5808<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> 5809</ul> 5810<p>The file system block size for i/o operations.</p> 5811<h5><code>stats.blocks</code><span><a class="mark" href="#fs_stats_blocks" id="fs_stats_blocks">#</a></span></h5> 5812<ul> 5813<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> 5814</ul> 5815<p>The number of blocks allocated for this file.</p> 5816<h5><code>stats.atimeMs</code><span><a class="mark" href="#fs_stats_atimems" id="fs_stats_atimems">#</a></span></h5> 5817<div class="api_metadata"> 5818<span>Added in: v8.1.0</span> 5819</div> 5820<ul> 5821<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> 5822</ul> 5823<p>The timestamp indicating the last time this file was accessed expressed in 5824milliseconds since the POSIX Epoch.</p> 5825<h5><code>stats.mtimeMs</code><span><a class="mark" href="#fs_stats_mtimems" id="fs_stats_mtimems">#</a></span></h5> 5826<div class="api_metadata"> 5827<span>Added in: v8.1.0</span> 5828</div> 5829<ul> 5830<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> 5831</ul> 5832<p>The timestamp indicating the last time this file was modified expressed in 5833milliseconds since the POSIX Epoch.</p> 5834<h5><code>stats.ctimeMs</code><span><a class="mark" href="#fs_stats_ctimems" id="fs_stats_ctimems">#</a></span></h5> 5835<div class="api_metadata"> 5836<span>Added in: v8.1.0</span> 5837</div> 5838<ul> 5839<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> 5840</ul> 5841<p>The timestamp indicating the last time the file status was changed expressed 5842in milliseconds since the POSIX Epoch.</p> 5843<h5><code>stats.birthtimeMs</code><span><a class="mark" href="#fs_stats_birthtimems" id="fs_stats_birthtimems">#</a></span></h5> 5844<div class="api_metadata"> 5845<span>Added in: v8.1.0</span> 5846</div> 5847<ul> 5848<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> 5849</ul> 5850<p>The timestamp indicating the creation time of this file expressed in 5851milliseconds since the POSIX Epoch.</p> 5852<h5><code>stats.atimeNs</code><span><a class="mark" href="#fs_stats_atimens" id="fs_stats_atimens">#</a></span></h5> 5853<div class="api_metadata"> 5854<span>Added in: v12.10.0</span> 5855</div> 5856<ul> 5857<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5858</ul> 5859<p>Only present when <code>bigint: true</code> is passed into the method that generates 5860the object. 5861The timestamp indicating the last time this file was accessed expressed in 5862nanoseconds since the POSIX Epoch.</p> 5863<h5><code>stats.mtimeNs</code><span><a class="mark" href="#fs_stats_mtimens" id="fs_stats_mtimens">#</a></span></h5> 5864<div class="api_metadata"> 5865<span>Added in: v12.10.0</span> 5866</div> 5867<ul> 5868<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5869</ul> 5870<p>Only present when <code>bigint: true</code> is passed into the method that generates 5871the object. 5872The timestamp indicating the last time this file was modified expressed in 5873nanoseconds since the POSIX Epoch.</p> 5874<h5><code>stats.ctimeNs</code><span><a class="mark" href="#fs_stats_ctimens" id="fs_stats_ctimens">#</a></span></h5> 5875<div class="api_metadata"> 5876<span>Added in: v12.10.0</span> 5877</div> 5878<ul> 5879<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5880</ul> 5881<p>Only present when <code>bigint: true</code> is passed into the method that generates 5882the object. 5883The timestamp indicating the last time the file status was changed expressed 5884in nanoseconds since the POSIX Epoch.</p> 5885<h5><code>stats.birthtimeNs</code><span><a class="mark" href="#fs_stats_birthtimens" id="fs_stats_birthtimens">#</a></span></h5> 5886<div class="api_metadata"> 5887<span>Added in: v12.10.0</span> 5888</div> 5889<ul> 5890<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5891</ul> 5892<p>Only present when <code>bigint: true</code> is passed into the method that generates 5893the object. 5894The timestamp indicating the creation time of this file expressed in 5895nanoseconds since the POSIX Epoch.</p> 5896<h5><code>stats.atime</code><span><a class="mark" href="#fs_stats_atime" id="fs_stats_atime">#</a></span></h5> 5897<div class="api_metadata"> 5898<span>Added in: v0.11.13</span> 5899</div> 5900<ul> 5901<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5902</ul> 5903<p>The timestamp indicating the last time this file was accessed.</p> 5904<h5><code>stats.mtime</code><span><a class="mark" href="#fs_stats_mtime" id="fs_stats_mtime">#</a></span></h5> 5905<div class="api_metadata"> 5906<span>Added in: v0.11.13</span> 5907</div> 5908<ul> 5909<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5910</ul> 5911<p>The timestamp indicating the last time this file was modified.</p> 5912<h5><code>stats.ctime</code><span><a class="mark" href="#fs_stats_ctime" id="fs_stats_ctime">#</a></span></h5> 5913<div class="api_metadata"> 5914<span>Added in: v0.11.13</span> 5915</div> 5916<ul> 5917<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5918</ul> 5919<p>The timestamp indicating the last time the file status was changed.</p> 5920<h5><code>stats.birthtime</code><span><a class="mark" href="#fs_stats_birthtime" id="fs_stats_birthtime">#</a></span></h5> 5921<div class="api_metadata"> 5922<span>Added in: v0.11.13</span> 5923</div> 5924<ul> 5925<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5926</ul> 5927<p>The timestamp indicating the creation time of this file.</p> 5928<h5>Stat time values<span><a class="mark" href="#fs_stat_time_values" id="fs_stat_time_values">#</a></span></h5> 5929<p>The <code>atimeMs</code>, <code>mtimeMs</code>, <code>ctimeMs</code>, <code>birthtimeMs</code> properties are 5930numeric values that hold the corresponding times in milliseconds. Their 5931precision is platform specific. When <code>bigint: true</code> is passed into the 5932method that generates the object, the properties will be <a href="https://tc39.github.io/proposal-bigint">bigints</a>, 5933otherwise they will be <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type">numbers</a>.</p> 5934<p>The <code>atimeNs</code>, <code>mtimeNs</code>, <code>ctimeNs</code>, <code>birthtimeNs</code> properties are 5935<a href="https://tc39.github.io/proposal-bigint">bigints</a> that hold the corresponding times in nanoseconds. They are 5936only present when <code>bigint: true</code> is passed into the method that generates 5937the object. Their precision is platform specific.</p> 5938<p><code>atime</code>, <code>mtime</code>, <code>ctime</code>, and <code>birthtime</code> are 5939<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 5940<code>Date</code> and number values are not connected. Assigning a new number value, or 5941mutating the <code>Date</code> value, will not be reflected in the corresponding alternate 5942representation.</p> 5943<p>The times in the stat object have the following semantics:</p> 5944<ul> 5945<li><code>atime</code> "Access Time": Time when file data last accessed. Changed 5946by 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> 5947<li><code>mtime</code> "Modified Time": Time when file data last modified. 5948Changed 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> 5949<li><code>ctime</code> "Change Time": Time when file status was last changed 5950(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>, 5951<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>, 5952<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> 5953<li><code>birthtime</code> "Birth Time": Time of file creation. Set once when the 5954file is created. On filesystems where birthtime is not available, 5955this field may instead hold either the <code>ctime</code> or 5956<code>1970-01-01T00:00Z</code> (ie, Unix epoch timestamp <code>0</code>). This value may be greater 5957than <code>atime</code> or <code>mtime</code> in this case. On Darwin and other FreeBSD variants, 5958also set if the <code>atime</code> is explicitly set to an earlier value than the current 5959<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> 5960</ul> 5961<p>Prior to Node.js 0.12, the <code>ctime</code> held the <code>birthtime</code> on Windows systems. As 5962of 0.12, <code>ctime</code> is not "creation time", and on Unix systems, it never was.</p> 5963<h4>Class: <code>fs.WriteStream</code><span><a class="mark" href="#fs_class_fs_writestream" id="fs_class_fs_writestream">#</a></span></h4> 5964<div class="api_metadata"> 5965<span>Added in: v0.1.93</span> 5966</div> 5967<ul> 5968<li>Extends <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li> 5969</ul> 5970<p>Instances of <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> are created and returned using the 5971<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> function.</p> 5972<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_2" id="fs_event_close_2">#</a></span></h5> 5973<div class="api_metadata"> 5974<span>Added in: v0.1.93</span> 5975</div> 5976<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a>'s underlying file descriptor has been closed.</p> 5977<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open_1" id="fs_event_open_1">#</a></span></h5> 5978<div class="api_metadata"> 5979<span>Added in: v0.1.93</span> 5980</div> 5981<ul> 5982<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 <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a>.</li> 5983</ul> 5984<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a>'s file is opened.</p> 5985<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready_1" id="fs_event_ready_1">#</a></span></h5> 5986<div class="api_metadata"> 5987<span>Added in: v9.11.0</span> 5988</div> 5989<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> is ready to be used.</p> 5990<p>Fires immediately after <code>'open'</code>.</p> 5991<h5><code>writeStream.bytesWritten</code><span><a class="mark" href="#fs_writestream_byteswritten" id="fs_writestream_byteswritten">#</a></span></h5> 5992<div class="api_metadata"> 5993<span>Added in: v0.4.7</span> 5994</div> 5995<p>The number of bytes written so far. Does not include data that is still queued 5996for writing.</p> 5997<h5><code>writeStream.close([callback])</code><span><a class="mark" href="#fs_writestream_close_callback" id="fs_writestream_close_callback">#</a></span></h5> 5998<div class="api_metadata"> 5999<span>Added in: v0.9.4</span> 6000</div> 6001<ul> 6002<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 6003<ul> 6004<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 6005</ul> 6006</li> 6007</ul> 6008<p>Closes <code>writeStream</code>. Optionally accepts a 6009callback that will be executed once the <code>writeStream</code> 6010is closed.</p> 6011<h5><code>writeStream.path</code><span><a class="mark" href="#fs_writestream_path" id="fs_writestream_path">#</a></span></h5> 6012<div class="api_metadata"> 6013<span>Added in: v0.1.93</span> 6014</div> 6015<p>The path to the file the stream is writing to as specified in the first 6016argument to <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>. If <code>path</code> is passed as a string, then 6017<code>writeStream.path</code> will be a string. If <code>path</code> is passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>, then 6018<code>writeStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 6019<h5><code>writeStream.pending</code><span><a class="mark" href="#fs_writestream_pending" id="fs_writestream_pending">#</a></span></h5> 6020<div class="api_metadata"> 6021<span>Added in: v11.2.0</span> 6022</div> 6023<ul> 6024<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 6025</ul> 6026<p>This property is <code>true</code> if the underlying file has not been opened yet, 6027i.e. before the <code>'ready'</code> event is emitted.</p> 6028<h4><code>fs.constants</code><span><a class="mark" href="#fs_fs_constants" id="fs_fs_constants">#</a></span></h4> 6029<ul> 6030<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 6031</ul> 6032<p>Returns an object containing commonly used constants for file system 6033operations.</p> 6034<h5>FS constants<span><a class="mark" href="#fs_fs_constants_1" id="fs_fs_constants_1">#</a></span></h5> 6035<p>The following constants are exported by <code>fs.constants</code>.</p> 6036<p>Not every constant will be available on every operating system.</p> 6037<p>To use more than one constant, use the bitwise OR <code>|</code> operator.</p> 6038<p>Example:</p> 6039<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6040 6041<span class="hljs-keyword">const</span> { 6042 <span class="hljs-variable constant_">O_RDWR</span>, 6043 <span class="hljs-variable constant_">O_CREAT</span>, 6044 <span class="hljs-variable constant_">O_EXCL</span> 6045} = constants; 6046 6047<span class="hljs-title function_">open</span>(<span class="hljs-string">'/path/to/my/file'</span>, <span class="hljs-variable constant_">O_RDWR</span> | <span class="hljs-variable constant_">O_CREAT</span> | <span class="hljs-variable constant_">O_EXCL</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 6048 <span class="hljs-comment">// ...</span> 6049});</code></pre> 6050<h6>File access constants<span><a class="mark" href="#fs_file_access_constants" id="fs_file_access_constants">#</a></span></h6> 6051<p>The following constants are meant for use with <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a>.</p> 6052<table> 6053 <tbody><tr> 6054 <th>Constant</th> 6055 <th>Description</th> 6056 </tr> 6057 <tr> 6058 <td><code>F_OK</code></td> 6059 <td>Flag indicating that the file is visible to the calling process. 6060 This is useful for determining if a file exists, but says nothing 6061 about <code>rwx</code> permissions. Default if no mode is specified.</td> 6062 </tr> 6063 <tr> 6064 <td><code>R_OK</code></td> 6065 <td>Flag indicating that the file can be read by the calling process.</td> 6066 </tr> 6067 <tr> 6068 <td><code>W_OK</code></td> 6069 <td>Flag indicating that the file can be written by the calling 6070 process.</td> 6071 </tr> 6072 <tr> 6073 <td><code>X_OK</code></td> 6074 <td>Flag indicating that the file can be executed by the calling 6075 process. This has no effect on Windows 6076 (will behave like <code>fs.constants.F_OK</code>).</td> 6077 </tr> 6078</tbody></table> 6079<h6>File copy constants<span><a class="mark" href="#fs_file_copy_constants" id="fs_file_copy_constants">#</a></span></h6> 6080<p>The following constants are meant for use with <a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile()</code></a>.</p> 6081<table> 6082 <tbody><tr> 6083 <th>Constant</th> 6084 <th>Description</th> 6085 </tr> 6086 <tr> 6087 <td><code>COPYFILE_EXCL</code></td> 6088 <td>If present, the copy operation will fail with an error if the 6089 destination path already exists.</td> 6090 </tr> 6091 <tr> 6092 <td><code>COPYFILE_FICLONE</code></td> 6093 <td>If present, the copy operation will attempt to create a 6094 copy-on-write reflink. If the underlying platform does not support 6095 copy-on-write, then a fallback copy mechanism is used.</td> 6096 </tr> 6097 <tr> 6098 <td><code>COPYFILE_FICLONE_FORCE</code></td> 6099 <td>If present, the copy operation will attempt to create a 6100 copy-on-write reflink. If the underlying platform does not support 6101 copy-on-write, then the operation will fail with an error.</td> 6102 </tr> 6103</tbody></table> 6104<h6>File open constants<span><a class="mark" href="#fs_file_open_constants" id="fs_file_open_constants">#</a></span></h6> 6105<p>The following constants are meant for use with <code>fs.open()</code>.</p> 6106<table> 6107 <tbody><tr> 6108 <th>Constant</th> 6109 <th>Description</th> 6110 </tr> 6111 <tr> 6112 <td><code>O_RDONLY</code></td> 6113 <td>Flag indicating to open a file for read-only access.</td> 6114 </tr> 6115 <tr> 6116 <td><code>O_WRONLY</code></td> 6117 <td>Flag indicating to open a file for write-only access.</td> 6118 </tr> 6119 <tr> 6120 <td><code>O_RDWR</code></td> 6121 <td>Flag indicating to open a file for read-write access.</td> 6122 </tr> 6123 <tr> 6124 <td><code>O_CREAT</code></td> 6125 <td>Flag indicating to create the file if it does not already exist.</td> 6126 </tr> 6127 <tr> 6128 <td><code>O_EXCL</code></td> 6129 <td>Flag indicating that opening a file should fail if the 6130 <code>O_CREAT</code> flag is set and the file already exists.</td> 6131 </tr> 6132 <tr> 6133 <td><code>O_NOCTTY</code></td> 6134 <td>Flag indicating that if path identifies a terminal device, opening the 6135 path shall not cause that terminal to become the controlling terminal for 6136 the process (if the process does not already have one).</td> 6137 </tr> 6138 <tr> 6139 <td><code>O_TRUNC</code></td> 6140 <td>Flag indicating that if the file exists and is a regular file, and the 6141 file is opened successfully for write access, its length shall be truncated 6142 to zero.</td> 6143 </tr> 6144 <tr> 6145 <td><code>O_APPEND</code></td> 6146 <td>Flag indicating that data will be appended to the end of the file.</td> 6147 </tr> 6148 <tr> 6149 <td><code>O_DIRECTORY</code></td> 6150 <td>Flag indicating that the open should fail if the path is not a 6151 directory.</td> 6152 </tr> 6153 <tr> 6154 <td><code>O_NOATIME</code></td> 6155 <td>Flag indicating reading accesses to the file system will no longer 6156 result in an update to the <code>atime</code> information associated with 6157 the file. This flag is available on Linux operating systems only.</td> 6158 </tr> 6159 <tr> 6160 <td><code>O_NOFOLLOW</code></td> 6161 <td>Flag indicating that the open should fail if the path is a symbolic 6162 link.</td> 6163 </tr> 6164 <tr> 6165 <td><code>O_SYNC</code></td> 6166 <td>Flag indicating that the file is opened for synchronized I/O with write 6167 operations waiting for file integrity.</td> 6168 </tr> 6169 <tr> 6170 <td><code>O_DSYNC</code></td> 6171 <td>Flag indicating that the file is opened for synchronized I/O with write 6172 operations waiting for data integrity.</td> 6173 </tr> 6174 <tr> 6175 <td><code>O_SYMLINK</code></td> 6176 <td>Flag indicating to open the symbolic link itself rather than the 6177 resource it is pointing to.</td> 6178 </tr> 6179 <tr> 6180 <td><code>O_DIRECT</code></td> 6181 <td>When set, an attempt will be made to minimize caching effects of file 6182 I/O.</td> 6183 </tr> 6184 <tr> 6185 <td><code>O_NONBLOCK</code></td> 6186 <td>Flag indicating to open the file in nonblocking mode when possible.</td> 6187 </tr> 6188 <tr> 6189 <td><code>UV_FS_O_FILEMAP</code></td> 6190 <td>When set, a memory file mapping is used to access the file. This flag 6191 is available on Windows operating systems only. On other operating systems, 6192 this flag is ignored.</td> 6193 </tr> 6194</tbody></table> 6195<h6>File type constants<span><a class="mark" href="#fs_file_type_constants" id="fs_file_type_constants">#</a></span></h6> 6196<p>The following constants are meant for use with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object's 6197<code>mode</code> property for determining a file's type.</p> 6198<table> 6199 <tbody><tr> 6200 <th>Constant</th> 6201 <th>Description</th> 6202 </tr> 6203 <tr> 6204 <td><code>S_IFMT</code></td> 6205 <td>Bit mask used to extract the file type code.</td> 6206 </tr> 6207 <tr> 6208 <td><code>S_IFREG</code></td> 6209 <td>File type constant for a regular file.</td> 6210 </tr> 6211 <tr> 6212 <td><code>S_IFDIR</code></td> 6213 <td>File type constant for a directory.</td> 6214 </tr> 6215 <tr> 6216 <td><code>S_IFCHR</code></td> 6217 <td>File type constant for a character-oriented device file.</td> 6218 </tr> 6219 <tr> 6220 <td><code>S_IFBLK</code></td> 6221 <td>File type constant for a block-oriented device file.</td> 6222 </tr> 6223 <tr> 6224 <td><code>S_IFIFO</code></td> 6225 <td>File type constant for a FIFO/pipe.</td> 6226 </tr> 6227 <tr> 6228 <td><code>S_IFLNK</code></td> 6229 <td>File type constant for a symbolic link.</td> 6230 </tr> 6231 <tr> 6232 <td><code>S_IFSOCK</code></td> 6233 <td>File type constant for a socket.</td> 6234 </tr> 6235</tbody></table> 6236<h6>File mode constants<span><a class="mark" href="#fs_file_mode_constants" id="fs_file_mode_constants">#</a></span></h6> 6237<p>The following constants are meant for use with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object's 6238<code>mode</code> property for determining the access permissions for a file.</p> 6239<table> 6240 <tbody><tr> 6241 <th>Constant</th> 6242 <th>Description</th> 6243 </tr> 6244 <tr> 6245 <td><code>S_IRWXU</code></td> 6246 <td>File mode indicating readable, writable, and executable by owner.</td> 6247 </tr> 6248 <tr> 6249 <td><code>S_IRUSR</code></td> 6250 <td>File mode indicating readable by owner.</td> 6251 </tr> 6252 <tr> 6253 <td><code>S_IWUSR</code></td> 6254 <td>File mode indicating writable by owner.</td> 6255 </tr> 6256 <tr> 6257 <td><code>S_IXUSR</code></td> 6258 <td>File mode indicating executable by owner.</td> 6259 </tr> 6260 <tr> 6261 <td><code>S_IRWXG</code></td> 6262 <td>File mode indicating readable, writable, and executable by group.</td> 6263 </tr> 6264 <tr> 6265 <td><code>S_IRGRP</code></td> 6266 <td>File mode indicating readable by group.</td> 6267 </tr> 6268 <tr> 6269 <td><code>S_IWGRP</code></td> 6270 <td>File mode indicating writable by group.</td> 6271 </tr> 6272 <tr> 6273 <td><code>S_IXGRP</code></td> 6274 <td>File mode indicating executable by group.</td> 6275 </tr> 6276 <tr> 6277 <td><code>S_IRWXO</code></td> 6278 <td>File mode indicating readable, writable, and executable by others.</td> 6279 </tr> 6280 <tr> 6281 <td><code>S_IROTH</code></td> 6282 <td>File mode indicating readable by others.</td> 6283 </tr> 6284 <tr> 6285 <td><code>S_IWOTH</code></td> 6286 <td>File mode indicating writable by others.</td> 6287 </tr> 6288 <tr> 6289 <td><code>S_IXOTH</code></td> 6290 <td>File mode indicating executable by others.</td> 6291 </tr> 6292</tbody></table> 6293</section><section><h3>Notes<span><a class="mark" href="#fs_notes" id="fs_notes">#</a></span></h3> 6294<h4>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></h4> 6295<p>Because they are executed asynchronously by the underlying thread pool, 6296there is no guaranteed ordering when using either the callback or 6297promise-based methods.</p> 6298<p>For example, the following is prone to error because the <code>fs.stat()</code> 6299operation might complete before the <code>fs.rename()</code> operation:</p> 6300<pre><code class="language-js">fs.<span class="hljs-title function_">rename</span>(<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> { 6301 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6302 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'renamed complete'</span>); 6303}); 6304fs.<span class="hljs-title function_">stat</span>(<span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> { 6305 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6306 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>); 6307});</code></pre> 6308<p>It is important to correctly order the operations by awaiting the results 6309of one before invoking the other:</p> 6310 6311<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { rename, stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 6312 6313<span class="hljs-keyword">const</span> <span class="hljs-keyword">from</span> = <span class="hljs-string">'/tmp/hello'</span>; 6314<span class="hljs-keyword">const</span> to = <span class="hljs-string">'/tmp/world'</span>; 6315 6316<span class="hljs-keyword">try</span> { 6317 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6318 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6319 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>); 6320} <span class="hljs-keyword">catch</span> (error) { 6321 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'there was an error:'</span>, error.<span class="hljs-property">message</span>); 6322}</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { rename, stat } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs/promises'</span>); 6323 6324(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params"><span class="hljs-keyword">from</span>, to</span>) { 6325 <span class="hljs-keyword">try</span> { 6326 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6327 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6328 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>); 6329 } <span class="hljs-keyword">catch</span> (error) { 6330 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'there was an error:'</span>, error.<span class="hljs-property">message</span>); 6331 } 6332})(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>);</code></pre> 6333<p>Or, when using the callback APIs, move the <code>fs.stat()</code> call into the callback 6334of the <code>fs.rename()</code> operation:</p> 6335 6336<pre><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { rename, stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6337 6338<span class="hljs-title function_">rename</span>(<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> { 6339 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6340 <span class="hljs-title function_">stat</span>(<span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> { 6341 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6342 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>); 6343 }); 6344});</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { rename, stat } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'fs/promises'</span>); 6345 6346<span class="hljs-title function_">rename</span>(<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> { 6347 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6348 <span class="hljs-title function_">stat</span>(<span class="hljs-string">'/tmp/world'</span>, <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> { 6349 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6350 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`stats: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(stats)}</span>`</span>); 6351 }); 6352});</code></pre> 6353<h4>File paths<span><a class="mark" href="#fs_file_paths" id="fs_file_paths">#</a></span></h4> 6354<p>Most <code>fs</code> operations accept file paths that may be specified in the form of 6355a string, a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>, or a <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> object using the <code>file:</code> protocol.</p> 6356<h5>String paths<span><a class="mark" href="#fs_string_paths" id="fs_string_paths">#</a></span></h5> 6357<p>String form paths are interpreted as UTF-8 character sequences identifying 6358the absolute or relative filename. Relative paths will be resolved relative 6359to the current working directory as determined by calling <code>process.cwd()</code>.</p> 6360<p>Example using an absolute path on POSIX:</p> 6361<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 6362 6363<span class="hljs-keyword">let</span> fd; 6364<span class="hljs-keyword">try</span> { 6365 fd = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-string">'/open/some/file.txt'</span>, <span class="hljs-string">'r'</span>); 6366 <span class="hljs-comment">// Do something with the file</span> 6367} <span class="hljs-keyword">finally</span> { 6368 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6369}</code></pre> 6370<p>Example using a relative path on POSIX (relative to <code>process.cwd()</code>):</p> 6371<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 6372 6373<span class="hljs-keyword">let</span> fd; 6374<span class="hljs-keyword">try</span> { 6375 fd = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-string">'file.txt'</span>, <span class="hljs-string">'r'</span>); 6376 <span class="hljs-comment">// Do something with the file</span> 6377} <span class="hljs-keyword">finally</span> { 6378 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6379}</code></pre> 6380<h5>File URL paths<span><a class="mark" href="#fs_file_url_paths" id="fs_file_url_paths">#</a></span></h5> 6381<div class="api_metadata"> 6382<span>Added in: v7.6.0</span> 6383</div> 6384<p>For most <code>fs</code> module functions, the <code>path</code> or <code>filename</code> argument may be passed 6385as a <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> object using the <code>file:</code> protocol.</p> 6386<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6387 6388<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///tmp/hello'</span>));</code></pre> 6389<p><code>file:</code> URLs are always absolute paths.</p> 6390<h6>Platform-specific considerations<span><a class="mark" href="#fs_platform_specific_considerations" id="fs_platform_specific_considerations">#</a></span></h6> 6391<p>On Windows, <code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s with a host name convert to UNC paths, while <code>file:</code> 6392<a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s with drive letters convert to local absolute paths. <code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s 6393without a host name nor a drive letter will result in an error:</p> 6394<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6395<span class="hljs-comment">// On Windows :</span> 6396 6397<span class="hljs-comment">// - WHATWG file URLs with hostname convert to UNC path</span> 6398<span class="hljs-comment">// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file</span> 6399<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file://hostname/p/a/t/h/file'</span>)); 6400 6401<span class="hljs-comment">// - WHATWG file URLs with drive letters convert to absolute path</span> 6402<span class="hljs-comment">// file:///C:/tmp/hello => C:\tmp\hello</span> 6403<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///C:/tmp/hello'</span>)); 6404 6405<span class="hljs-comment">// - WHATWG file URLs without hostname must have a drive letters</span> 6406<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///notdriveletter/p/a/t/h/file'</span>)); 6407<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///c/p/a/t/h/file'</span>)); 6408<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute</span></code></pre> 6409<p><code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s with drive letters must use <code>:</code> as a separator just after 6410the drive letter. Using another separator will result in an error.</p> 6411<p>On all other platforms, <code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s with a host name are unsupported and 6412will result in an error:</p> 6413<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6414<span class="hljs-comment">// On other platforms:</span> 6415 6416<span class="hljs-comment">// - WHATWG file URLs with hostname are unsupported</span> 6417<span class="hljs-comment">// file://hostname/p/a/t/h/file => throw!</span> 6418<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file://hostname/p/a/t/h/file'</span>)); 6419<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute</span> 6420 6421<span class="hljs-comment">// - WHATWG file URLs convert to absolute path</span> 6422<span class="hljs-comment">// file:///tmp/hello => /tmp/hello</span> 6423<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///tmp/hello'</span>));</code></pre> 6424<p>A <code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> having encoded slash characters will result in an error on all 6425platforms:</p> 6426<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6427 6428<span class="hljs-comment">// On Windows</span> 6429<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///C:/p/a/t/h/%2F'</span>)); 6430<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///C:/p/a/t/h/%2f'</span>)); 6431<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6432\ or / characters */</span> 6433 6434<span class="hljs-comment">// On POSIX</span> 6435<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///p/a/t/h/%2F'</span>)); 6436<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///p/a/t/h/%2f'</span>)); 6437<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6438/ characters */</span></code></pre> 6439<p>On Windows, <code>file:</code> <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a>s having encoded backslash will result in an error:</p> 6440<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { readFileSync } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6441 6442<span class="hljs-comment">// On Windows</span> 6443<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///C:/path/%5C'</span>)); 6444<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///C:/path/%5c'</span>)); 6445<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6446\ or / characters */</span></code></pre> 6447<h5>Buffer paths<span><a class="mark" href="#fs_buffer_paths" id="fs_buffer_paths">#</a></span></h5> 6448<p>Paths specified using a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> are useful primarily on certain POSIX 6449operating systems that treat file paths as opaque byte sequences. On such 6450systems, it is possible for a single file path to contain sub-sequences that 6451use multiple character encodings. As with string paths, <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> paths may 6452be relative or absolute:</p> 6453<p>Example using an absolute path on POSIX:</p> 6454<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 6455 6456<span class="hljs-keyword">let</span> fd; 6457<span class="hljs-keyword">try</span> { 6458 fd = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(<span class="hljs-string">'/open/some/file.txt'</span>), <span class="hljs-string">'r'</span>); 6459 <span class="hljs-comment">// Do something with the file</span> 6460} <span class="hljs-keyword">finally</span> { 6461 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6462}</code></pre> 6463<h5>Per-drive working directories on Windows<span><a class="mark" href="#fs_per_drive_working_directories_on_windows" id="fs_per_drive_working_directories_on_windows">#</a></span></h5> 6464<p>On Windows, Node.js follows the concept of per-drive working directory. This 6465behavior can be observed when using a drive path without a backslash. For 6466example <code>fs.readdirSync('C:\\')</code> can potentially return a different result than 6467<code>fs.readdirSync('C:')</code>. For more information, see 6468<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths">this MSDN page</a>.</p> 6469<h4>File descriptors<span><a class="mark" href="#fs_file_descriptors_1" id="fs_file_descriptors_1">#</a></span></h4> 6470<p>On POSIX systems, for every process, the kernel maintains a table of currently 6471open files and resources. Each open file is assigned a simple numeric 6472identifier called a <em>file descriptor</em>. At the system-level, all file system 6473operations use these file descriptors to identify and track each specific 6474file. Windows systems use a different but conceptually similar mechanism for 6475tracking resources. To simplify things for users, Node.js abstracts away the 6476differences between operating systems and assigns all open files a numeric file 6477descriptor.</p> 6478<p>The callback-based <code>fs.open()</code>, and synchronous <code>fs.openSync()</code> methods open a 6479file and allocate a new file descriptor. Once allocated, the file descriptor may 6480be used to read data from, write data to, or request information about the file.</p> 6481<p>Operating systems limit the number of file descriptors that may be open 6482at any given time so it is critical to close the descriptor when operations 6483are completed. Failure to do so will result in a memory leak that will 6484eventually cause an application to crash.</p> 6485<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open, close, fstat } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 6486 6487<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 6488 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 6489 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6490 }); 6491} 6492 6493<span class="hljs-title function_">open</span>(<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> { 6494 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6495 <span class="hljs-keyword">try</span> { 6496 <span class="hljs-title function_">fstat</span>(fd, <span class="hljs-function">(<span class="hljs-params">err, stat</span>) =></span> { 6497 <span class="hljs-keyword">if</span> (err) { 6498 <span class="hljs-title function_">closeFd</span>(fd); 6499 <span class="hljs-keyword">throw</span> err; 6500 } 6501 6502 <span class="hljs-comment">// use stat</span> 6503 6504 <span class="hljs-title function_">closeFd</span>(fd); 6505 }); 6506 } <span class="hljs-keyword">catch</span> (err) { 6507 <span class="hljs-title function_">closeFd</span>(fd); 6508 <span class="hljs-keyword">throw</span> err; 6509 } 6510});</code></pre> 6511<p>The promise-based APIs use a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object in place of the numeric 6512file descriptor. These objects are better managed by the system to ensure 6513that resources are not leaked. However, it is still required that they are 6514closed when operations are completed:</p> 6515<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { open } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 6516 6517<span class="hljs-keyword">let</span> file; 6518<span class="hljs-keyword">try</span> { 6519 file = <span class="hljs-keyword">await</span> <span class="hljs-title function_">open</span>(<span class="hljs-string">'/open/some/file.txt'</span>, <span class="hljs-string">'r'</span>); 6520 <span class="hljs-keyword">const</span> stat = <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">stat</span>(); 6521 <span class="hljs-comment">// use stat</span> 6522} <span class="hljs-keyword">finally</span> { 6523 <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">close</span>(); 6524}</code></pre> 6525<h4>Threadpool usage<span><a class="mark" href="#fs_threadpool_usage" id="fs_threadpool_usage">#</a></span></h4> 6526<p>All callback and promise-based file system APIs ( with the exception of 6527<code>fs.FSWatcher()</code>) use libuv's threadpool. This can have surprising and negative 6528performance implications for some applications. See the 6529<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p> 6530<h4>File system flags<span><a class="mark" href="#fs_file_system_flags" id="fs_file_system_flags">#</a></span></h4> 6531<p>The following flags are available wherever the <code>flag</code> option takes a 6532string.</p> 6533<ul> 6534<li> 6535<p><code>'a'</code>: Open file for appending. 6536The file is created if it does not exist.</p> 6537</li> 6538<li> 6539<p><code>'ax'</code>: Like <code>'a'</code> but fails if the path exists.</p> 6540</li> 6541<li> 6542<p><code>'a+'</code>: Open file for reading and appending. 6543The file is created if it does not exist.</p> 6544</li> 6545<li> 6546<p><code>'ax+'</code>: Like <code>'a+'</code> but fails if the path exists.</p> 6547</li> 6548<li> 6549<p><code>'as'</code>: Open file for appending in synchronous mode. 6550The file is created if it does not exist.</p> 6551</li> 6552<li> 6553<p><code>'as+'</code>: Open file for reading and appending in synchronous mode. 6554The file is created if it does not exist.</p> 6555</li> 6556<li> 6557<p><code>'r'</code>: Open file for reading. 6558An exception occurs if the file does not exist.</p> 6559</li> 6560<li> 6561<p><code>'r+'</code>: Open file for reading and writing. 6562An exception occurs if the file does not exist.</p> 6563</li> 6564<li> 6565<p><code>'rs+'</code>: Open file for reading and writing in synchronous mode. Instructs 6566the operating system to bypass the local file system cache.</p> 6567<p>This is primarily useful for opening files on NFS mounts as it allows 6568skipping the potentially stale local cache. It has a very real impact on 6569I/O performance so using this flag is not recommended unless it is needed.</p> 6570<p>This doesn't turn <code>fs.open()</code> or <code>fsPromises.open()</code> into a synchronous 6571blocking call. If synchronous operation is desired, something like 6572<code>fs.openSync()</code> should be used.</p> 6573</li> 6574<li> 6575<p><code>'w'</code>: Open file for writing. 6576The file is created (if it does not exist) or truncated (if it exists).</p> 6577</li> 6578<li> 6579<p><code>'wx'</code>: Like <code>'w'</code> but fails if the path exists.</p> 6580</li> 6581<li> 6582<p><code>'w+'</code>: Open file for reading and writing. 6583The file is created (if it does not exist) or truncated (if it exists).</p> 6584</li> 6585<li> 6586<p><code>'wx+'</code>: Like <code>'w+'</code> but fails if the path exists.</p> 6587</li> 6588</ul> 6589<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 6590are available from <code>fs.constants</code>. On Windows, flags are translated to 6591their equivalent ones where applicable, e.g. <code>O_WRONLY</code> to <code>FILE_GENERIC_WRITE</code>, 6592or <code>O_EXCL|O_CREAT</code> to <code>CREATE_NEW</code>, as accepted by <code>CreateFileW</code>.</p> 6593<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 6594return an error if the path already exists. On POSIX, if the path is a symbolic 6595link, using <code>O_EXCL</code> returns an error even if the link is to a path that does 6596not exist. The exclusive flag might not work with network file systems.</p> 6597<p>On Linux, positional writes don't work when the file is opened in append mode. 6598The kernel ignores the position argument and always appends the data to 6599the end of the file.</p> 6600<p>Modifying a file rather than replacing it may require the <code>flag</code> option to be 6601set to <code>'r+'</code> rather than the default <code>'w'</code>.</p> 6602<p>The behavior of some flags are platform-specific. As such, opening a directory 6603on macOS and Linux with the <code>'a+'</code> flag, as in the example below, will return an 6604error. In contrast, on Windows and FreeBSD, a file descriptor or a <code>FileHandle</code> 6605will be returned.</p> 6606<pre><code class="language-js"><span class="hljs-comment">// macOS and Linux</span> 6607fs.<span class="hljs-title function_">open</span>(<span class="hljs-string">'<directory>'</span>, <span class="hljs-string">'a+'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 6608 <span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, open <directory>]</span> 6609}); 6610 6611<span class="hljs-comment">// Windows and FreeBSD</span> 6612fs.<span class="hljs-title function_">open</span>(<span class="hljs-string">'<directory>'</span>, <span class="hljs-string">'a+'</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 6613 <span class="hljs-comment">// => null, <fd></span> 6614});</code></pre> 6615<p>On Windows, opening an existing hidden file using the <code>'w'</code> flag (either 6616through <code>fs.open()</code> or <code>fs.writeFile()</code> or <code>fsPromises.open()</code>) will fail with 6617<code>EPERM</code>. Existing hidden files can be opened for writing with the <code>'r+'</code> flag.</p> 6618<p>A call to <code>fs.ftruncate()</code> or <code>filehandle.truncate()</code> can be used to reset 6619the file contents.</p></section> 6620 <!-- API END --> 6621 </div> 6622 </div> 6623 </div> 6624 <script> 6625 'use strict'; 6626 { 6627 const kCustomPreference = 'customDarkTheme'; 6628 const userSettings = sessionStorage.getItem(kCustomPreference); 6629 const themeToggleButton = document.getElementById('theme-toggle-btn'); 6630 if (userSettings === null && window.matchMedia) { 6631 const mq = window.matchMedia('(prefers-color-scheme: dark)'); 6632 if ('onchange' in mq) { 6633 function mqChangeListener(e) { 6634 document.body.classList.toggle('dark-mode', e.matches); 6635 } 6636 mq.addEventListener('change', mqChangeListener); 6637 if (themeToggleButton) { 6638 themeToggleButton.addEventListener('click', function() { 6639 mq.removeEventListener('change', mqChangeListener); 6640 }, { once: true }); 6641 } 6642 } 6643 if (mq.matches) { 6644 document.body.classList.add('dark-mode'); 6645 } 6646 } else if (userSettings === 'true') { 6647 document.body.classList.add('dark-mode'); 6648 } 6649 if (themeToggleButton) { 6650 themeToggleButton.hidden = false; 6651 themeToggleButton.addEventListener('click', function() { 6652 sessionStorage.setItem( 6653 kCustomPreference, 6654 document.body.classList.toggle('dark-mode') 6655 ); 6656 }); 6657 } 6658 } 6659 </script> 6660</body> 6661</html> 6662