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.21.2"> 7 <title>File system | Node.js v14.21.2 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.21.2 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-v19.x/api/fs.html">19.x</a></li> 120<li><a href="https://nodejs.org/docs/latest-v18.x/api/fs.html">18.x <b>LTS</b></a></li> 121<li><a href="https://nodejs.org/docs/latest-v17.x/api/fs.html">17.x</a></li> 122<li><a href="https://nodejs.org/docs/latest-v16.x/api/fs.html">16.x <b>LTS</b></a></li> 123<li><a href="https://nodejs.org/docs/latest-v15.x/api/fs.html">15.x</a></li> 124<li><a href="https://nodejs.org/docs/latest-v14.x/api/fs.html">14.x <b>LTS</b></a></li> 125<li><a href="https://nodejs.org/docs/latest-v13.x/api/fs.html">13.x</a></li> 126<li><a href="https://nodejs.org/docs/latest-v12.x/api/fs.html">12.x</a></li> 127<li><a href="https://nodejs.org/docs/latest-v11.x/api/fs.html">11.x</a></li> 128<li><a href="https://nodejs.org/docs/latest-v10.x/api/fs.html">10.x</a></li> 129<li><a href="https://nodejs.org/docs/latest-v9.x/api/fs.html">9.x</a></li> 130<li><a href="https://nodejs.org/docs/latest-v8.x/api/fs.html">8.x</a></li> 131<li><a href="https://nodejs.org/docs/latest-v7.x/api/fs.html">7.x</a></li> 132<li><a href="https://nodejs.org/docs/latest-v6.x/api/fs.html">6.x</a></li> 133<li><a href="https://nodejs.org/docs/latest-v5.x/api/fs.html">5.x</a></li> 134<li><a href="https://nodejs.org/docs/latest-v4.x/api/fs.html">4.x</a></li> 135<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/fs.html">0.12.x</a></li> 136<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/fs.html">0.10.x</a></li></ol> 137 </li> 138 139 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/fs.md">Edit on GitHub</a></li> 140 </ul> 141 </div> 142 <hr> 143 </header> 144 145 <details id="toc" open><summary>Table of contents</summary><ul> 146<li><span class="stability_2"><a href="#fs_file_system">File system</a></span> 147<ul> 148<li><a href="#fs_promise_example">Promise example</a></li> 149<li><a href="#fs_callback_example">Callback example</a></li> 150<li><a href="#fs_synchronous_example">Synchronous example</a></li> 151<li><a href="#fs_promises_api">Promises API</a> 152<ul> 153<li><a href="#fs_class_filehandle">Class: <code>FileHandle</code></a> 154<ul> 155<li><a href="#fs_filehandle_appendfile_data_options"><code>filehandle.appendFile(data[, options])</code></a></li> 156<li><a href="#fs_filehandle_chmod_mode"><code>filehandle.chmod(mode)</code></a></li> 157<li><a href="#fs_filehandle_chown_uid_gid"><code>filehandle.chown(uid, gid)</code></a></li> 158<li><a href="#fs_filehandle_close"><code>filehandle.close()</code></a></li> 159<li><a href="#fs_filehandle_datasync"><code>filehandle.datasync()</code></a></li> 160<li><a href="#fs_filehandle_fd"><code>filehandle.fd</code></a></li> 161<li><a href="#fs_filehandle_read_buffer_offset_length_position"><code>filehandle.read(buffer, offset, length, position)</code></a></li> 162<li><a href="#fs_filehandle_read_options"><code>filehandle.read([options])</code></a></li> 163<li><a href="#fs_filehandle_readfile_options"><code>filehandle.readFile(options)</code></a></li> 164<li><a href="#fs_filehandle_readv_buffers_position"><code>filehandle.readv(buffers[, position])</code></a></li> 165<li><a href="#fs_filehandle_stat_options"><code>filehandle.stat([options])</code></a></li> 166<li><a href="#fs_filehandle_sync"><code>filehandle.sync()</code></a></li> 167<li><a href="#fs_filehandle_truncate_len"><code>filehandle.truncate(len)</code></a></li> 168<li><a href="#fs_filehandle_utimes_atime_mtime"><code>filehandle.utimes(atime, mtime)</code></a></li> 169<li><a href="#fs_filehandle_write_buffer_offset_length_position"><code>filehandle.write(buffer[, offset[, length[, position]]])</code></a></li> 170<li><a href="#fs_filehandle_write_string_position_encoding"><code>filehandle.write(string[, position[, encoding]])</code></a></li> 171<li><a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile(data, options)</code></a></li> 172<li><a href="#fs_filehandle_writev_buffers_position"><code>filehandle.writev(buffers[, position])</code></a></li> 173</ul> 174</li> 175<li><a href="#fs_fspromises_access_path_mode"><code>fsPromises.access(path[, mode])</code></a></li> 176<li><a href="#fs_fspromises_appendfile_path_data_options"><code>fsPromises.appendFile(path, data[, options])</code></a></li> 177<li><a href="#fs_fspromises_chmod_path_mode"><code>fsPromises.chmod(path, mode)</code></a></li> 178<li><a href="#fs_fspromises_chown_path_uid_gid"><code>fsPromises.chown(path, uid, gid)</code></a></li> 179<li><a href="#fs_fspromises_copyfile_src_dest_mode"><code>fsPromises.copyFile(src, dest[, mode])</code></a></li> 180<li><a href="#fs_fspromises_lchmod_path_mode"><code>fsPromises.lchmod(path, mode)</code></a></li> 181<li><a href="#fs_fspromises_lchown_path_uid_gid"><code>fsPromises.lchown(path, uid, gid)</code></a></li> 182<li><a href="#fs_fspromises_lutimes_path_atime_mtime"><code>fsPromises.lutimes(path, atime, mtime)</code></a></li> 183<li><a href="#fs_fspromises_link_existingpath_newpath"><code>fsPromises.link(existingPath, newPath)</code></a></li> 184<li><a href="#fs_fspromises_lstat_path_options"><code>fsPromises.lstat(path[, options])</code></a></li> 185<li><a href="#fs_fspromises_mkdir_path_options"><code>fsPromises.mkdir(path[, options])</code></a></li> 186<li><a href="#fs_fspromises_mkdtemp_prefix_options"><code>fsPromises.mkdtemp(prefix[, options])</code></a></li> 187<li><a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open(path, flags[, mode])</code></a></li> 188<li><a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir(path[, options])</code></a></li> 189<li><a href="#fs_fspromises_readdir_path_options"><code>fsPromises.readdir(path[, options])</code></a></li> 190<li><a href="#fs_fspromises_readfile_path_options"><code>fsPromises.readFile(path[, options])</code></a></li> 191<li><a href="#fs_fspromises_readlink_path_options"><code>fsPromises.readlink(path[, options])</code></a></li> 192<li><a href="#fs_fspromises_realpath_path_options"><code>fsPromises.realpath(path[, options])</code></a></li> 193<li><a href="#fs_fspromises_rename_oldpath_newpath"><code>fsPromises.rename(oldPath, newPath)</code></a></li> 194<li><a href="#fs_fspromises_rmdir_path_options"><code>fsPromises.rmdir(path[, options])</code></a></li> 195<li><a href="#fs_fspromises_rm_path_options"><code>fsPromises.rm(path[, options])</code></a></li> 196<li><a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat(path[, options])</code></a></li> 197<li><a href="#fs_fspromises_symlink_target_path_type"><code>fsPromises.symlink(target, path[, type])</code></a></li> 198<li><a href="#fs_fspromises_truncate_path_len"><code>fsPromises.truncate(path[, len])</code></a></li> 199<li><a href="#fs_fspromises_unlink_path"><code>fsPromises.unlink(path)</code></a></li> 200<li><a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes(path, atime, mtime)</code></a></li> 201<li><a href="#fs_fspromises_watch_filename_options"><code>fsPromises.watch(filename[, options])</code></a></li> 202<li><a href="#fs_fspromises_writefile_file_data_options"><code>fsPromises.writeFile(file, data[, options])</code></a></li> 203</ul> 204</li> 205<li><a href="#fs_callback_api">Callback API</a> 206<ul> 207<li><a href="#fs_fs_access_path_mode_callback"><code>fs.access(path[, mode], callback)</code></a></li> 208<li><a href="#fs_fs_appendfile_path_data_options_callback"><code>fs.appendFile(path, data[, options], callback)</code></a></li> 209<li><a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod(path, mode, callback)</code></a> 210<ul> 211<li><a href="#fs_file_modes">File modes</a></li> 212</ul> 213</li> 214<li><a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown(path, uid, gid, callback)</code></a></li> 215<li><a href="#fs_fs_close_fd_callback"><code>fs.close(fd[, callback])</code></a></li> 216<li><a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile(src, dest[, mode], callback)</code></a></li> 217<li><a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream(path[, options])</code></a></li> 218<li><a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream(path[, options])</code></a></li> 219<li><span class="stability_0"><a href="#fs_fs_exists_path_callback"><code>fs.exists(path, callback)</code></a></span></li> 220<li><a href="#fs_fs_fchmod_fd_mode_callback"><code>fs.fchmod(fd, mode, callback)</code></a></li> 221<li><a href="#fs_fs_fchown_fd_uid_gid_callback"><code>fs.fchown(fd, uid, gid, callback)</code></a></li> 222<li><a href="#fs_fs_fdatasync_fd_callback"><code>fs.fdatasync(fd, callback)</code></a></li> 223<li><a href="#fs_fs_fstat_fd_options_callback"><code>fs.fstat(fd[, options], callback)</code></a></li> 224<li><a href="#fs_fs_fsync_fd_callback"><code>fs.fsync(fd, callback)</code></a></li> 225<li><a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate(fd[, len], callback)</code></a></li> 226<li><a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes(fd, atime, mtime, callback)</code></a></li> 227<li><a href="#fs_fs_lchmod_path_mode_callback"><code>fs.lchmod(path, mode, callback)</code></a></li> 228<li><a href="#fs_fs_lchown_path_uid_gid_callback"><code>fs.lchown(path, uid, gid, callback)</code></a></li> 229<li><a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes(path, atime, mtime, callback)</code></a></li> 230<li><a href="#fs_fs_link_existingpath_newpath_callback"><code>fs.link(existingPath, newPath, callback)</code></a></li> 231<li><a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat(path[, options], callback)</code></a></li> 232<li><a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir(path[, options], callback)</code></a></li> 233<li><a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp(prefix[, options], callback)</code></a></li> 234<li><a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open(path[, flags[, mode]], callback)</code></a></li> 235<li><a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir(path[, options], callback)</code></a></li> 236<li><a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read(fd, buffer, offset, length, position, callback)</code></a></li> 237<li><a href="#fs_fs_read_fd_options_callback"><code>fs.read(fd, [options,] callback)</code></a></li> 238<li><a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir(path[, options], callback)</code></a></li> 239<li><a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile(path[, options], callback)</code></a> 240<ul> 241<li><a href="#fs_file_descriptors">File descriptors</a></li> 242<li><a href="#fs_performance_considerations">Performance Considerations</a></li> 243</ul> 244</li> 245<li><a href="#fs_fs_readlink_path_options_callback"><code>fs.readlink(path[, options], callback)</code></a></li> 246<li><a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv(fd, buffers[, position], callback)</code></a></li> 247<li><a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath(path[, options], callback)</code></a></li> 248<li><a href="#fs_fs_realpath_native_path_options_callback"><code>fs.realpath.native(path[, options], callback)</code></a></li> 249<li><a href="#fs_fs_rename_oldpath_newpath_callback"><code>fs.rename(oldPath, newPath, callback)</code></a></li> 250<li><a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir(path[, options], callback)</code></a></li> 251<li><a href="#fs_fs_rm_path_options_callback"><code>fs.rm(path[, options], callback)</code></a></li> 252<li><a href="#fs_fs_stat_path_options_callback"><code>fs.stat(path[, options], callback)</code></a></li> 253<li><a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink(target, path[, type], callback)</code></a></li> 254<li><a href="#fs_fs_truncate_path_len_callback"><code>fs.truncate(path[, len], callback)</code></a></li> 255<li><a href="#fs_fs_unlink_path_callback"><code>fs.unlink(path, callback)</code></a></li> 256<li><a href="#fs_fs_unwatchfile_filename_listener"><code>fs.unwatchFile(filename[, listener])</code></a></li> 257<li><a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes(path, atime, mtime, callback)</code></a></li> 258<li><a href="#fs_fs_watch_filename_options_listener"><code>fs.watch(filename[, options][, listener])</code></a> 259<ul> 260<li><a href="#fs_caveats">Caveats</a> 261<ul> 262<li><a href="#fs_availability">Availability</a></li> 263<li><a href="#fs_inodes">Inodes</a></li> 264<li><a href="#fs_filename_argument">Filename argument</a></li> 265</ul> 266</li> 267</ul> 268</li> 269<li><a href="#fs_fs_watchfile_filename_options_listener"><code>fs.watchFile(filename[, options], listener)</code></a></li> 270<li><a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer[, offset[, length[, position]]], callback)</code></a></li> 271<li><a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string[, position[, encoding]], callback)</code></a></li> 272<li><a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile(file, data[, options], callback)</code></a> 273<ul> 274<li><a href="#fs_using_fs_writefile_with_file_descriptors">Using <code>fs.writeFile()</code> with file descriptors</a></li> 275</ul> 276</li> 277<li><a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev(fd, buffers[, position], callback)</code></a></li> 278</ul> 279</li> 280<li><a href="#fs_synchronous_api">Synchronous API</a> 281<ul> 282<li><a href="#fs_fs_accesssync_path_mode"><code>fs.accessSync(path[, mode])</code></a></li> 283<li><a href="#fs_fs_appendfilesync_path_data_options"><code>fs.appendFileSync(path, data[, options])</code></a></li> 284<li><a href="#fs_fs_chmodsync_path_mode"><code>fs.chmodSync(path, mode)</code></a></li> 285<li><a href="#fs_fs_chownsync_path_uid_gid"><code>fs.chownSync(path, uid, gid)</code></a></li> 286<li><a href="#fs_fs_closesync_fd"><code>fs.closeSync(fd)</code></a></li> 287<li><a href="#fs_fs_copyfilesync_src_dest_mode"><code>fs.copyFileSync(src, dest[, mode])</code></a></li> 288<li><a href="#fs_fs_existssync_path"><code>fs.existsSync(path)</code></a></li> 289<li><a href="#fs_fs_fchmodsync_fd_mode"><code>fs.fchmodSync(fd, mode)</code></a></li> 290<li><a href="#fs_fs_fchownsync_fd_uid_gid"><code>fs.fchownSync(fd, uid, gid)</code></a></li> 291<li><a href="#fs_fs_fdatasyncsync_fd"><code>fs.fdatasyncSync(fd)</code></a></li> 292<li><a href="#fs_fs_fstatsync_fd_options"><code>fs.fstatSync(fd[, options])</code></a></li> 293<li><a href="#fs_fs_fsyncsync_fd"><code>fs.fsyncSync(fd)</code></a></li> 294<li><a href="#fs_fs_ftruncatesync_fd_len"><code>fs.ftruncateSync(fd[, len])</code></a></li> 295<li><a href="#fs_fs_futimessync_fd_atime_mtime"><code>fs.futimesSync(fd, atime, mtime)</code></a></li> 296<li><a href="#fs_fs_lchmodsync_path_mode"><code>fs.lchmodSync(path, mode)</code></a></li> 297<li><a href="#fs_fs_lchownsync_path_uid_gid"><code>fs.lchownSync(path, uid, gid)</code></a></li> 298<li><a href="#fs_fs_lutimessync_path_atime_mtime"><code>fs.lutimesSync(path, atime, mtime)</code></a></li> 299<li><a href="#fs_fs_linksync_existingpath_newpath"><code>fs.linkSync(existingPath, newPath)</code></a></li> 300<li><a href="#fs_fs_lstatsync_path_options"><code>fs.lstatSync(path[, options])</code></a></li> 301<li><a href="#fs_fs_mkdirsync_path_options"><code>fs.mkdirSync(path[, options])</code></a></li> 302<li><a href="#fs_fs_mkdtempsync_prefix_options"><code>fs.mkdtempSync(prefix[, options])</code></a></li> 303<li><a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync(path[, options])</code></a></li> 304<li><a href="#fs_fs_opensync_path_flags_mode"><code>fs.openSync(path[, flags[, mode]])</code></a></li> 305<li><a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync(path[, options])</code></a></li> 306<li><a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync(path[, options])</code></a></li> 307<li><a href="#fs_fs_readlinksync_path_options"><code>fs.readlinkSync(path[, options])</code></a></li> 308<li><a href="#fs_fs_readsync_fd_buffer_offset_length_position"><code>fs.readSync(fd, buffer, offset, length, position)</code></a></li> 309<li><a href="#fs_fs_readsync_fd_buffer_options"><code>fs.readSync(fd, buffer, [options])</code></a></li> 310<li><a href="#fs_fs_readvsync_fd_buffers_position"><code>fs.readvSync(fd, buffers[, position])</code></a></li> 311<li><a href="#fs_fs_realpathsync_path_options"><code>fs.realpathSync(path[, options])</code></a></li> 312<li><a href="#fs_fs_realpathsync_native_path_options"><code>fs.realpathSync.native(path[, options])</code></a></li> 313<li><a href="#fs_fs_renamesync_oldpath_newpath"><code>fs.renameSync(oldPath, newPath)</code></a></li> 314<li><a href="#fs_fs_rmdirsync_path_options"><code>fs.rmdirSync(path[, options])</code></a></li> 315<li><a href="#fs_fs_rmsync_path_options"><code>fs.rmSync(path[, options])</code></a></li> 316<li><a href="#fs_fs_statsync_path_options"><code>fs.statSync(path[, options])</code></a></li> 317<li><a href="#fs_fs_symlinksync_target_path_type"><code>fs.symlinkSync(target, path[, type])</code></a></li> 318<li><a href="#fs_fs_truncatesync_path_len"><code>fs.truncateSync(path[, len])</code></a></li> 319<li><a href="#fs_fs_unlinksync_path"><code>fs.unlinkSync(path)</code></a></li> 320<li><a href="#fs_fs_utimessync_path_atime_mtime"><code>fs.utimesSync(path, atime, mtime)</code></a></li> 321<li><a href="#fs_fs_writefilesync_file_data_options"><code>fs.writeFileSync(file, data[, options])</code></a></li> 322<li><a href="#fs_fs_writesync_fd_buffer_offset_length_position"><code>fs.writeSync(fd, buffer[, offset[, length[, position]]])</code></a></li> 323<li><a href="#fs_fs_writesync_fd_string_position_encoding"><code>fs.writeSync(fd, string[, position[, encoding]])</code></a></li> 324<li><a href="#fs_fs_writevsync_fd_buffers_position"><code>fs.writevSync(fd, buffers[, position])</code></a></li> 325</ul> 326</li> 327<li><a href="#fs_common_objects">Common Objects</a> 328<ul> 329<li><a href="#fs_class_fs_dir">Class: <code>fs.Dir</code></a> 330<ul> 331<li><a href="#fs_dir_close"><code>dir.close()</code></a></li> 332<li><a href="#fs_dir_close_callback"><code>dir.close(callback)</code></a></li> 333<li><a href="#fs_dir_closesync"><code>dir.closeSync()</code></a></li> 334<li><a href="#fs_dir_path"><code>dir.path</code></a></li> 335<li><a href="#fs_dir_read"><code>dir.read()</code></a></li> 336<li><a href="#fs_dir_read_callback"><code>dir.read(callback)</code></a></li> 337<li><a href="#fs_dir_readsync"><code>dir.readSync()</code></a></li> 338<li><a href="#fs_dir_symbol_asynciterator"><code>dir[Symbol.asyncIterator]()</code></a></li> 339</ul> 340</li> 341<li><a href="#fs_class_fs_dirent">Class: <code>fs.Dirent</code></a> 342<ul> 343<li><a href="#fs_dirent_isblockdevice"><code>dirent.isBlockDevice()</code></a></li> 344<li><a href="#fs_dirent_ischaracterdevice"><code>dirent.isCharacterDevice()</code></a></li> 345<li><a href="#fs_dirent_isdirectory"><code>dirent.isDirectory()</code></a></li> 346<li><a href="#fs_dirent_isfifo"><code>dirent.isFIFO()</code></a></li> 347<li><a href="#fs_dirent_isfile"><code>dirent.isFile()</code></a></li> 348<li><a href="#fs_dirent_issocket"><code>dirent.isSocket()</code></a></li> 349<li><a href="#fs_dirent_issymboliclink"><code>dirent.isSymbolicLink()</code></a></li> 350<li><a href="#fs_dirent_name"><code>dirent.name</code></a></li> 351</ul> 352</li> 353<li><a href="#fs_class_fs_fswatcher">Class: <code>fs.FSWatcher</code></a> 354<ul> 355<li><a href="#fs_event_change">Event: <code>'change'</code></a></li> 356<li><a href="#fs_event_close">Event: <code>'close'</code></a></li> 357<li><a href="#fs_event_error">Event: <code>'error'</code></a></li> 358<li><a href="#fs_watcher_close"><code>watcher.close()</code></a></li> 359<li><a href="#fs_watcher_ref"><code>watcher.ref()</code></a></li> 360<li><a href="#fs_watcher_unref"><code>watcher.unref()</code></a></li> 361</ul> 362</li> 363<li><a href="#fs_class_fs_statwatcher">Class: <code>fs.StatWatcher</code></a> 364<ul> 365<li><a href="#fs_watcher_ref_1"><code>watcher.ref()</code></a></li> 366<li><a href="#fs_watcher_unref_1"><code>watcher.unref()</code></a></li> 367</ul> 368</li> 369<li><a href="#fs_class_fs_readstream">Class: <code>fs.ReadStream</code></a> 370<ul> 371<li><a href="#fs_event_close_1">Event: <code>'close'</code></a></li> 372<li><a href="#fs_event_open">Event: <code>'open'</code></a></li> 373<li><a href="#fs_event_ready">Event: <code>'ready'</code></a></li> 374<li><a href="#fs_readstream_bytesread"><code>readStream.bytesRead</code></a></li> 375<li><a href="#fs_readstream_path"><code>readStream.path</code></a></li> 376<li><a href="#fs_readstream_pending"><code>readStream.pending</code></a></li> 377</ul> 378</li> 379<li><a href="#fs_class_fs_stats">Class: <code>fs.Stats</code></a> 380<ul> 381<li><a href="#fs_stats_isblockdevice"><code>stats.isBlockDevice()</code></a></li> 382<li><a href="#fs_stats_ischaracterdevice"><code>stats.isCharacterDevice()</code></a></li> 383<li><a href="#fs_stats_isdirectory"><code>stats.isDirectory()</code></a></li> 384<li><a href="#fs_stats_isfifo"><code>stats.isFIFO()</code></a></li> 385<li><a href="#fs_stats_isfile"><code>stats.isFile()</code></a></li> 386<li><a href="#fs_stats_issocket"><code>stats.isSocket()</code></a></li> 387<li><a href="#fs_stats_issymboliclink"><code>stats.isSymbolicLink()</code></a></li> 388<li><a href="#fs_stats_dev"><code>stats.dev</code></a></li> 389<li><a href="#fs_stats_ino"><code>stats.ino</code></a></li> 390<li><a href="#fs_stats_mode"><code>stats.mode</code></a></li> 391<li><a href="#fs_stats_nlink"><code>stats.nlink</code></a></li> 392<li><a href="#fs_stats_uid"><code>stats.uid</code></a></li> 393<li><a href="#fs_stats_gid"><code>stats.gid</code></a></li> 394<li><a href="#fs_stats_rdev"><code>stats.rdev</code></a></li> 395<li><a href="#fs_stats_size"><code>stats.size</code></a></li> 396<li><a href="#fs_stats_blksize"><code>stats.blksize</code></a></li> 397<li><a href="#fs_stats_blocks"><code>stats.blocks</code></a></li> 398<li><a href="#fs_stats_atimems"><code>stats.atimeMs</code></a></li> 399<li><a href="#fs_stats_mtimems"><code>stats.mtimeMs</code></a></li> 400<li><a href="#fs_stats_ctimems"><code>stats.ctimeMs</code></a></li> 401<li><a href="#fs_stats_birthtimems"><code>stats.birthtimeMs</code></a></li> 402<li><a href="#fs_stats_atimens"><code>stats.atimeNs</code></a></li> 403<li><a href="#fs_stats_mtimens"><code>stats.mtimeNs</code></a></li> 404<li><a href="#fs_stats_ctimens"><code>stats.ctimeNs</code></a></li> 405<li><a href="#fs_stats_birthtimens"><code>stats.birthtimeNs</code></a></li> 406<li><a href="#fs_stats_atime"><code>stats.atime</code></a></li> 407<li><a href="#fs_stats_mtime"><code>stats.mtime</code></a></li> 408<li><a href="#fs_stats_ctime"><code>stats.ctime</code></a></li> 409<li><a href="#fs_stats_birthtime"><code>stats.birthtime</code></a></li> 410<li><a href="#fs_stat_time_values">Stat time values</a></li> 411</ul> 412</li> 413<li><a href="#fs_class_fs_writestream">Class: <code>fs.WriteStream</code></a> 414<ul> 415<li><a href="#fs_event_close_2">Event: <code>'close'</code></a></li> 416<li><a href="#fs_event_open_1">Event: <code>'open'</code></a></li> 417<li><a href="#fs_event_ready_1">Event: <code>'ready'</code></a></li> 418<li><a href="#fs_writestream_byteswritten"><code>writeStream.bytesWritten</code></a></li> 419<li><a href="#fs_writestream_close_callback"><code>writeStream.close([callback])</code></a></li> 420<li><a href="#fs_writestream_path"><code>writeStream.path</code></a></li> 421<li><a href="#fs_writestream_pending"><code>writeStream.pending</code></a></li> 422</ul> 423</li> 424<li><a href="#fs_fs_constants"><code>fs.constants</code></a> 425<ul> 426<li><a href="#fs_fs_constants_1">FS constants</a> 427<ul> 428<li><a href="#fs_file_access_constants">File access constants</a></li> 429<li><a href="#fs_file_copy_constants">File copy constants</a></li> 430<li><a href="#fs_file_open_constants">File open constants</a></li> 431<li><a href="#fs_file_type_constants">File type constants</a></li> 432<li><a href="#fs_file_mode_constants">File mode constants</a></li> 433</ul> 434</li> 435</ul> 436</li> 437</ul> 438</li> 439<li><a href="#fs_notes">Notes</a> 440<ul> 441<li><a href="#fs_ordering_of_callback_and_promise_based_operations">Ordering of callback and promise-based operations</a></li> 442<li><a href="#fs_file_paths">File paths</a> 443<ul> 444<li><a href="#fs_string_paths">String paths</a></li> 445<li><a href="#fs_file_url_paths">File URL paths</a> 446<ul> 447<li><a href="#fs_platform_specific_considerations">Platform-specific considerations</a></li> 448</ul> 449</li> 450<li><a href="#fs_buffer_paths">Buffer paths</a></li> 451<li><a href="#fs_per_drive_working_directories_on_windows">Per-drive working directories on Windows</a></li> 452</ul> 453</li> 454<li><a href="#fs_file_descriptors_1">File descriptors</a></li> 455<li><a href="#fs_threadpool_usage">Threadpool usage</a></li> 456<li><a href="#fs_file_system_flags">File system flags</a></li> 457</ul> 458</li> 459</ul> 460</li> 461</ul></details> 462 463 <div id="apicontent"> 464 <h2>File system<span><a class="mark" href="#fs_file_system" id="fs_file_system">#</a></span></h2> 465 466<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p> 467 468<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v14.21.2/lib/fs.js">lib/fs.js</a></p> 469<p>The <code>fs</code> module enables interacting with the file system in a 470way modeled on standard POSIX functions.</p> 471<p>To use the promise-based APIs:</p> 472 473<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> 474<p>To use the callback and sync APIs:</p> 475 476<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> 477<p>All file system operations have synchronous, callback, and promise-based 478forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).</p> 479<section><h3>Promise example<span><a class="mark" href="#fs_promise_example" id="fs_promise_example">#</a></span></h3> 480<p>Promise-based operations return a promise that is fulfilled when the 481asynchronous operation is complete.</p> 482 483<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>; 484 485<span class="hljs-keyword">try</span> { 486 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(<span class="hljs-string">'/tmp/hello'</span>); 487 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 488} <span class="hljs-keyword">catch</span> (error) { 489 <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>); 490}</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>); 491 492(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params">path</span>) { 493 <span class="hljs-keyword">try</span> { 494 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(path); 495 <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>); 496 } <span class="hljs-keyword">catch</span> (error) { 497 <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>); 498 } 499})(<span class="hljs-string">'/tmp/hello'</span>);</code></pre> 500</section><section><h3>Callback example<span><a class="mark" href="#fs_callback_example" id="fs_callback_example">#</a></span></h3> 501<p>The callback form takes a completion callback function as its last 502argument and invokes the operation asynchronously. The arguments passed to 503the completion callback depend on the method, but the first argument is always 504reserved for an exception. If the operation is completed successfully, then 505the first argument is <code>null</code> or <code>undefined</code>.</p> 506 507<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>; 508 509<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> { 510 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 511 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 512});</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>); 513 514<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> { 515 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 516 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 517});</code></pre> 518<p>The callback-based versions of the <code>fs</code> module APIs are preferable over 519the use of the promise APIs when maximal performance (both in terms of 520execution time and memory allocation are required).</p> 521</section><section><h3>Synchronous example<span><a class="mark" href="#fs_synchronous_example" id="fs_synchronous_example">#</a></span></h3> 522<p>The synchronous APIs block the Node.js event loop and further JavaScript 523execution until the operation is complete. Exceptions are thrown immediately 524and can be handled using <code>try…catch</code>, or can be allowed to bubble up.</p> 525 526<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>; 527 528<span class="hljs-keyword">try</span> { 529 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 530 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 531} <span class="hljs-keyword">catch</span> (err) { 532 <span class="hljs-comment">// handle the error</span> 533}</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>); 534 535<span class="hljs-keyword">try</span> { 536 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 537 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 538} <span class="hljs-keyword">catch</span> (err) { 539 <span class="hljs-comment">// handle the error</span> 540}</code></pre> 541</section><section><h3>Promises API<span><a class="mark" href="#fs_promises_api" id="fs_promises_api">#</a></span></h3> 542<div class="api_metadata"> 543<details class="changelog"><summary>History</summary> 544<table> 545<tbody><tr><th>Version</th><th>Changes</th></tr> 546<tr><td>v14.0.0</td> 547<td><p>Exposed as <code>require('fs/promises')</code>.</p></td></tr> 548<tr><td>v11.14.0, v10.17.0</td> 549<td><p>This API is no longer experimental.</p></td></tr> 550<tr><td>v10.1.0</td> 551<td><p>The API is accessible via <code>require('fs').promises</code> only.</p></td></tr> 552<tr><td>v10.0.0</td> 553<td><p><span>Added in: v10.0.0</span></p></td></tr> 554</tbody></table> 555</details> 556</div> 557<p>The <code>fs/promises</code> API provides asynchronous file system methods that return 558promises.</p> 559<p>The promise APIs use the underlying Node.js threadpool to perform file 560system operations off the event loop thread. These operations are not 561synchronized or threadsafe. Care must be taken when performing multiple 562concurrent modifications on the same file or data corruption may occur.</p> 563<h4>Class: <code>FileHandle</code><span><a class="mark" href="#fs_class_filehandle" id="fs_class_filehandle">#</a></span></h4> 564<div class="api_metadata"> 565<span>Added in: v10.0.0</span> 566</div> 567<p>A <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object is an object wrapper for a numeric file descriptor.</p> 568<p>Instances of the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object are created by the <code>fsPromises.open()</code> 569method.</p> 570<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> 571<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 572try to automatically close the file descriptor and emit a process warning, 573helping to prevent memory leaks. Please do not rely on this behavior because 574it can be unreliable and the file may not be closed. Instead, always explicitly 575close <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>s. Node.js may change this behavior in the future.</p> 576<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> 577<div class="api_metadata"> 578<details class="changelog"><summary>History</summary> 579<table> 580<tbody><tr><th>Version</th><th>Changes</th></tr> 581<tr><td>v14.18.0</td> 582<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 583<tr><td>v14.0.0</td> 584<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 585<tr><td>v10.0.0</td> 586<td><p><span>Added in: v10.0.0</span></p></td></tr> 587</tbody></table> 588</details> 589</div> 590<ul> 591<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://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> 592<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> 593<ul> 594<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> 595</ul> 596</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>Alias of <a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 600<p>When operating on file handles, the mode cannot be changed from what it was set 601to with <a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open()</code></a>. Therefore, this is equivalent to 602<a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 603<h5><code>filehandle.chmod(mode)</code><span><a class="mark" href="#fs_filehandle_chmod_mode" id="fs_filehandle_chmod_mode">#</a></span></h5> 604<div class="api_metadata"> 605<span>Added in: v10.0.0</span> 606</div> 607<ul> 608<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> 609<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> 610</ul> 611<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> 612<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> 613<div class="api_metadata"> 614<span>Added in: v10.0.0</span> 615</div> 616<ul> 617<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> 618<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> 619<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> 620</ul> 621<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> 622<h5><code>filehandle.close()</code><span><a class="mark" href="#fs_filehandle_close" id="fs_filehandle_close">#</a></span></h5> 623<div class="api_metadata"> 624<span>Added in: v10.0.0</span> 625</div> 626<ul> 627<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> 628</ul> 629<p>Closes the file handle after waiting for any pending operation on the handle to 630complete.</p> 631<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>; 632 633<span class="hljs-keyword">let</span> filehandle; 634<span class="hljs-keyword">try</span> { 635 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>); 636} <span class="hljs-keyword">finally</span> { 637 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 638}</code></pre> 639<h5><code>filehandle.datasync()</code><span><a class="mark" href="#fs_filehandle_datasync" id="fs_filehandle_datasync">#</a></span></h5> 640<div class="api_metadata"> 641<span>Added in: v10.0.0</span> 642</div> 643<ul> 644<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> 645</ul> 646<p>Forces all currently queued I/O operations associated with the file to the 647operating system's synchronized I/O completion state. Refer to the POSIX 648<a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a> documentation for details.</p> 649<p>Unlike <code>filehandle.sync</code> this method does not flush modified metadata.</p> 650<h5><code>filehandle.fd</code><span><a class="mark" href="#fs_filehandle_fd" id="fs_filehandle_fd">#</a></span></h5> 651<div class="api_metadata"> 652<span>Added in: v10.0.0</span> 653</div> 654<ul> 655<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> 656</ul> 657<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> 658<div class="api_metadata"> 659<span>Added in: v10.0.0</span> 660</div> 661<ul> 662<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 663file data read.</li> 664<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. 665<strong>Default:</strong> <code>0</code></li> 666<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> 667<code>buffer.byteLength</code></li> 668<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 669file. If <code>null</code>, data will be read from the current file position, and 670the position will be updated. If <code>position</code> is an integer, the current 671file position will remain unchanged.</li> 672<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: 673<ul> 674<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> 675<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> 676argument.</li> 677</ul> 678</li> 679</ul> 680<p>Reads data from the file and stores that in the given buffer.</p> 681<p>If the file is not modified concurrently, the end-of-file is reached when the 682number of bytes read is zero.</p> 683<h5><code>filehandle.read([options])</code><span><a class="mark" href="#fs_filehandle_read_options" id="fs_filehandle_read_options">#</a></span></h5> 684<div class="api_metadata"> 685<span>Added in: v13.11.0, v12.17.0</span> 686</div> 687<ul> 688<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 689<ul> 690<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 691file data read. <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li> 692<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. 693<strong>Default:</strong> <code>0</code></li> 694<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> 695<code>buffer.byteLength</code></li> 696<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 697file. If <code>null</code>, data will be read from the current file position, and 698the position will be updated. If <code>position</code> is an integer, the current 699file position will remain unchanged. <strong>Default:</strong>: <code>null</code></li> 700</ul> 701</li> 702<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: 703<ul> 704<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> 705<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> 706argument.</li> 707</ul> 708</li> 709</ul> 710<p>Reads data from the file and stores that in the given buffer.</p> 711<p>If the file is not modified concurrently, the end-of-file is reached when the 712number of bytes read is zero.</p> 713<h5><code>filehandle.readFile(options)</code><span><a class="mark" href="#fs_filehandle_readfile_options" id="fs_filehandle_readfile_options">#</a></span></h5> 714<div class="api_metadata"> 715<span>Added in: v10.0.0</span> 716</div> 717<ul> 718<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> 719<ul> 720<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> 721<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 722</ul> 723</li> 724<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 725file. If no encoding is specified (using <code>options.encoding</code>), the data is 726returned as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</li> 727</ul> 728<p>Asynchronously reads the entire contents of a file.</p> 729<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 730<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 731<p>If one or more <code>filehandle.read()</code> calls are made on a file handle and then a 732<code>filehandle.readFile()</code> call is made, the data will be read from the current 733position till the end of the file. It doesn't always read from the beginning 734of the file.</p> 735<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> 736<div class="api_metadata"> 737<span>Added in: v13.13.0, v12.17.0</span> 738</div> 739<ul> 740<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> 741<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 742should be read from. If <code>position</code> is not a <code>number</code>, the data will be read 743from the current position.</li> 744<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: 745<ul> 746<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> 747<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 748a reference to the <code>buffers</code> input.</li> 749</ul> 750</li> 751</ul> 752<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> 753<h5><code>filehandle.stat([options])</code><span><a class="mark" href="#fs_filehandle_stat_options" id="fs_filehandle_stat_options">#</a></span></h5> 754<div class="api_metadata"> 755<details class="changelog"><summary>History</summary> 756<table> 757<tbody><tr><th>Version</th><th>Changes</th></tr> 758<tr><td>v10.5.0</td> 759<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 760<tr><td>v10.0.0</td> 761<td><p><span>Added in: v10.0.0</span></p></td></tr> 762</tbody></table> 763</details> 764</div> 765<ul> 766<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 767<ul> 768<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 769<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> 770</ul> 771</li> 772<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> 773</ul> 774<h5><code>filehandle.sync()</code><span><a class="mark" href="#fs_filehandle_sync" id="fs_filehandle_sync">#</a></span></h5> 775<div class="api_metadata"> 776<span>Added in: v10.0.0</span> 777</div> 778<ul> 779<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> 780</ul> 781<p>Request that all data for the open file descriptor is flushed to the storage 782device. The specific implementation is operating system and device specific. 783Refer 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> 784<h5><code>filehandle.truncate(len)</code><span><a class="mark" href="#fs_filehandle_truncate_len" id="fs_filehandle_truncate_len">#</a></span></h5> 785<div class="api_metadata"> 786<span>Added in: v10.0.0</span> 787</div> 788<ul> 789<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> 790<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> 791</ul> 792<p>Truncates the file.</p> 793<p>If the file was larger than <code>len</code> bytes, only the first <code>len</code> bytes will be 794retained in the file.</p> 795<p>The following example retains only the first four bytes of the file:</p> 796<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>; 797 798<span class="hljs-keyword">let</span> filehandle = <span class="hljs-literal">null</span>; 799<span class="hljs-keyword">try</span> { 800 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>); 801 <span class="hljs-keyword">await</span> filehandle.<span class="hljs-title function_">truncate</span>(<span class="hljs-number">4</span>); 802} <span class="hljs-keyword">finally</span> { 803 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 804}</code></pre> 805<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the 806extended part is filled with null bytes (<code>'\0'</code>):</p> 807<p>If <code>len</code> is negative then <code>0</code> will be used.</p> 808<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> 809<div class="api_metadata"> 810<span>Added in: v10.0.0</span> 811</div> 812<ul> 813<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> 814<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> 815<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 816</ul> 817<p>Change the file system timestamps of the object referenced by the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> 818then resolves the promise with no arguments upon success.</p> 819<p>This function does not work on AIX versions before 7.1, it will reject the 820promise with an error using code <code>UV_ENOSYS</code>.</p> 821<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> 822<div class="api_metadata"> 823<details class="changelog"><summary>History</summary> 824<table> 825<tbody><tr><th>Version</th><th>Changes</th></tr> 826<tr><td>v14.0.0</td> 827<td><p>The <code>buffer</code> parameter won't coerce unsupported input to buffers anymore.</p></td></tr> 828<tr><td>v10.0.0</td> 829<td><p><span>Added in: v10.0.0</span></p></td></tr> 830</tbody></table> 831</details> 832</div> 833<ul> 834<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> 835<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 836to write begins. <strong>Default:</strong> <code>0</code></li> 837<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> 838<code>buffer.byteLength - offset</code></li> 839<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 840data from <code>buffer</code> should be written. If <code>position</code> is not a <code>number</code>, 841the 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> 842documentation for more detail.</li> 843<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 844</ul> 845<p>Write <code>buffer</code> to the file.</p> 846<p>The promise is resolved with an object containing two properties:</p> 847<ul> 848<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> 849<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 850<code>buffer</code> written.</li> 851</ul> 852<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 853without waiting for the promise to be resolved (or rejected). For this 854scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 855<p>On Linux, positional writes do not work when the file is opened in append mode. 856The kernel ignores the position argument and always appends the data to 857the end of the file.</p> 858<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> 859<div class="api_metadata"> 860<details class="changelog"><summary>History</summary> 861<table> 862<tbody><tr><th>Version</th><th>Changes</th></tr> 863<tr><td>v14.0.0</td> 864<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 865<tr><td>v10.0.0</td> 866<td><p><span>Added in: v10.0.0</span></p></td></tr> 867</tbody></table> 868</details> 869</div> 870<ul> 871<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 872<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 873data from <code>string</code> should be written. If <code>position</code> is not a <code>number</code> the 874data 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> 875documentation for more detail.</li> 876<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> 877<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 878</ul> 879<p>Write <code>string</code> to the file. If <code>string</code> is not a string, the promise is 880rejected with an error.</p> 881<p>The promise is resolved with an object containing two properties:</p> 882<ul> 883<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> 884<li><code>buffer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> a reference to the <code>string</code> written.</li> 885</ul> 886<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 887without waiting for the promise to be resolved (or rejected). For this 888scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 889<p>On Linux, positional writes do not work when the file is opened in append mode. 890The kernel ignores the position argument and always appends the data to 891the end of the file.</p> 892<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> 893<div class="api_metadata"> 894<details class="changelog"><summary>History</summary> 895<table> 896<tbody><tr><th>Version</th><th>Changes</th></tr> 897<tr><td>v14.18.0</td> 898<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 899<tr><td>v14.0.0</td> 900<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 901<tr><td>v10.0.0</td> 902<td><p><span>Added in: v10.0.0</span></p></td></tr> 903</tbody></table> 904</details> 905</div> 906<ul> 907<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://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> 908<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> 909<ul> 910<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 911string. <strong>Default:</strong> <code>'utf8'</code></li> 912</ul> 913</li> 914<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 915</ul> 916<p>Asynchronously writes data to a file, replacing the file if it already exists. 917<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. 918The promise is resolved with no arguments upon success.</p> 919<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 920<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support writing.</p> 921<p>It is unsafe to use <code>filehandle.writeFile()</code> multiple times on the same file 922without waiting for the promise to be resolved (or rejected).</p> 923<p>If one or more <code>filehandle.write()</code> calls are made on a file handle and then a 924<code>filehandle.writeFile()</code> call is made, the data will be written from the 925current position till the end of the file. It doesn't always write from the 926beginning of the file.</p> 927<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> 928<div class="api_metadata"> 929<span>Added in: v12.9.0</span> 930</div> 931<ul> 932<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> 933<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 934data from <code>buffers</code> should be written. If <code>position</code> is not a <code>number</code>, 935the data will be written at the current position.</li> 936<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 937</ul> 938<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> 939<p>The promise is resolved with an object containing a two properties:</p> 940<ul> 941<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> 942<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> 943input.</li> 944</ul> 945<p>It is unsafe to call <code>writev()</code> multiple times on the same file without waiting 946for the promise to be resolved (or rejected).</p> 947<p>On Linux, positional writes don't work when the file is opened in append mode. 948The kernel ignores the position argument and always appends the data to 949the end of the file.</p> 950<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> 951<div class="api_metadata"> 952<span>Added in: v10.0.0</span> 953</div> 954<ul> 955<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> 956<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> 957<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> 958</ul> 959<p>Tests a user's permissions for the file or directory specified by <code>path</code>. 960The <code>mode</code> argument is an optional integer that specifies the accessibility 961checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values 962of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of 963two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 964<p>If the accessibility check is successful, the promise is resolved with no 965value. If any of the accessibility checks fail, the promise is rejected 966with 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 967<code>/etc/passwd</code> can be read and written by the current process.</p> 968<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>; 969<span class="hljs-keyword">import</span> { constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 970 971<span class="hljs-keyword">try</span> { 972 <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>); 973 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can access'</span>); 974} <span class="hljs-keyword">catch</span> { 975 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'cannot access'</span>); 976}</code></pre> 977<p>Using <code>fsPromises.access()</code> to check for the accessibility of a file before 978calling <code>fsPromises.open()</code> is not recommended. Doing so introduces a race 979condition, since other processes may change the file's state between the two 980calls. Instead, user code should open/read/write the file directly and handle 981the error raised if the file is not accessible.</p> 982<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> 983<div class="api_metadata"> 984<span>Added in: v10.0.0</span> 985</div> 986<ul> 987<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> 988<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> 989<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> 990<ul> 991<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> 992<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> 993<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> 994</ul> 995</li> 996<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> 997</ul> 998<p>Asynchronously append data to a file, creating the file if it does not yet 999exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 1000<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 1001<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> 1002for more details.</p> 1003<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 1004for appending (using <code>fsPromises.open()</code>).</p> 1005<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> 1006<div class="api_metadata"> 1007<span>Added in: v10.0.0</span> 1008</div> 1009<ul> 1010<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> 1011<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> 1012<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> 1013</ul> 1014<p>Changes the permissions of a file.</p> 1015<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> 1016<div class="api_metadata"> 1017<span>Added in: v10.0.0</span> 1018</div> 1019<ul> 1020<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> 1021<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1022<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1023<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> 1024</ul> 1025<p>Changes the ownership of a file.</p> 1026<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> 1027<div class="api_metadata"> 1028<details class="changelog"><summary>History</summary> 1029<table> 1030<tbody><tr><th>Version</th><th>Changes</th></tr> 1031<tr><td>v14.0.0</td> 1032<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 1033<tr><td>v10.0.0</td> 1034<td><p><span>Added in: v10.0.0</span></p></td></tr> 1035</tbody></table> 1036</details> 1037</div> 1038<ul> 1039<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> 1040<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> 1041<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 1042operation. It is possible to create a mask consisting of the bitwise OR of 1043two or more values (e.g. 1044<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>) 1045<strong>Default:</strong> <code>0</code>. 1046<ul> 1047<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> 1048already exists.</li> 1049<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create 1050a copy-on-write reflink. If the platform does not support copy-on-write, 1051then a fallback copy mechanism is used.</li> 1052<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 1053create a copy-on-write reflink. If the platform does not support 1054copy-on-write, then the operation will fail.</li> 1055</ul> 1056</li> 1057<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> 1058</ul> 1059<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 1060already exists.</p> 1061<p>No guarantees are made about the atomicity of the copy operation. If an 1062error occurs after the destination file has been opened for writing, an attempt 1063will be made to remove the destination.</p> 1064<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>; 1065<span class="hljs-keyword">import</span> { copyFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1066 1067<span class="hljs-keyword">try</span> { 1068 <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>); 1069 <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>); 1070} <span class="hljs-keyword">catch</span> { 1071 <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>); 1072} 1073 1074<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 1075<span class="hljs-keyword">try</span> { 1076 <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>); 1077 <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>); 1078} <span class="hljs-keyword">catch</span> { 1079 <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>); 1080}</code></pre> 1081<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> 1082<div class="api_metadata"> 1083<span>Deprecated since: v10.0.0</span> 1084</div> 1085<ul> 1086<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> 1087<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1088<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> 1089</ul> 1090<p>Changes the permissions on a symbolic link.</p> 1091<p>This method is only implemented on macOS.</p> 1092<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> 1093<div class="api_metadata"> 1094<details class="changelog"><summary>History</summary> 1095<table> 1096<tbody><tr><th>Version</th><th>Changes</th></tr> 1097<tr><td>v10.6.0</td> 1098<td><p>This API is no longer deprecated.</p></td></tr> 1099<tr><td>v10.0.0</td> 1100<td><p><span>Added in: v10.0.0</span></p></td></tr> 1101</tbody></table> 1102</details> 1103</div> 1104<ul> 1105<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> 1106<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1107<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1108<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> 1109</ul> 1110<p>Changes the ownership on a symbolic link.</p> 1111<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> 1112<div class="api_metadata"> 1113<span>Added in: v14.5.0, v12.19.0</span> 1114</div> 1115<ul> 1116<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> 1117<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> 1118<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> 1119<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> 1120</ul> 1121<p>Changes the access and modification times of a file in the same way as 1122<a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes()</code></a>, with the difference that if the path refers to a 1123symbolic link, then the link is not dereferenced: instead, the timestamps of 1124the symbolic link itself are changed.</p> 1125<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> 1126<div class="api_metadata"> 1127<span>Added in: v10.0.0</span> 1128</div> 1129<ul> 1130<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> 1131<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> 1132<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> 1133</ul> 1134<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 1135<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a> documentation for more detail.</p> 1136<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> 1137<div class="api_metadata"> 1138<details class="changelog"><summary>History</summary> 1139<table> 1140<tbody><tr><th>Version</th><th>Changes</th></tr> 1141<tr><td>v10.5.0</td> 1142<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1143<tr><td>v10.0.0</td> 1144<td><p><span>Added in: v10.0.0</span></p></td></tr> 1145</tbody></table> 1146</details> 1147</div> 1148<ul> 1149<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> 1150<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1151<ul> 1152<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 1153<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> 1154</ul> 1155</li> 1156<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 1157symbolic link <code>path</code>.</li> 1158</ul> 1159<p>Equivalent to <a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat()</code></a> unless <code>path</code> refers to a symbolic link, 1160in which case the link itself is stat-ed, not the file that it refers to. 1161Refer 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> 1162<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> 1163<div class="api_metadata"> 1164<span>Added in: v10.0.0</span> 1165</div> 1166<ul> 1167<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> 1168<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> 1169<ul> 1170<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> 1171<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> 1172</ul> 1173</li> 1174<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> 1175is <code>false</code>, or the first directory path created if <code>recursive</code> is <code>true</code>.</li> 1176</ul> 1177<p>Asynchronously creates a directory.</p> 1178<p>The optional <code>options</code> argument can be an integer specifying <code>mode</code> (permission 1179and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code> 1180property indicating whether parent directories should be created. Calling 1181<code>fsPromises.mkdir()</code> when <code>path</code> is a directory that exists results in a 1182rejection only when <code>recursive</code> is false.</p> 1183<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> 1184<div class="api_metadata"> 1185<details class="changelog"><summary>History</summary> 1186<table> 1187<tbody><tr><th>Version</th><th>Changes</th></tr> 1188<tr><td>v14.18.0</td> 1189<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 1190<tr><td>v10.0.0</td> 1191<td><p><span>Added in: v10.0.0</span></p></td></tr> 1192</tbody></table> 1193</details> 1194</div> 1195<ul> 1196<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 1197<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> 1198<ul> 1199<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> 1200</ul> 1201</li> 1202<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 1203of the newly created temporary directory.</li> 1204</ul> 1205<p>Creates a unique temporary directory. A unique directory name is generated by 1206appending six random characters to the end of the provided <code>prefix</code>. Due to 1207platform inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some 1208platforms, notably the BSDs, can return more than six random characters, and 1209replace trailing <code>X</code> characters in <code>prefix</code> with random characters.</p> 1210<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1211object with an <code>encoding</code> property specifying the character encoding to use.</p> 1212<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>; 1213 1214<span class="hljs-keyword">try</span> { 1215 <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>)); 1216} <span class="hljs-keyword">catch</span> (err) { 1217 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1218}</code></pre> 1219<p>The <code>fsPromises.mkdtemp()</code> method will append the six randomly selected 1220characters directly to the <code>prefix</code> string. For instance, given a directory 1221<code>/tmp</code>, if the intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the 1222<code>prefix</code> must end with a trailing platform-specific path separator 1223(<code>require('path').sep</code>).</p> 1224<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> 1225<div class="api_metadata"> 1226<details class="changelog"><summary>History</summary> 1227<table> 1228<tbody><tr><th>Version</th><th>Changes</th></tr> 1229<tr><td>v11.1.0</td> 1230<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 1231<tr><td>v10.0.0</td> 1232<td><p><span>Added in: v10.0.0</span></p></td></tr> 1233</tbody></table> 1234</details> 1235</div> 1236<ul> 1237<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> 1238<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>. 1239<strong>Default:</strong> <code>'r'</code>.</li> 1240<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) 1241if the file is created. <strong>Default:</strong> <code>0o666</code> (readable and writable)</li> 1242<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> 1243</ul> 1244<p>Opens a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>.</p> 1245<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> 1246<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented 1247by <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 1248a colon, Node.js will open a file system stream, as described by 1249<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p> 1250<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> 1251<div class="api_metadata"> 1252<details class="changelog"><summary>History</summary> 1253<table> 1254<tbody><tr><th>Version</th><th>Changes</th></tr> 1255<tr><td>v13.1.0, v12.16.0</td> 1256<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 1257<tr><td>v12.12.0</td> 1258<td><p><span>Added in: v12.12.0</span></p></td></tr> 1259</tbody></table> 1260</details> 1261</div> 1262<ul> 1263<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> 1264<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1265<ul> 1266<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> 1267<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 1268internally when reading from the directory. Higher values lead to better 1269performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 1270</ul> 1271</li> 1272<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> 1273</ul> 1274<p>Asynchronously open a directory for iterative scanning. See the POSIX 1275<a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a> documentation for more detail.</p> 1276<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 1277and cleaning up the directory.</p> 1278<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 1279directory and subsequent read operations.</p> 1280<p>Example using async iteration:</p> 1281<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>; 1282 1283<span class="hljs-keyword">try</span> { 1284 <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>); 1285 <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) 1286 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 1287} <span class="hljs-keyword">catch</span> (err) { 1288 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1289}</code></pre> 1290<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 1291closed after the iterator exits.</p> 1292<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> 1293<div class="api_metadata"> 1294<details class="changelog"><summary>History</summary> 1295<table> 1296<tbody><tr><th>Version</th><th>Changes</th></tr> 1297<tr><td>v10.11.0</td> 1298<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 1299<tr><td>v10.0.0</td> 1300<td><p><span>Added in: v10.0.0</span></p></td></tr> 1301</tbody></table> 1302</details> 1303</div> 1304<ul> 1305<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> 1306<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> 1307<ul> 1308<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> 1309<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> 1310</ul> 1311</li> 1312<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 1313the directory excluding <code>'.'</code> and <code>'..'</code>.</li> 1314</ul> 1315<p>Reads the contents of a directory.</p> 1316<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1317object with an <code>encoding</code> property specifying the character encoding to use for 1318the filenames. If the <code>encoding</code> is set to <code>'buffer'</code>, the filenames returned 1319will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 1320<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the resolved array will contain 1321<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 1322<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>; 1323 1324<span class="hljs-keyword">try</span> { 1325 <span class="hljs-keyword">const</span> files = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readdir</span>(path); 1326 <span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> file <span class="hljs-keyword">of</span> files) 1327 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(file); 1328} <span class="hljs-keyword">catch</span> (err) { 1329 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1330}</code></pre> 1331<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> 1332<div class="api_metadata"> 1333<details class="changelog"><summary>History</summary> 1334<table> 1335<tbody><tr><th>Version</th><th>Changes</th></tr> 1336<tr><td>v14.17.0</td> 1337<td><p>The options argument may include an AbortSignal to abort an ongoing readFile request.</p></td></tr> 1338<tr><td>v10.0.0</td> 1339<td><p><span>Added in: v10.0.0</span></p></td></tr> 1340</tbody></table> 1341</details> 1342</div> 1343<ul> 1344<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> 1345<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> 1346<ul> 1347<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> 1348<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> 1349<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 1350</ul> 1351</li> 1352<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> 1353</ul> 1354<p>Asynchronously reads the entire contents of a file.</p> 1355<p>If no encoding is specified (using <code>options.encoding</code>), the data is returned 1356as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</p> 1357<p>If <code>options</code> is a string, then it specifies the encoding.</p> 1358<p>When the <code>path</code> is a directory, the behavior of <code>fsPromises.readFile()</code> is 1359platform-specific. On macOS, Linux, and Windows, the promise will be rejected 1360with an error. On FreeBSD, a representation of the directory's contents will be 1361returned.</p> 1362<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 1363request is aborted the promise returned is rejected with an <code>AbortError</code>:</p> 1364<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>; 1365 1366<span class="hljs-keyword">try</span> { 1367 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1368 <span class="hljs-keyword">const</span> { signal } = controller; 1369 <span class="hljs-keyword">const</span> promise = <span class="hljs-title function_">readFile</span>(fileName, { signal }); 1370 1371 <span class="hljs-comment">// Abort the request before the promise settles.</span> 1372 controller.<span class="hljs-title function_">abort</span>(); 1373 1374 <span class="hljs-keyword">await</span> promise; 1375} <span class="hljs-keyword">catch</span> (err) { 1376 <span class="hljs-comment">// When a request is aborted - err is an AbortError</span> 1377 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1378}</code></pre> 1379<p>Aborting an ongoing request does not abort individual operating 1380system requests but rather the internal buffering <code>fs.readFile</code> performs.</p> 1381<p>Any specified <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 1382<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> 1383<div class="api_metadata"> 1384<span>Added in: v10.0.0</span> 1385</div> 1386<ul> 1387<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> 1388<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> 1389<ul> 1390<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> 1391</ul> 1392</li> 1393<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> 1394</ul> 1395<p>Reads the contents of the symbolic link referred to by <code>path</code>. See the POSIX 1396<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 1397<code>linkString</code> upon success.</p> 1398<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1399object with an <code>encoding</code> property specifying the character encoding to use for 1400the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, the link path 1401returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1402<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> 1403<div class="api_metadata"> 1404<span>Added in: v10.0.0</span> 1405</div> 1406<ul> 1407<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> 1408<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> 1409<ul> 1410<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> 1411</ul> 1412</li> 1413<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> 1414</ul> 1415<p>Determines the actual location of <code>path</code> using the same semantics as the 1416<code>fs.realpath.native()</code> function.</p> 1417<p>Only paths that can be converted to UTF8 strings are supported.</p> 1418<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1419object with an <code>encoding</code> property specifying the character encoding to use for 1420the path. If the <code>encoding</code> is set to <code>'buffer'</code>, the path returned will be 1421passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1422<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 1423be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 1424this restriction.</p> 1425<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> 1426<div class="api_metadata"> 1427<span>Added in: v10.0.0</span> 1428</div> 1429<ul> 1430<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> 1431<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> 1432<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> 1433</ul> 1434<p>Renames <code>oldPath</code> to <code>newPath</code>.</p> 1435<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> 1436<div class="api_metadata"> 1437<details class="changelog"><summary>History</summary> 1438<table> 1439<tbody><tr><th>Version</th><th>Changes</th></tr> 1440<tr><td>v14.14.0</td> 1441<td><p>The <code>recursive</code> option is deprecated, use <code>fsPromises.rm</code> instead.</p></td></tr> 1442<tr><td>v13.3.0, v12.16.0</td> 1443<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> 1444<tr><td>v12.10.0</td> 1445<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 1446<tr><td>v10.0.0</td> 1447<td><p><span>Added in: v10.0.0</span></p></td></tr> 1448</tbody></table> 1449</details> 1450</div> 1451<ul> 1452<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> 1453<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1454<ul> 1455<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 1456<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 1457backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1458represents the number of retries. This option is ignored if the <code>recursive</code> 1459option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1460<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 1461recursive mode, errors are not reported if <code>path</code> does not exist, and 1462operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1463<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 1464retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1465<strong>Default:</strong> <code>100</code>.</li> 1466</ul> 1467</li> 1468<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> 1469</ul> 1470<p>Removes the directory identified by <code>path</code>.</p> 1471<p>Using <code>fsPromises.rmdir()</code> on a file (not a directory) results in the 1472promise being rejected with an <code>ENOENT</code> error on Windows and an <code>ENOTDIR</code> 1473error on POSIX.</p> 1474<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 1475<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 1476that represent files will be deleted. The permissive behavior of the 1477<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 1478the future.</p> 1479<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> 1480<div class="api_metadata"> 1481<span>Added in: v14.14.0</span> 1482</div> 1483<ul> 1484<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> 1485<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1486<ul> 1487<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 1488not exist. <strong>Default:</strong> <code>false</code>.</li> 1489<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 1490<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 1491backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1492represents the number of retries. This option is ignored if the <code>recursive</code> 1493option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1494<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 1495recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1496<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 1497retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1498<strong>Default:</strong> <code>100</code>.</li> 1499</ul> 1500</li> 1501<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> 1502</ul> 1503<p>Removes files and directories (modeled on the standard POSIX <code>rm</code> utility).</p> 1504<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> 1505<div class="api_metadata"> 1506<details class="changelog"><summary>History</summary> 1507<table> 1508<tbody><tr><th>Version</th><th>Changes</th></tr> 1509<tr><td>v10.5.0</td> 1510<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1511<tr><td>v10.0.0</td> 1512<td><p><span>Added in: v10.0.0</span></p></td></tr> 1513</tbody></table> 1514</details> 1515</div> 1516<ul> 1517<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> 1518<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1519<ul> 1520<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 1521<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> 1522</ul> 1523</li> 1524<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 1525given <code>path</code>.</li> 1526</ul> 1527<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> 1528<div class="api_metadata"> 1529<span>Added in: v10.0.0</span> 1530</div> 1531<ul> 1532<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> 1533<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> 1534<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> 1535<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> 1536</ul> 1537<p>Creates a symbolic link.</p> 1538<p>The <code>type</code> argument is only used on Windows platforms and can be one of <code>'dir'</code>, 1539<code>'file'</code>, or <code>'junction'</code>. Windows junction points require the destination path 1540to be absolute. When using <code>'junction'</code>, the <code>target</code> argument will 1541automatically be normalized to absolute path.</p> 1542<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> 1543<div class="api_metadata"> 1544<span>Added in: v10.0.0</span> 1545</div> 1546<ul> 1547<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> 1548<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> 1549<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> 1550</ul> 1551<p>Truncates (shortens or extends the length) of the content at <code>path</code> to <code>len</code> 1552bytes.</p> 1553<h4><code>fsPromises.unlink(path)</code><span><a class="mark" href="#fs_fspromises_unlink_path" id="fs_fspromises_unlink_path">#</a></span></h4> 1554<div class="api_metadata"> 1555<span>Added in: v10.0.0</span> 1556</div> 1557<ul> 1558<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> 1559<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> 1560</ul> 1561<p>If <code>path</code> refers to a symbolic link, then the link is removed without affecting 1562the file or directory to which that link refers. If the <code>path</code> refers to a file 1563path 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> 1564documentation for more detail.</p> 1565<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> 1566<div class="api_metadata"> 1567<span>Added in: v10.0.0</span> 1568</div> 1569<ul> 1570<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> 1571<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> 1572<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> 1573<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> 1574</ul> 1575<p>Change the file system timestamps of the object referenced by <code>path</code>.</p> 1576<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p> 1577<ul> 1578<li>Values can be either numbers representing Unix epoch time, <code>Date</code>s, or a 1579numeric string like <code>'123456789.0'</code>.</li> 1580<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or 1581<code>-Infinity</code>, an <code>Error</code> will be thrown.</li> 1582</ul> 1583<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> 1584<div class="api_metadata"> 1585<span>Added in: v14.18.0</span> 1586</div> 1587<ul> 1588<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> 1589<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> 1590<ul> 1591<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 1592as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li> 1593<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 1594watched, or only the current directory. This applies when a directory is 1595specified, and only on supported platforms (See <a href="#fs_caveats">caveats</a>). <strong>Default:</strong> 1596<code>false</code>.</li> 1597<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 1598filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li> 1599<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 1600should stop.</li> 1601</ul> 1602</li> 1603<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> of objects with the properties: 1604<ul> 1605<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> 1606<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> 1607</ul> 1608</li> 1609</ul> 1610<p>Returns an async iterator that watches for changes on <code>filename</code>, where <code>filename</code> 1611is either a file or a directory.</p> 1612<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>); 1613 1614<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1615<span class="hljs-keyword">const</span> { signal } = ac; 1616<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>); 1617 1618(<span class="hljs-keyword">async</span> () => { 1619 <span class="hljs-keyword">try</span> { 1620 <span class="hljs-keyword">const</span> watcher = <span class="hljs-title function_">watch</span>(__filename, { signal }); 1621 <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) 1622 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event); 1623 } <span class="hljs-keyword">catch</span> (err) { 1624 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">name</span> === <span class="hljs-string">'AbortError'</span>) 1625 <span class="hljs-keyword">return</span>; 1626 <span class="hljs-keyword">throw</span> err; 1627 } 1628})();</code></pre> 1629<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or 1630disappears in the directory.</p> 1631<p>All the <a href="#fs_caveats">caveats</a> for <code>fs.watch()</code> also apply to <code>fsPromises.watch()</code>.</p> 1632<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> 1633<div class="api_metadata"> 1634<details class="changelog"><summary>History</summary> 1635<table> 1636<tbody><tr><th>Version</th><th>Changes</th></tr> 1637<tr><td>v14.18.0</td> 1638<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 1639<tr><td>v14.17.0</td> 1640<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 1641<tr><td>v14.0.0</td> 1642<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 1643<tr><td>v10.0.0</td> 1644<td><p><span>Added in: v10.0.0</span></p></td></tr> 1645</tbody></table> 1646</details> 1647</div> 1648<ul> 1649<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> 1650<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://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> 1651<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> 1652<ul> 1653<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> 1654<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> 1655<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> 1656<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 1657</ul> 1658</li> 1659<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> 1660</ul> 1661<p>Asynchronously writes data to a file, replacing the file if it already exists. 1662<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.</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.0.0</td> 4009<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4010<tr><td>v10.10.0</td> 4011<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4012<tr><td>v10.0.0</td> 4013<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> 4014<tr><td>v7.4.0</td> 4015<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4016<tr><td>v7.2.0</td> 4017<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 4018<tr><td>v7.0.0</td> 4019<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> 4020<tr><td>v0.0.2</td> 4021<td><p><span>Added in: v0.0.2</span></p></td></tr> 4022</tbody></table> 4023</details> 4024</div> 4025<ul> 4026<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4027<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> 4028<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4029<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4030<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4031<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4032<ul> 4033<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4034<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4035<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> 4036</ul> 4037</li> 4038</ul> 4039<p>Write <code>buffer</code> to the file specified by <code>fd</code>.</p> 4040<p><code>offset</code> determines the part of the buffer to be written, and <code>length</code> is 4041an integer specifying the number of bytes to write.</p> 4042<p><code>position</code> refers to the offset from the beginning of the file where this data 4043should be written. If <code>typeof position !== 'number'</code>, the data will be written 4044at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4045<p>The callback will be given three arguments <code>(err, bytesWritten, buffer)</code> where 4046<code>bytesWritten</code> specifies how many <em>bytes</em> were written from <code>buffer</code>.</p> 4047<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 4048a promise for an <code>Object</code> with <code>bytesWritten</code> and <code>buffer</code> properties.</p> 4049<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4050for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4051recommended.</p> 4052<p>On Linux, positional writes don't work when the file is opened in append mode. 4053The kernel ignores the position argument and always appends the data to 4054the end of the file.</p> 4055<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> 4056<div class="api_metadata"> 4057<details class="changelog"><summary>History</summary> 4058<table> 4059<tbody><tr><th>Version</th><th>Changes</th></tr> 4060<tr><td>v14.12.0</td> 4061<td><p>The <code>string</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4062<tr><td>v14.0.0</td> 4063<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4064<tr><td>v10.0.0</td> 4065<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> 4066<tr><td>v7.2.0</td> 4067<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 4068<tr><td>v7.0.0</td> 4069<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> 4070<tr><td>v0.11.5</td> 4071<td><p><span>Added in: v0.11.5</span></p></td></tr> 4072</tbody></table> 4073</details> 4074</div> 4075<ul> 4076<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4077<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> 4078<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4079<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> 4080<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4081<ul> 4082<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4083<li><code>written</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4084<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4085</ul> 4086</li> 4087</ul> 4088<p>Write <code>string</code> to the file specified by <code>fd</code>. If <code>string</code> is not a string, or an 4089object with an own <code>toString</code> function property, then an exception is thrown.</p> 4090<p><code>position</code> refers to the offset from the beginning of the file where this data 4091should be written. If <code>typeof position !== 'number'</code> the data will be written at 4092the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4093<p><code>encoding</code> is the expected string encoding.</p> 4094<p>The callback will receive the arguments <code>(err, written, string)</code> where <code>written</code> 4095specifies how many <em>bytes</em> the passed string required to be written. Bytes 4096written is not necessarily the same as string characters written. See 4097<a href="buffer.html#buffer_static_method_buffer_bytelength_string_encoding"><code>Buffer.byteLength</code></a>.</p> 4098<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4099for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4100recommended.</p> 4101<p>On Linux, positional writes don't work when the file is opened in append mode. 4102The kernel ignores the position argument and always appends the data to 4103the end of the file.</p> 4104<p>On Windows, if the file descriptor is connected to the console (e.g. <code>fd == 1</code> 4105or <code>stdout</code>) a string containing non-ASCII characters will not be rendered 4106properly by default, regardless of the encoding used. 4107It is possible to configure the console to render UTF-8 properly by changing the 4108active codepage with the <code>chcp 65001</code> command. See the <a href="https://ss64.com/nt/chcp.html">chcp</a> docs for more 4109details.</p> 4110<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> 4111<div class="api_metadata"> 4112<details class="changelog"><summary>History</summary> 4113<table> 4114<tbody><tr><th>Version</th><th>Changes</th></tr> 4115<tr><td>v14.17.0</td> 4116<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 4117<tr><td>v14.12.0</td> 4118<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4119<tr><td>v14.0.0</td> 4120<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4121<tr><td>v10.10.0</td> 4122<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4123<tr><td>v10.0.0</td> 4124<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> 4125<tr><td>v7.4.0</td> 4126<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4127<tr><td>v7.0.0</td> 4128<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> 4129<tr><td>v5.0.0</td> 4130<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4131<tr><td>v0.1.29</td> 4132<td><p><span>Added in: v0.1.29</span></p></td></tr> 4133</tbody></table> 4134</details> 4135</div> 4136<ul> 4137<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> 4138<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> 4139<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> 4140<ul> 4141<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> 4142<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> 4143<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> 4144<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 4145</ul> 4146</li> 4147<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4148<ul> 4149<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4150</ul> 4151</li> 4152</ul> 4153<p>When <code>file</code> is a filename, asynchronously writes data to the file, replacing the 4154file if it already exists. <code>data</code> can be a string or a buffer.</p> 4155<p>When <code>file</code> is a file descriptor, the behavior is similar to calling 4156<code>fs.write()</code> directly (which is recommended). See the notes below on using 4157a file descriptor.</p> 4158<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p> 4159<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> 4160for more details.</p> 4161<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 4162function property.</p> 4163<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>; 4164 4165<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>)); 4166<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> { 4167 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 4168 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The file has been saved!'</span>); 4169});</code></pre> 4170<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4171<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>; 4172 4173<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> 4174<p>It is unsafe to use <code>fs.writeFile()</code> multiple times on the same file without 4175waiting for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4176recommended.</p> 4177<p>Similarly to <code>fs.readFile</code> - <code>fs.writeFile</code> is a convenience method that 4178performs multiple <code>write</code> calls internally to write the buffer passed to it. 4179For performance sensitive code consider using <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4180<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>. 4181Cancelation is "best effort", and some amount of data is likely still 4182to be written.</p> 4183<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>; 4184 4185<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 4186<span class="hljs-keyword">const</span> { signal } = controller; 4187<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>)); 4188<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> { 4189 <span class="hljs-comment">// When a request is aborted - the callback is called with an AbortError</span> 4190}); 4191<span class="hljs-comment">// When the request should be aborted</span> 4192controller.<span class="hljs-title function_">abort</span>();</code></pre> 4193<p>Aborting an ongoing request does not abort individual operating 4194system requests but rather the internal buffering <code>fs.writeFile</code> performs.</p> 4195<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> 4196<p>When <code>file</code> is a file descriptor, the behavior is almost identical to directly 4197calling <code>fs.write()</code> like:</p> 4198<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>; 4199 4200<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> 4201<p>The difference from directly calling <code>fs.write()</code> is that under some unusual 4202conditions, <code>fs.write()</code> might write only part of the buffer and need to be 4203retried to write the remaining data, whereas <code>fs.writeFile()</code> retries until 4204the data is entirely written (or an error occurs).</p> 4205<p>The implications of this are a common source of confusion. In 4206the file descriptor case, the file is not replaced! The data is not necessarily 4207written to the beginning of the file, and the file's original data may remain 4208before and/or after the newly written data.</p> 4209<p>For example, if <code>fs.writeFile()</code> is called twice in a row, first to write the 4210string <code>'Hello'</code>, then to write the string <code>', World'</code>, the file would contain 4211<code>'Hello, World'</code>, and might contain some of the file's original data (depending 4212on the size of the original file, and the position of the file descriptor). If 4213a file name had been used instead of a descriptor, the file would be guaranteed 4214to contain only <code>', World'</code>.</p> 4215<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> 4216<div class="api_metadata"> 4217<span>Added in: v12.9.0</span> 4218</div> 4219<ul> 4220<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4221<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4222<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4223<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4224<ul> 4225<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4226<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4227<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4228</ul> 4229</li> 4230</ul> 4231<p>Write an array of <code>ArrayBufferView</code>s to the file specified by <code>fd</code> using 4232<code>writev()</code>.</p> 4233<p><code>position</code> is the offset from the beginning of the file where this data 4234should be written. If <code>typeof position !== 'number'</code>, the data will be written 4235at the current position.</p> 4236<p>The callback will be given three arguments: <code>err</code>, <code>bytesWritten</code>, and 4237<code>buffers</code>. <code>bytesWritten</code> is how many bytes were written from <code>buffers</code>.</p> 4238<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 4239<code>Object</code> with <code>bytesWritten</code> and <code>buffers</code> properties.</p> 4240<p>It is unsafe to use <code>fs.writev()</code> multiple times on the same file without 4241waiting for the callback. For this scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4242<p>On Linux, positional writes don't work when the file is opened in append mode. 4243The kernel ignores the position argument and always appends the data to 4244the end of the file.</p> 4245</section><section><h3>Synchronous API<span><a class="mark" href="#fs_synchronous_api" id="fs_synchronous_api">#</a></span></h3> 4246<p>The synchronous APIs perform all operations synchronously, blocking the 4247event loop until the operation completes or fails.</p> 4248<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> 4249<div class="api_metadata"> 4250<details class="changelog"><summary>History</summary> 4251<table> 4252<tbody><tr><th>Version</th><th>Changes</th></tr> 4253<tr><td>v7.6.0</td> 4254<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4255<tr><td>v0.11.15</td> 4256<td><p><span>Added in: v0.11.15</span></p></td></tr> 4257</tbody></table> 4258</details> 4259</div> 4260<ul> 4261<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> 4262<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> 4263</ul> 4264<p>Synchronously tests a user's permissions for the file or directory specified 4265by <code>path</code>. The <code>mode</code> argument is an optional integer that specifies the 4266accessibility checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for 4267possible values of <code>mode</code>. It is possible to create a mask consisting of 4268the bitwise OR of two or more values 4269(e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 4270<p>If any of the accessibility checks fail, an <code>Error</code> will be thrown. Otherwise, 4271the method will return <code>undefined</code>.</p> 4272<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>; 4273 4274<span class="hljs-keyword">try</span> { 4275 <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>); 4276 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can read/write'</span>); 4277} <span class="hljs-keyword">catch</span> (err) { 4278 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'no access!'</span>); 4279}</code></pre> 4280<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> 4281<div class="api_metadata"> 4282<details class="changelog"><summary>History</summary> 4283<table> 4284<tbody><tr><th>Version</th><th>Changes</th></tr> 4285<tr><td>v7.0.0</td> 4286<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 4287<tr><td>v5.0.0</td> 4288<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4289<tr><td>v0.6.7</td> 4290<td><p><span>Added in: v0.6.7</span></p></td></tr> 4291</tbody></table> 4292</details> 4293</div> 4294<ul> 4295<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> 4296<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> 4297<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> 4298<ul> 4299<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> 4300<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> 4301<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> 4302</ul> 4303</li> 4304</ul> 4305<p>Synchronously append data to a file, creating the file if it does not yet 4306exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 4307<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> 4308for more details.</p> 4309<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>; 4310 4311<span class="hljs-keyword">try</span> { 4312 <span class="hljs-title function_">appendFileSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>); 4313 <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>); 4314} <span class="hljs-keyword">catch</span> (err) { 4315 <span class="hljs-comment">/* Handle the error */</span> 4316}</code></pre> 4317<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4318<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>; 4319 4320<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> 4321<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened 4322for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will 4323not be closed automatically.</p> 4324<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>; 4325 4326<span class="hljs-keyword">let</span> fd; 4327 4328<span class="hljs-keyword">try</span> { 4329 fd = <span class="hljs-title function_">openSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'a'</span>); 4330 <span class="hljs-title function_">appendFileSync</span>(fd, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>); 4331} <span class="hljs-keyword">catch</span> (err) { 4332 <span class="hljs-comment">/* Handle the error */</span> 4333} <span class="hljs-keyword">finally</span> { 4334 <span class="hljs-keyword">if</span> (fd !== <span class="hljs-literal">undefined</span>) 4335 <span class="hljs-title function_">closeSync</span>(fd); 4336}</code></pre> 4337<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> 4338<div class="api_metadata"> 4339<details class="changelog"><summary>History</summary> 4340<table> 4341<tbody><tr><th>Version</th><th>Changes</th></tr> 4342<tr><td>v7.6.0</td> 4343<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4344<tr><td>v0.6.7</td> 4345<td><p><span>Added in: v0.6.7</span></p></td></tr> 4346</tbody></table> 4347</details> 4348</div> 4349<ul> 4350<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> 4351<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> 4352</ul> 4353<p>For detailed information, see the documentation of the asynchronous version of 4354this API: <a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p> 4355<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> 4356<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> 4357<div class="api_metadata"> 4358<details class="changelog"><summary>History</summary> 4359<table> 4360<tbody><tr><th>Version</th><th>Changes</th></tr> 4361<tr><td>v7.6.0</td> 4362<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4363<tr><td>v0.1.97</td> 4364<td><p><span>Added in: v0.1.97</span></p></td></tr> 4365</tbody></table> 4366</details> 4367</div> 4368<ul> 4369<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> 4370<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4371<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4372</ul> 4373<p>Synchronously changes owner and group of a file. Returns <code>undefined</code>. 4374This is the synchronous version of <a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown()</code></a>.</p> 4375<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> 4376<h4><code>fs.closeSync(fd)</code><span><a class="mark" href="#fs_fs_closesync_fd" id="fs_fs_closesync_fd">#</a></span></h4> 4377<div class="api_metadata"> 4378<span>Added in: v0.1.21</span> 4379</div> 4380<ul> 4381<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4382</ul> 4383<p>Closes the file descriptor. Returns <code>undefined</code>.</p> 4384<p>Calling <code>fs.closeSync()</code> on any file descriptor (<code>fd</code>) that is currently in use 4385through any other <code>fs</code> operation may lead to undefined behavior.</p> 4386<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> 4387<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> 4388<div class="api_metadata"> 4389<details class="changelog"><summary>History</summary> 4390<table> 4391<tbody><tr><th>Version</th><th>Changes</th></tr> 4392<tr><td>v14.0.0</td> 4393<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 4394<tr><td>v8.5.0</td> 4395<td><p><span>Added in: v8.5.0</span></p></td></tr> 4396</tbody></table> 4397</details> 4398</div> 4399<ul> 4400<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> 4401<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> 4402<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> 4403</ul> 4404<p>Synchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 4405already exists. Returns <code>undefined</code>. Node.js makes no guarantees about the 4406atomicity of the copy operation. If an error occurs after the destination file 4407has been opened for writing, Node.js will attempt to remove the destination.</p> 4408<p><code>mode</code> is an optional integer that specifies the behavior 4409of the copy operation. It is possible to create a mask consisting of the bitwise 4410OR of two or more values (e.g. 4411<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p> 4412<ul> 4413<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already 4414exists.</li> 4415<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a 4416copy-on-write reflink. If the platform does not support copy-on-write, then a 4417fallback copy mechanism is used.</li> 4418<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 4419create a copy-on-write reflink. If the platform does not support 4420copy-on-write, then the operation will fail.</li> 4421</ul> 4422<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>; 4423 4424<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span> 4425<span class="hljs-title function_">copyFileSync</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>); 4426<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>); 4427 4428<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 4429<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> 4430<h4><code>fs.existsSync(path)</code><span><a class="mark" href="#fs_fs_existssync_path" id="fs_fs_existssync_path">#</a></span></h4> 4431<div class="api_metadata"> 4432<details class="changelog"><summary>History</summary> 4433<table> 4434<tbody><tr><th>Version</th><th>Changes</th></tr> 4435<tr><td>v7.6.0</td> 4436<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4437<tr><td>v0.1.21</td> 4438<td><p><span>Added in: v0.1.21</span></p></td></tr> 4439</tbody></table> 4440</details> 4441</div> 4442<ul> 4443<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> 4444<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 4445</ul> 4446<p>Returns <code>true</code> if the path exists, <code>false</code> otherwise.</p> 4447<p>For detailed information, see the documentation of the asynchronous version of 4448this API: <a href="#fs_fs_exists_path_callback"><code>fs.exists()</code></a>.</p> 4449<p><code>fs.exists()</code> is deprecated, but <code>fs.existsSync()</code> is not. The <code>callback</code> 4450parameter to <code>fs.exists()</code> accepts parameters that are inconsistent with other 4451Node.js callbacks. <code>fs.existsSync()</code> does not use a callback.</p> 4452<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>; 4453 4454<span class="hljs-keyword">if</span> (<span class="hljs-title function_">existsSync</span>(<span class="hljs-string">'/etc/passwd'</span>)) 4455 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The path exists.'</span>);</code></pre> 4456<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> 4457<div class="api_metadata"> 4458<span>Added in: v0.4.7</span> 4459</div> 4460<ul> 4461<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4462<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> 4463</ul> 4464<p>Sets the permissions on the file. Returns <code>undefined</code>.</p> 4465<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> 4466<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> 4467<div class="api_metadata"> 4468<span>Added in: v0.4.7</span> 4469</div> 4470<ul> 4471<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4472<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> 4473<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> 4474</ul> 4475<p>Sets the owner of the file. Returns <code>undefined</code>.</p> 4476<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> 4477<h4><code>fs.fdatasyncSync(fd)</code><span><a class="mark" href="#fs_fs_fdatasyncsync_fd" id="fs_fs_fdatasyncsync_fd">#</a></span></h4> 4478<div class="api_metadata"> 4479<span>Added in: v0.1.96</span> 4480</div> 4481<ul> 4482<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4483</ul> 4484<p>Forces all currently queued I/O operations associated with the file to the 4485operating system's synchronized I/O completion state. Refer to the POSIX 4486<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> 4487<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> 4488<div class="api_metadata"> 4489<details class="changelog"><summary>History</summary> 4490<table> 4491<tbody><tr><th>Version</th><th>Changes</th></tr> 4492<tr><td>v10.5.0</td> 4493<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4494<tr><td>v0.1.95</td> 4495<td><p><span>Added in: v0.1.95</span></p></td></tr> 4496</tbody></table> 4497</details> 4498</div> 4499<ul> 4500<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4501<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4502<ul> 4503<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 4504<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> 4505</ul> 4506</li> 4507<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4508</ul> 4509<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file descriptor.</p> 4510<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> 4511<h4><code>fs.fsyncSync(fd)</code><span><a class="mark" href="#fs_fs_fsyncsync_fd" id="fs_fs_fsyncsync_fd">#</a></span></h4> 4512<div class="api_metadata"> 4513<span>Added in: v0.1.96</span> 4514</div> 4515<ul> 4516<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4517</ul> 4518<p>Request that all data for the open file descriptor is flushed to the storage 4519device. The specific implementation is operating system and device specific. 4520Refer 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> 4521<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> 4522<div class="api_metadata"> 4523<span>Added in: v0.8.6</span> 4524</div> 4525<ul> 4526<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4527<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> 4528</ul> 4529<p>Truncates the file descriptor. Returns <code>undefined</code>.</p> 4530<p>For detailed information, see the documentation of the asynchronous version of 4531this API: <a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate()</code></a>.</p> 4532<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> 4533<div class="api_metadata"> 4534<details class="changelog"><summary>History</summary> 4535<table> 4536<tbody><tr><th>Version</th><th>Changes</th></tr> 4537<tr><td>v4.1.0</td> 4538<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 4539<tr><td>v0.4.2</td> 4540<td><p><span>Added in: v0.4.2</span></p></td></tr> 4541</tbody></table> 4542</details> 4543</div> 4544<ul> 4545<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4546<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> 4547<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> 4548</ul> 4549<p>Synchronous version of <a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes()</code></a>. Returns <code>undefined</code>.</p> 4550<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> 4551<div class="api_metadata"> 4552<span>Deprecated since: v0.4.7</span> 4553</div> 4554<ul> 4555<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> 4556<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4557</ul> 4558<p>Changes the permissions on a symbolic link. Returns <code>undefined</code>.</p> 4559<p>This method is only implemented on macOS.</p> 4560<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> 4561<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> 4562<div class="api_metadata"> 4563<details class="changelog"><summary>History</summary> 4564<table> 4565<tbody><tr><th>Version</th><th>Changes</th></tr> 4566<tr><td>v10.6.0</td> 4567<td><p>This API is no longer deprecated.</p></td></tr> 4568<tr><td>v0.4.7</td> 4569<td><p>Documentation-only deprecation.</p></td></tr> 4570</tbody></table> 4571</details> 4572</div> 4573<ul> 4574<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> 4575<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> 4576<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> 4577</ul> 4578<p>Set the owner for the path. Returns <code>undefined</code>.</p> 4579<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> 4580<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> 4581<div class="api_metadata"> 4582<span>Added in: v14.5.0, v12.19.0</span> 4583</div> 4584<ul> 4585<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> 4586<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> 4587<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> 4588</ul> 4589<p>Change the file system timestamps of the symbolic link referenced by <code>path</code>. 4590Returns <code>undefined</code>, or throws an exception when parameters are incorrect or 4591the operation fails. This is the synchronous version of <a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes()</code></a>.</p> 4592<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> 4593<div class="api_metadata"> 4594<details class="changelog"><summary>History</summary> 4595<table> 4596<tbody><tr><th>Version</th><th>Changes</th></tr> 4597<tr><td>v7.6.0</td> 4598<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> 4599<tr><td>v0.1.31</td> 4600<td><p><span>Added in: v0.1.31</span></p></td></tr> 4601</tbody></table> 4602</details> 4603</div> 4604<ul> 4605<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> 4606<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> 4607</ul> 4608<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 4609<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> 4610<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> 4611<div class="api_metadata"> 4612<details class="changelog"><summary>History</summary> 4613<table> 4614<tbody><tr><th>Version</th><th>Changes</th></tr> 4615<tr><td>v14.17.0</td> 4616<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> 4617<tr><td>v10.5.0</td> 4618<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4619<tr><td>v7.6.0</td> 4620<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4621<tr><td>v0.1.30</td> 4622<td><p><span>Added in: v0.1.30</span></p></td></tr> 4623</tbody></table> 4624</details> 4625</div> 4626<ul> 4627<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> 4628<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4629<ul> 4630<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 4631<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> 4632<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 4633if no file system entry exists, rather than returning <code>undefined</code>. 4634<strong>Default:</strong> <code>true</code>.</li> 4635</ul> 4636</li> 4637<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4638</ul> 4639<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> 4640<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> 4641<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> 4642<div class="api_metadata"> 4643<details class="changelog"><summary>History</summary> 4644<table> 4645<tbody><tr><th>Version</th><th>Changes</th></tr> 4646<tr><td>v13.11.0, v12.17.0</td> 4647<td><p>In <code>recursive</code> mode, the first created path is returned now.</p></td></tr> 4648<tr><td>v10.12.0</td> 4649<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> 4650<tr><td>v7.6.0</td> 4651<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4652<tr><td>v0.1.21</td> 4653<td><p><span>Added in: v0.1.21</span></p></td></tr> 4654</tbody></table> 4655</details> 4656</div> 4657<ul> 4658<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> 4659<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> 4660<ul> 4661<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> 4662<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> 4663</ul> 4664</li> 4665<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> 4666</ul> 4667<p>Synchronously creates a directory. Returns <code>undefined</code>, or if <code>recursive</code> is 4668<code>true</code>, the first directory path created. 4669This is the synchronous version of <a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir()</code></a>.</p> 4670<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> 4671<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> 4672<div class="api_metadata"> 4673<details class="changelog"><summary>History</summary> 4674<table> 4675<tbody><tr><th>Version</th><th>Changes</th></tr> 4676<tr><td>v14.18.0</td> 4677<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 4678<tr><td>v5.10.0</td> 4679<td><p><span>Added in: v5.10.0</span></p></td></tr> 4680</tbody></table> 4681</details> 4682</div> 4683<ul> 4684<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4685<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> 4686<ul> 4687<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> 4688</ul> 4689</li> 4690<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4691</ul> 4692<p>Returns the created directory path.</p> 4693<p>For detailed information, see the documentation of the asynchronous version of 4694this API: <a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp()</code></a>.</p> 4695<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4696object with an <code>encoding</code> property specifying the character encoding to use.</p> 4697<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> 4698<div class="api_metadata"> 4699<details class="changelog"><summary>History</summary> 4700<table> 4701<tbody><tr><th>Version</th><th>Changes</th></tr> 4702<tr><td>v13.1.0, v12.16.0</td> 4703<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 4704<tr><td>v12.12.0</td> 4705<td><p><span>Added in: v12.12.0</span></p></td></tr> 4706</tbody></table> 4707</details> 4708</div> 4709<ul> 4710<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> 4711<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4712<ul> 4713<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> 4714<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 4715internally when reading from the directory. Higher values lead to better 4716performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 4717</ul> 4718</li> 4719<li>Returns: <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li> 4720</ul> 4721<p>Synchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p> 4722<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 4723and cleaning up the directory.</p> 4724<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 4725directory and subsequent read operations.</p> 4726<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> 4727<div class="api_metadata"> 4728<details class="changelog"><summary>History</summary> 4729<table> 4730<tbody><tr><th>Version</th><th>Changes</th></tr> 4731<tr><td>v11.1.0</td> 4732<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 4733<tr><td>v9.9.0</td> 4734<td><p>The <code>as</code> and <code>as+</code> flags are supported now.</p></td></tr> 4735<tr><td>v7.6.0</td> 4736<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4737<tr><td>v0.1.21</td> 4738<td><p><span>Added in: v0.1.21</span></p></td></tr> 4739</tbody></table> 4740</details> 4741</div> 4742<ul> 4743<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> 4744<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>. 4745See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.</li> 4746<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> 4747<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4748</ul> 4749<p>Returns an integer representing the file descriptor.</p> 4750<p>For detailed information, see the documentation of the asynchronous version of 4751this API: <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a>.</p> 4752<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> 4753<div class="api_metadata"> 4754<details class="changelog"><summary>History</summary> 4755<table> 4756<tbody><tr><th>Version</th><th>Changes</th></tr> 4757<tr><td>v10.10.0</td> 4758<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 4759<tr><td>v7.6.0</td> 4760<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4761<tr><td>v0.1.21</td> 4762<td><p><span>Added in: v0.1.21</span></p></td></tr> 4763</tbody></table> 4764</details> 4765</div> 4766<ul> 4767<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> 4768<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> 4769<ul> 4770<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> 4771<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> 4772</ul> 4773</li> 4774<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> 4775</ul> 4776<p>Reads the contents of the directory.</p> 4777<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> 4778<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4779object with an <code>encoding</code> property specifying the character encoding to use for 4780the filenames returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4781the filenames returned will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 4782<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the result will contain 4783<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 4784<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> 4785<div class="api_metadata"> 4786<details class="changelog"><summary>History</summary> 4787<table> 4788<tbody><tr><th>Version</th><th>Changes</th></tr> 4789<tr><td>v7.6.0</td> 4790<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4791<tr><td>v5.0.0</td> 4792<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr> 4793<tr><td>v0.1.8</td> 4794<td><p><span>Added in: v0.1.8</span></p></td></tr> 4795</tbody></table> 4796</details> 4797</div> 4798<ul> 4799<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> 4800<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> 4801<ul> 4802<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> 4803<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> 4804</ul> 4805</li> 4806<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> 4807</ul> 4808<p>Returns the contents of the <code>path</code>.</p> 4809<p>For detailed information, see the documentation of the asynchronous version of 4810this API: <a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile()</code></a>.</p> 4811<p>If the <code>encoding</code> option is specified then this function returns a 4812string. Otherwise it returns a buffer.</p> 4813<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 4814<code>fs.readFileSync()</code> is platform-specific.</p> 4815<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>; 4816 4817<span class="hljs-comment">// macOS, Linux, and Windows</span> 4818<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); 4819<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span> 4820 4821<span class="hljs-comment">// FreeBSD</span> 4822<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); <span class="hljs-comment">// => <data></span></code></pre> 4823<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> 4824<div class="api_metadata"> 4825<details class="changelog"><summary>History</summary> 4826<table> 4827<tbody><tr><th>Version</th><th>Changes</th></tr> 4828<tr><td>v7.6.0</td> 4829<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4830<tr><td>v0.1.31</td> 4831<td><p><span>Added in: v0.1.31</span></p></td></tr> 4832</tbody></table> 4833</details> 4834</div> 4835<ul> 4836<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> 4837<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> 4838<ul> 4839<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> 4840</ul> 4841</li> 4842<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> 4843</ul> 4844<p>Returns the symbolic link's string value.</p> 4845<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> 4846<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4847object with an <code>encoding</code> property specifying the character encoding to use for 4848the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4849the link path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4850<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> 4851<div class="api_metadata"> 4852<details class="changelog"><summary>History</summary> 4853<table> 4854<tbody><tr><th>Version</th><th>Changes</th></tr> 4855<tr><td>v10.10.0</td> 4856<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4857<tr><td>v6.0.0</td> 4858<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr> 4859<tr><td>v0.1.21</td> 4860<td><p><span>Added in: v0.1.21</span></p></td></tr> 4861</tbody></table> 4862</details> 4863</div> 4864<ul> 4865<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4866<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> 4867<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4868<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4869<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> 4870<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4871</ul> 4872<p>Returns the number of <code>bytesRead</code>.</p> 4873<p>For detailed information, see the documentation of the asynchronous version of 4874this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4875<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> 4876<div class="api_metadata"> 4877<details class="changelog"><summary>History</summary> 4878<table> 4879<tbody><tr><th>Version</th><th>Changes</th></tr> 4880<tr><td>v13.13.0, v12.17.0</td> 4881<td><p><span>Added in: v13.13.0, v12.17.0</span></p></td></tr> 4882<tr><td>v13.13.0, v12.17.0</td> 4883<td><p>Options object can be passed in to make offset, length and position optional.</p></td></tr> 4884</tbody></table> 4885</details> 4886</div> 4887<ul> 4888<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4889<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> 4890<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4891<ul> 4892<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> 4893<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> 4894<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> 4895</ul> 4896</li> 4897<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4898</ul> 4899<p>Returns the number of <code>bytesRead</code>.</p> 4900<p>Similar to the above <code>fs.readSync</code> function, this version takes an optional <code>options</code> object. 4901If no <code>options</code> object is specified, it will default with the above values.</p> 4902<p>For detailed information, see the documentation of the asynchronous version of 4903this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4904<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> 4905<div class="api_metadata"> 4906<span>Added in: v13.13.0, v12.17.0</span> 4907</div> 4908<ul> 4909<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4910<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4911<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4912<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> 4913</ul> 4914<p>For detailed information, see the documentation of the asynchronous version of 4915this API: <a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv()</code></a>.</p> 4916<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> 4917<div class="api_metadata"> 4918<details class="changelog"><summary>History</summary> 4919<table> 4920<tbody><tr><th>Version</th><th>Changes</th></tr> 4921<tr><td>v8.0.0</td> 4922<td><p>Pipe/Socket resolve support was added.</p></td></tr> 4923<tr><td>v7.6.0</td> 4924<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4925<tr><td>v6.4.0</td> 4926<td><p>Calling <code>realpathSync</code> now works again for various edge cases on Windows.</p></td></tr> 4927<tr><td>v6.0.0</td> 4928<td><p>The <code>cache</code> parameter was removed.</p></td></tr> 4929<tr><td>v0.1.31</td> 4930<td><p><span>Added in: v0.1.31</span></p></td></tr> 4931</tbody></table> 4932</details> 4933</div> 4934<ul> 4935<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> 4936<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> 4937<ul> 4938<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> 4939</ul> 4940</li> 4941<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> 4942</ul> 4943<p>Returns the resolved pathname.</p> 4944<p>For detailed information, see the documentation of the asynchronous version of 4945this API: <a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath()</code></a>.</p> 4946<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> 4947<div class="api_metadata"> 4948<span>Added in: v9.2.0</span> 4949</div> 4950<ul> 4951<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> 4952<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> 4953<ul> 4954<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> 4955</ul> 4956</li> 4957<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> 4958</ul> 4959<p>Synchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p> 4960<p>Only paths that can be converted to UTF8 strings are supported.</p> 4961<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4962object with an <code>encoding</code> property specifying the character encoding to use for 4963the path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4964the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4965<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 4966be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 4967this restriction.</p> 4968<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> 4969<div class="api_metadata"> 4970<details class="changelog"><summary>History</summary> 4971<table> 4972<tbody><tr><th>Version</th><th>Changes</th></tr> 4973<tr><td>v7.6.0</td> 4974<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> 4975<tr><td>v0.1.21</td> 4976<td><p><span>Added in: v0.1.21</span></p></td></tr> 4977</tbody></table> 4978</details> 4979</div> 4980<ul> 4981<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> 4982<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> 4983</ul> 4984<p>Renames the file from <code>oldPath</code> to <code>newPath</code>. Returns <code>undefined</code>.</p> 4985<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> 4986<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> 4987<div class="api_metadata"> 4988<details class="changelog"><summary>History</summary> 4989<table> 4990<tbody><tr><th>Version</th><th>Changes</th></tr> 4991<tr><td>v14.14.0</td> 4992<td><p>The <code>recursive</code> option is deprecated, use <code>fs.rmSync</code> instead.</p></td></tr> 4993<tr><td>v13.3.0, v12.16.0</td> 4994<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> 4995<tr><td>v12.10.0</td> 4996<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 4997<tr><td>v7.6.0</td> 4998<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4999<tr><td>v0.1.21</td> 5000<td><p><span>Added in: v0.1.21</span></p></td></tr> 5001</tbody></table> 5002</details> 5003</div> 5004<ul> 5005<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> 5006<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5007<ul> 5008<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 5009<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 5010backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5011represents the number of retries. This option is ignored if the <code>recursive</code> 5012option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5013<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 5014recursive mode, errors are not reported if <code>path</code> does not exist, and 5015operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5016<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 5017retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5018<strong>Default:</strong> <code>100</code>.</li> 5019</ul> 5020</li> 5021</ul> 5022<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"><code>rmdir(2)</code></a>. Returns <code>undefined</code>.</p> 5023<p>Using <code>fs.rmdirSync()</code> on a file (not a directory) results in an <code>ENOENT</code> error 5024on Windows and an <code>ENOTDIR</code> error on POSIX.</p> 5025<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 5026<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 5027that represent files will be deleted. The permissive behavior of the 5028<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 5029the future.</p> 5030<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> 5031<div class="api_metadata"> 5032<span>Added in: v14.14.0</span> 5033</div> 5034<ul> 5035<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> 5036<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5037<ul> 5038<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 5039not exist. <strong>Default:</strong> <code>false</code>.</li> 5040<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 5041<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 5042backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5043represents the number of retries. This option is ignored if the <code>recursive</code> 5044option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5045<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 5046recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5047<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 5048retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5049<strong>Default:</strong> <code>100</code>.</li> 5050</ul> 5051</li> 5052</ul> 5053<p>Synchronously removes files and directories (modeled on the standard POSIX <code>rm</code> 5054utility). Returns <code>undefined</code>.</p> 5055<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> 5056<div class="api_metadata"> 5057<details class="changelog"><summary>History</summary> 5058<table> 5059<tbody><tr><th>Version</th><th>Changes</th></tr> 5060<tr><td>v14.17.0</td> 5061<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> 5062<tr><td>v10.5.0</td> 5063<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 5064<tr><td>v7.6.0</td> 5065<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5066<tr><td>v0.1.21</td> 5067<td><p><span>Added in: v0.1.21</span></p></td></tr> 5068</tbody></table> 5069</details> 5070</div> 5071<ul> 5072<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> 5073<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5074<ul> 5075<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 5076<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> 5077<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 5078if no file system entry exists, rather than returning <code>undefined</code>. 5079<strong>Default:</strong> <code>true</code>.</li> 5080</ul> 5081</li> 5082<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 5083</ul> 5084<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the path.</p> 5085<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> 5086<div class="api_metadata"> 5087<details class="changelog"><summary>History</summary> 5088<table> 5089<tbody><tr><th>Version</th><th>Changes</th></tr> 5090<tr><td>v12.0.0</td> 5091<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> 5092<tr><td>v7.6.0</td> 5093<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> 5094<tr><td>v0.1.31</td> 5095<td><p><span>Added in: v0.1.31</span></p></td></tr> 5096</tbody></table> 5097</details> 5098</div> 5099<ul> 5100<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> 5101<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> 5102<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5103</ul> 5104<p>Returns <code>undefined</code>.</p> 5105<p>For detailed information, see the documentation of the asynchronous version of 5106this API: <a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink()</code></a>.</p> 5107<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> 5108<div class="api_metadata"> 5109<span>Added in: v0.8.6</span> 5110</div> 5111<ul> 5112<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> 5113<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> 5114</ul> 5115<p>Truncates the file. Returns <code>undefined</code>. A file descriptor can also be 5116passed as the first argument. In this case, <code>fs.ftruncateSync()</code> is called.</p> 5117<p>Passing a file descriptor is deprecated and may result in an error being thrown 5118in the future.</p> 5119<h4><code>fs.unlinkSync(path)</code><span><a class="mark" href="#fs_fs_unlinksync_path" id="fs_fs_unlinksync_path">#</a></span></h4> 5120<div class="api_metadata"> 5121<details class="changelog"><summary>History</summary> 5122<table> 5123<tbody><tr><th>Version</th><th>Changes</th></tr> 5124<tr><td>v7.6.0</td> 5125<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5126<tr><td>v0.1.21</td> 5127<td><p><span>Added in: v0.1.21</span></p></td></tr> 5128</tbody></table> 5129</details> 5130</div> 5131<ul> 5132<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> 5133</ul> 5134<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>. Returns <code>undefined</code>.</p> 5135<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> 5136<div class="api_metadata"> 5137<details class="changelog"><summary>History</summary> 5138<table> 5139<tbody><tr><th>Version</th><th>Changes</th></tr> 5140<tr><td>v8.0.0</td> 5141<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr> 5142<tr><td>v7.6.0</td> 5143<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5144<tr><td>v4.1.0</td> 5145<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 5146<tr><td>v0.4.2</td> 5147<td><p><span>Added in: v0.4.2</span></p></td></tr> 5148</tbody></table> 5149</details> 5150</div> 5151<ul> 5152<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> 5153<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> 5154<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> 5155</ul> 5156<p>Returns <code>undefined</code>.</p> 5157<p>For detailed information, see the documentation of the asynchronous version of 5158this API: <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p> 5159<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> 5160<div class="api_metadata"> 5161<details class="changelog"><summary>History</summary> 5162<table> 5163<tbody><tr><th>Version</th><th>Changes</th></tr> 5164<tr><td>v14.12.0</td> 5165<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 5166<tr><td>v14.0.0</td> 5167<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5168<tr><td>v10.10.0</td> 5169<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5170<tr><td>v7.4.0</td> 5171<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5172<tr><td>v5.0.0</td> 5173<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 5174<tr><td>v0.1.29</td> 5175<td><p><span>Added in: v0.1.29</span></p></td></tr> 5176</tbody></table> 5177</details> 5178</div> 5179<ul> 5180<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> 5181<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> 5182<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> 5183<ul> 5184<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> 5185<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> 5186<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> 5187</ul> 5188</li> 5189</ul> 5190<p>Returns <code>undefined</code>.</p> 5191<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 5192function property.</p> 5193<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> 5194for more details.</p> 5195<p>For detailed information, see the documentation of the asynchronous version of 5196this API: <a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile()</code></a>.</p> 5197<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> 5198<div class="api_metadata"> 5199<details class="changelog"><summary>History</summary> 5200<table> 5201<tbody><tr><th>Version</th><th>Changes</th></tr> 5202<tr><td>v14.0.0</td> 5203<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5204<tr><td>v10.10.0</td> 5205<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5206<tr><td>v7.4.0</td> 5207<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5208<tr><td>v7.2.0</td> 5209<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 5210<tr><td>v0.1.21</td> 5211<td><p><span>Added in: v0.1.21</span></p></td></tr> 5212</tbody></table> 5213</details> 5214</div> 5215<ul> 5216<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5217<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> 5218<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5219<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5220<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5221<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> 5222</ul> 5223<p>For detailed information, see the documentation of the asynchronous version of 5224this API: <a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer...)</code></a>.</p> 5225<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> 5226<div class="api_metadata"> 5227<details class="changelog"><summary>History</summary> 5228<table> 5229<tbody><tr><th>Version</th><th>Changes</th></tr> 5230<tr><td>v14.0.0</td> 5231<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5232<tr><td>v7.2.0</td> 5233<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 5234<tr><td>v0.11.5</td> 5235<td><p><span>Added in: v0.11.5</span></p></td></tr> 5236</tbody></table> 5237</details> 5238</div> 5239<ul> 5240<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5241<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5242<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5243<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5244<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> 5245</ul> 5246<p>For detailed information, see the documentation of the asynchronous version of 5247this API: <a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string...)</code></a>.</p> 5248<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> 5249<div class="api_metadata"> 5250<span>Added in: v12.9.0</span> 5251</div> 5252<ul> 5253<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5254<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 5255<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5256<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> 5257</ul> 5258<p>For detailed information, see the documentation of the asynchronous version of 5259this API: <a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev()</code></a>.</p> 5260</section><section><h3>Common Objects<span><a class="mark" href="#fs_common_objects" id="fs_common_objects">#</a></span></h3> 5261<p>The common objects are shared by all of the file system API variants 5262(promise, callback, and synchronous).</p> 5263<h4>Class: <code>fs.Dir</code><span><a class="mark" href="#fs_class_fs_dir" id="fs_class_fs_dir">#</a></span></h4> 5264<div class="api_metadata"> 5265<span>Added in: v12.12.0</span> 5266</div> 5267<p>A class representing a directory stream.</p> 5268<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 5269<a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir()</code></a>.</p> 5270<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>; 5271 5272<span class="hljs-keyword">try</span> { 5273 <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>); 5274 <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) 5275 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 5276} <span class="hljs-keyword">catch</span> (err) { 5277 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 5278}</code></pre> 5279<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 5280closed after the iterator exits.</p> 5281<h5><code>dir.close()</code><span><a class="mark" href="#fs_dir_close" id="fs_dir_close">#</a></span></h5> 5282<div class="api_metadata"> 5283<span>Added in: v12.12.0</span> 5284</div> 5285<ul> 5286<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 5287</ul> 5288<p>Asynchronously close the directory's underlying resource handle. 5289Subsequent reads will result in errors.</p> 5290<p>A promise is returned that will be resolved after the resource has been 5291closed.</p> 5292<h5><code>dir.close(callback)</code><span><a class="mark" href="#fs_dir_close_callback" id="fs_dir_close_callback">#</a></span></h5> 5293<div class="api_metadata"> 5294<span>Added in: v12.12.0</span> 5295</div> 5296<ul> 5297<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5298<ul> 5299<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5300</ul> 5301</li> 5302</ul> 5303<p>Asynchronously close the directory's underlying resource handle. 5304Subsequent reads will result in errors.</p> 5305<p>The <code>callback</code> will be called after the resource handle has been closed.</p> 5306<h5><code>dir.closeSync()</code><span><a class="mark" href="#fs_dir_closesync" id="fs_dir_closesync">#</a></span></h5> 5307<div class="api_metadata"> 5308<span>Added in: v12.12.0</span> 5309</div> 5310<p>Synchronously close the directory's underlying resource handle. 5311Subsequent reads will result in errors.</p> 5312<h5><code>dir.path</code><span><a class="mark" href="#fs_dir_path" id="fs_dir_path">#</a></span></h5> 5313<div class="api_metadata"> 5314<span>Added in: v12.12.0</span> 5315</div> 5316<ul> 5317<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5318</ul> 5319<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>, 5320<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> 5321<h5><code>dir.read()</code><span><a class="mark" href="#fs_dir_read" id="fs_dir_read">#</a></span></h5> 5322<div class="api_metadata"> 5323<span>Added in: v12.12.0</span> 5324</div> 5325<ul> 5326<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> 5327</ul> 5328<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 5329<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5330<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> 5331if there are no more directory entries to read.</p> 5332<p>Directory entries returned by this function are in no particular order as 5333provided by the operating system's underlying directory mechanisms. 5334Entries added or removed while iterating over the directory might not be 5335included in the iteration results.</p> 5336<h5><code>dir.read(callback)</code><span><a class="mark" href="#fs_dir_read_callback" id="fs_dir_read_callback">#</a></span></h5> 5337<div class="api_metadata"> 5338<span>Added in: v12.12.0</span> 5339</div> 5340<ul> 5341<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5342<ul> 5343<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5344<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> 5345</ul> 5346</li> 5347</ul> 5348<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 5349<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5350<p>After the read is completed, the <code>callback</code> will be called with an 5351<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> 5352<p>Directory entries returned by this function are in no particular order as 5353provided by the operating system's underlying directory mechanisms. 5354Entries added or removed while iterating over the directory might not be 5355included in the iteration results.</p> 5356<h5><code>dir.readSync()</code><span><a class="mark" href="#fs_dir_readsync" id="fs_dir_readsync">#</a></span></h5> 5357<div class="api_metadata"> 5358<span>Added in: v12.12.0</span> 5359</div> 5360<ul> 5361<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> 5362</ul> 5363<p>Synchronously read the next directory entry as an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. See the 5364POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more detail.</p> 5365<p>If there are no more directory entries to read, <code>null</code> will be returned.</p> 5366<p>Directory entries returned by this function are in no particular order as 5367provided by the operating system's underlying directory mechanisms. 5368Entries added or removed while iterating over the directory might not be 5369included in the iteration results.</p> 5370<h5><code>dir[Symbol.asyncIterator]()</code><span><a class="mark" href="#fs_dir_symbol_asynciterator" id="fs_dir_symbol_asynciterator">#</a></span></h5> 5371<div class="api_metadata"> 5372<span>Added in: v12.12.0</span> 5373</div> 5374<ul> 5375<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> 5376</ul> 5377<p>Asynchronously iterates over the directory until all entries have 5378been 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> 5379<p>Entries returned by the async iterator are always an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. 5380The <code>null</code> case from <code>dir.read()</code> is handled internally.</p> 5381<p>See <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> for an example.</p> 5382<p>Directory entries returned by this iterator are in no particular order as 5383provided by the operating system's underlying directory mechanisms. 5384Entries added or removed while iterating over the directory might not be 5385included in the iteration results.</p> 5386<h4>Class: <code>fs.Dirent</code><span><a class="mark" href="#fs_class_fs_dirent" id="fs_class_fs_dirent">#</a></span></h4> 5387<div class="api_metadata"> 5388<span>Added in: v10.10.0</span> 5389</div> 5390<p>A representation of a directory entry, which can be a file or a subdirectory 5391within the directory, as returned by reading from an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>. The 5392directory entry is a combination of the file name and file type pairs.</p> 5393<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 5394the <code>withFileTypes</code> option set to <code>true</code>, the resulting array is filled with 5395<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> 5396<h5><code>dirent.isBlockDevice()</code><span><a class="mark" href="#fs_dirent_isblockdevice" id="fs_dirent_isblockdevice">#</a></span></h5> 5397<div class="api_metadata"> 5398<span>Added in: v10.10.0</span> 5399</div> 5400<ul> 5401<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5402</ul> 5403<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> 5404<h5><code>dirent.isCharacterDevice()</code><span><a class="mark" href="#fs_dirent_ischaracterdevice" id="fs_dirent_ischaracterdevice">#</a></span></h5> 5405<div class="api_metadata"> 5406<span>Added in: v10.10.0</span> 5407</div> 5408<ul> 5409<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5410</ul> 5411<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> 5412<h5><code>dirent.isDirectory()</code><span><a class="mark" href="#fs_dirent_isdirectory" id="fs_dirent_isdirectory">#</a></span></h5> 5413<div class="api_metadata"> 5414<span>Added in: v10.10.0</span> 5415</div> 5416<ul> 5417<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5418</ul> 5419<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 5420directory.</p> 5421<h5><code>dirent.isFIFO()</code><span><a class="mark" href="#fs_dirent_isfifo" id="fs_dirent_isfifo">#</a></span></h5> 5422<div class="api_metadata"> 5423<span>Added in: v10.10.0</span> 5424</div> 5425<ul> 5426<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5427</ul> 5428<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 5429(FIFO) pipe.</p> 5430<h5><code>dirent.isFile()</code><span><a class="mark" href="#fs_dirent_isfile" id="fs_dirent_isfile">#</a></span></h5> 5431<div class="api_metadata"> 5432<span>Added in: v10.10.0</span> 5433</div> 5434<ul> 5435<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5436</ul> 5437<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> 5438<h5><code>dirent.isSocket()</code><span><a class="mark" href="#fs_dirent_issocket" id="fs_dirent_issocket">#</a></span></h5> 5439<div class="api_metadata"> 5440<span>Added in: v10.10.0</span> 5441</div> 5442<ul> 5443<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5444</ul> 5445<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> 5446<h5><code>dirent.isSymbolicLink()</code><span><a class="mark" href="#fs_dirent_issymboliclink" id="fs_dirent_issymboliclink">#</a></span></h5> 5447<div class="api_metadata"> 5448<span>Added in: v10.10.0</span> 5449</div> 5450<ul> 5451<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5452</ul> 5453<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> 5454<h5><code>dirent.name</code><span><a class="mark" href="#fs_dirent_name" id="fs_dirent_name">#</a></span></h5> 5455<div class="api_metadata"> 5456<span>Added in: v10.10.0</span> 5457</div> 5458<ul> 5459<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> 5460</ul> 5461<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 5462value is determined by the <code>options.encoding</code> passed to <a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir()</code></a> or 5463<a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync()</code></a>.</p> 5464<h4>Class: <code>fs.FSWatcher</code><span><a class="mark" href="#fs_class_fs_fswatcher" id="fs_class_fs_fswatcher">#</a></span></h4> 5465<div class="api_metadata"> 5466<span>Added in: v0.5.8</span> 5467</div> 5468<ul> 5469<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5470</ul> 5471<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> 5472object.</p> 5473<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 5474file is modified.</p> 5475<h5>Event: <code>'change'</code><span><a class="mark" href="#fs_event_change" id="fs_event_change">#</a></span></h5> 5476<div class="api_metadata"> 5477<span>Added in: v0.5.8</span> 5478</div> 5479<ul> 5480<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> 5481<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> 5482</ul> 5483<p>Emitted when something changes in a watched directory or file. 5484See more details in <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a>.</p> 5485<p>The <code>filename</code> argument may not be provided depending on operating system 5486support. If <code>filename</code> is provided, it will be provided as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> if 5487<code>fs.watch()</code> is called with its <code>encoding</code> option set to <code>'buffer'</code>, otherwise 5488<code>filename</code> will be a UTF-8 string.</p> 5489<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>; 5490<span class="hljs-comment">// Example when handled through fs.watch() listener</span> 5491<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> { 5492 <span class="hljs-keyword">if</span> (filename) { 5493 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(filename); 5494 <span class="hljs-comment">// Prints: <Buffer ...></span> 5495 } 5496});</code></pre> 5497<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close" id="fs_event_close">#</a></span></h5> 5498<div class="api_metadata"> 5499<span>Added in: v10.0.0</span> 5500</div> 5501<p>Emitted when the watcher stops watching for changes. The closed 5502<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5503<h5>Event: <code>'error'</code><span><a class="mark" href="#fs_event_error" id="fs_event_error">#</a></span></h5> 5504<div class="api_metadata"> 5505<span>Added in: v0.5.8</span> 5506</div> 5507<ul> 5508<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5509</ul> 5510<p>Emitted when an error occurs while watching the file. The errored 5511<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5512<h5><code>watcher.close()</code><span><a class="mark" href="#fs_watcher_close" id="fs_watcher_close">#</a></span></h5> 5513<div class="api_metadata"> 5514<span>Added in: v0.5.8</span> 5515</div> 5516<p>Stop watching for changes on the given <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>. Once stopped, the 5517<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable.</p> 5518<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref" id="fs_watcher_ref">#</a></span></h5> 5519<div class="api_metadata"> 5520<span>Added in: v14.3.0, v12.20.0</span> 5521</div> 5522<ul> 5523<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5524</ul> 5525<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5526<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5527no effect.</p> 5528<p>By default, all <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> objects are "ref'ed", making it normally 5529unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5530called previously.</p> 5531<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref" id="fs_watcher_unref">#</a></span></h5> 5532<div class="api_metadata"> 5533<span>Added in: v14.3.0, v12.20.0</span> 5534</div> 5535<ul> 5536<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5537</ul> 5538<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 5539event loop to remain active. If there is no other activity keeping the 5540event loop running, the process may exit before the <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object's 5541callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5542no effect.</p> 5543<h4>Class: <code>fs.StatWatcher</code><span><a class="mark" href="#fs_class_fs_statwatcher" id="fs_class_fs_statwatcher">#</a></span></h4> 5544<div class="api_metadata"> 5545<span>Added in: v14.3.0, v12.20.0</span> 5546</div> 5547<ul> 5548<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5549</ul> 5550<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> 5551object.</p> 5552<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref_1" id="fs_watcher_ref_1">#</a></span></h5> 5553<div class="api_metadata"> 5554<span>Added in: v14.3.0, v12.20.0</span> 5555</div> 5556<ul> 5557<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5558</ul> 5559<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5560<a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5561no effect.</p> 5562<p>By default, all <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> objects are "ref'ed", making it normally 5563unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5564called previously.</p> 5565<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref_1" id="fs_watcher_unref_1">#</a></span></h5> 5566<div class="api_metadata"> 5567<span>Added in: v14.3.0, v12.20.0</span> 5568</div> 5569<ul> 5570<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5571</ul> 5572<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 5573event loop to remain active. If there is no other activity keeping the 5574event loop running, the process may exit before the <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> object's 5575callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5576no effect.</p> 5577<h4>Class: <code>fs.ReadStream</code><span><a class="mark" href="#fs_class_fs_readstream" id="fs_class_fs_readstream">#</a></span></h4> 5578<div class="api_metadata"> 5579<span>Added in: v0.1.93</span> 5580</div> 5581<ul> 5582<li>Extends: <a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li> 5583</ul> 5584<p>Instances of <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> are created and returned using the 5585<a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream()</code></a> function.</p> 5586<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_1" id="fs_event_close_1">#</a></span></h5> 5587<div class="api_metadata"> 5588<span>Added in: v0.1.93</span> 5589</div> 5590<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> 5591<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open" id="fs_event_open">#</a></span></h5> 5592<div class="api_metadata"> 5593<span>Added in: v0.1.93</span> 5594</div> 5595<ul> 5596<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> 5597</ul> 5598<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>'s file descriptor has been opened.</p> 5599<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready" id="fs_event_ready">#</a></span></h5> 5600<div class="api_metadata"> 5601<span>Added in: v9.11.0</span> 5602</div> 5603<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> is ready to be used.</p> 5604<p>Fires immediately after <code>'open'</code>.</p> 5605<h5><code>readStream.bytesRead</code><span><a class="mark" href="#fs_readstream_bytesread" id="fs_readstream_bytesread">#</a></span></h5> 5606<div class="api_metadata"> 5607<span>Added in: v6.4.0</span> 5608</div> 5609<ul> 5610<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 5611</ul> 5612<p>The number of bytes that have been read so far.</p> 5613<h5><code>readStream.path</code><span><a class="mark" href="#fs_readstream_path" id="fs_readstream_path">#</a></span></h5> 5614<div class="api_metadata"> 5615<span>Added in: v0.1.93</span> 5616</div> 5617<ul> 5618<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> 5619</ul> 5620<p>The path to the file the stream is reading from as specified in the first 5621argument to <code>fs.createReadStream()</code>. If <code>path</code> is passed as a string, then 5622<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 5623<code>readStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 5624<h5><code>readStream.pending</code><span><a class="mark" href="#fs_readstream_pending" id="fs_readstream_pending">#</a></span></h5> 5625<div class="api_metadata"> 5626<span>Added in: v11.2.0, v10.16.0</span> 5627</div> 5628<ul> 5629<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5630</ul> 5631<p>This property is <code>true</code> if the underlying file has not been opened yet, 5632i.e. before the <code>'ready'</code> event is emitted.</p> 5633<h4>Class: <code>fs.Stats</code><span><a class="mark" href="#fs_class_fs_stats" id="fs_class_fs_stats">#</a></span></h4> 5634<div class="api_metadata"> 5635<details class="changelog"><summary>History</summary> 5636<table> 5637<tbody><tr><th>Version</th><th>Changes</th></tr> 5638<tr><td>v8.1.0</td> 5639<td><p>Added times as numbers.</p></td></tr> 5640<tr><td>v0.1.21</td> 5641<td><p><span>Added in: v0.1.21</span></p></td></tr> 5642</tbody></table> 5643</details> 5644</div> 5645<p>A <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object provides information about a file.</p> 5646<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 5647their synchronous counterparts are of this type. 5648If <code>bigint</code> in the <code>options</code> passed to those methods is true, the numeric values 5649will be <code>bigint</code> instead of <code>number</code>, and the object will contain additional 5650nanosecond-precision properties suffixed with <code>Ns</code>.</p> 5651<pre><code class="language-console">Stats { 5652 dev: 2114, 5653 ino: 48064969, 5654 mode: 33188, 5655 nlink: 1, 5656 uid: 85, 5657 gid: 100, 5658 rdev: 0, 5659 size: 527, 5660 blksize: 4096, 5661 blocks: 8, 5662 atimeMs: 1318289051000.1, 5663 mtimeMs: 1318289051000.1, 5664 ctimeMs: 1318289051000.1, 5665 birthtimeMs: 1318289051000.1, 5666 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5667 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5668 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5669 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5670<p><code>bigint</code> version:</p> 5671<pre><code class="language-console">BigIntStats { 5672 dev: 2114n, 5673 ino: 48064969n, 5674 mode: 33188n, 5675 nlink: 1n, 5676 uid: 85n, 5677 gid: 100n, 5678 rdev: 0n, 5679 size: 527n, 5680 blksize: 4096n, 5681 blocks: 8n, 5682 atimeMs: 1318289051000n, 5683 mtimeMs: 1318289051000n, 5684 ctimeMs: 1318289051000n, 5685 birthtimeMs: 1318289051000n, 5686 atimeNs: 1318289051000000000n, 5687 mtimeNs: 1318289051000000000n, 5688 ctimeNs: 1318289051000000000n, 5689 birthtimeNs: 1318289051000000000n, 5690 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5691 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5692 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5693 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5694<h5><code>stats.isBlockDevice()</code><span><a class="mark" href="#fs_stats_isblockdevice" id="fs_stats_isblockdevice">#</a></span></h5> 5695<div class="api_metadata"> 5696<span>Added in: v0.1.10</span> 5697</div> 5698<ul> 5699<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5700</ul> 5701<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> 5702<h5><code>stats.isCharacterDevice()</code><span><a class="mark" href="#fs_stats_ischaracterdevice" id="fs_stats_ischaracterdevice">#</a></span></h5> 5703<div class="api_metadata"> 5704<span>Added in: v0.1.10</span> 5705</div> 5706<ul> 5707<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5708</ul> 5709<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> 5710<h5><code>stats.isDirectory()</code><span><a class="mark" href="#fs_stats_isdirectory" id="fs_stats_isdirectory">#</a></span></h5> 5711<div class="api_metadata"> 5712<span>Added in: v0.1.10</span> 5713</div> 5714<ul> 5715<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5716</ul> 5717<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> 5718<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 5719always return <code>false</code>. This is because <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a> returns information 5720about a symbolic link itself and not the path it resolves to.</p> 5721<h5><code>stats.isFIFO()</code><span><a class="mark" href="#fs_stats_isfifo" id="fs_stats_isfifo">#</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 first-in-first-out (FIFO) 5729pipe.</p> 5730<h5><code>stats.isFile()</code><span><a class="mark" href="#fs_stats_isfile" id="fs_stats_isfile">#</a></span></h5> 5731<div class="api_metadata"> 5732<span>Added in: v0.1.10</span> 5733</div> 5734<ul> 5735<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5736</ul> 5737<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> 5738<h5><code>stats.isSocket()</code><span><a class="mark" href="#fs_stats_issocket" id="fs_stats_issocket">#</a></span></h5> 5739<div class="api_metadata"> 5740<span>Added in: v0.1.10</span> 5741</div> 5742<ul> 5743<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5744</ul> 5745<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> 5746<h5><code>stats.isSymbolicLink()</code><span><a class="mark" href="#fs_stats_issymboliclink" id="fs_stats_issymboliclink">#</a></span></h5> 5747<div class="api_metadata"> 5748<span>Added in: v0.1.10</span> 5749</div> 5750<ul> 5751<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5752</ul> 5753<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> 5754<p>This method is only valid when using <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a>.</p> 5755<h5><code>stats.dev</code><span><a class="mark" href="#fs_stats_dev" id="fs_stats_dev">#</a></span></h5> 5756<ul> 5757<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> 5758</ul> 5759<p>The numeric identifier of the device containing the file.</p> 5760<h5><code>stats.ino</code><span><a class="mark" href="#fs_stats_ino" id="fs_stats_ino">#</a></span></h5> 5761<ul> 5762<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> 5763</ul> 5764<p>The file system specific "Inode" number for the file.</p> 5765<h5><code>stats.mode</code><span><a class="mark" href="#fs_stats_mode" id="fs_stats_mode">#</a></span></h5> 5766<ul> 5767<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> 5768</ul> 5769<p>A bit-field describing the file type and mode.</p> 5770<h5><code>stats.nlink</code><span><a class="mark" href="#fs_stats_nlink" id="fs_stats_nlink">#</a></span></h5> 5771<ul> 5772<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> 5773</ul> 5774<p>The number of hard-links that exist for the file.</p> 5775<h5><code>stats.uid</code><span><a class="mark" href="#fs_stats_uid" id="fs_stats_uid">#</a></span></h5> 5776<ul> 5777<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> 5778</ul> 5779<p>The numeric user identifier of the user that owns the file (POSIX).</p> 5780<h5><code>stats.gid</code><span><a class="mark" href="#fs_stats_gid" id="fs_stats_gid">#</a></span></h5> 5781<ul> 5782<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> 5783</ul> 5784<p>The numeric group identifier of the group that owns the file (POSIX).</p> 5785<h5><code>stats.rdev</code><span><a class="mark" href="#fs_stats_rdev" id="fs_stats_rdev">#</a></span></h5> 5786<ul> 5787<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> 5788</ul> 5789<p>A numeric device identifier if the file represents a device.</p> 5790<h5><code>stats.size</code><span><a class="mark" href="#fs_stats_size" id="fs_stats_size">#</a></span></h5> 5791<ul> 5792<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> 5793</ul> 5794<p>The size of the file in bytes.</p> 5795<h5><code>stats.blksize</code><span><a class="mark" href="#fs_stats_blksize" id="fs_stats_blksize">#</a></span></h5> 5796<ul> 5797<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> 5798</ul> 5799<p>The file system block size for i/o operations.</p> 5800<h5><code>stats.blocks</code><span><a class="mark" href="#fs_stats_blocks" id="fs_stats_blocks">#</a></span></h5> 5801<ul> 5802<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> 5803</ul> 5804<p>The number of blocks allocated for this file.</p> 5805<h5><code>stats.atimeMs</code><span><a class="mark" href="#fs_stats_atimems" id="fs_stats_atimems">#</a></span></h5> 5806<div class="api_metadata"> 5807<span>Added in: v8.1.0</span> 5808</div> 5809<ul> 5810<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> 5811</ul> 5812<p>The timestamp indicating the last time this file was accessed expressed in 5813milliseconds since the POSIX Epoch.</p> 5814<h5><code>stats.mtimeMs</code><span><a class="mark" href="#fs_stats_mtimems" id="fs_stats_mtimems">#</a></span></h5> 5815<div class="api_metadata"> 5816<span>Added in: v8.1.0</span> 5817</div> 5818<ul> 5819<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> 5820</ul> 5821<p>The timestamp indicating the last time this file was modified expressed in 5822milliseconds since the POSIX Epoch.</p> 5823<h5><code>stats.ctimeMs</code><span><a class="mark" href="#fs_stats_ctimems" id="fs_stats_ctimems">#</a></span></h5> 5824<div class="api_metadata"> 5825<span>Added in: v8.1.0</span> 5826</div> 5827<ul> 5828<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> 5829</ul> 5830<p>The timestamp indicating the last time the file status was changed expressed 5831in milliseconds since the POSIX Epoch.</p> 5832<h5><code>stats.birthtimeMs</code><span><a class="mark" href="#fs_stats_birthtimems" id="fs_stats_birthtimems">#</a></span></h5> 5833<div class="api_metadata"> 5834<span>Added in: v8.1.0</span> 5835</div> 5836<ul> 5837<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> 5838</ul> 5839<p>The timestamp indicating the creation time of this file expressed in 5840milliseconds since the POSIX Epoch.</p> 5841<h5><code>stats.atimeNs</code><span><a class="mark" href="#fs_stats_atimens" id="fs_stats_atimens">#</a></span></h5> 5842<div class="api_metadata"> 5843<span>Added in: v12.10.0</span> 5844</div> 5845<ul> 5846<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5847</ul> 5848<p>Only present when <code>bigint: true</code> is passed into the method that generates 5849the object. 5850The timestamp indicating the last time this file was accessed expressed in 5851nanoseconds since the POSIX Epoch.</p> 5852<h5><code>stats.mtimeNs</code><span><a class="mark" href="#fs_stats_mtimens" id="fs_stats_mtimens">#</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 modified expressed in 5862nanoseconds since the POSIX Epoch.</p> 5863<h5><code>stats.ctimeNs</code><span><a class="mark" href="#fs_stats_ctimens" id="fs_stats_ctimens">#</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 the file status was changed expressed 5873in nanoseconds since the POSIX Epoch.</p> 5874<h5><code>stats.birthtimeNs</code><span><a class="mark" href="#fs_stats_birthtimens" id="fs_stats_birthtimens">#</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 creation time of this file expressed in 5884nanoseconds since the POSIX Epoch.</p> 5885<h5><code>stats.atime</code><span><a class="mark" href="#fs_stats_atime" id="fs_stats_atime">#</a></span></h5> 5886<div class="api_metadata"> 5887<span>Added in: v0.11.13</span> 5888</div> 5889<ul> 5890<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5891</ul> 5892<p>The timestamp indicating the last time this file was accessed.</p> 5893<h5><code>stats.mtime</code><span><a class="mark" href="#fs_stats_mtime" id="fs_stats_mtime">#</a></span></h5> 5894<div class="api_metadata"> 5895<span>Added in: v0.11.13</span> 5896</div> 5897<ul> 5898<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5899</ul> 5900<p>The timestamp indicating the last time this file was modified.</p> 5901<h5><code>stats.ctime</code><span><a class="mark" href="#fs_stats_ctime" id="fs_stats_ctime">#</a></span></h5> 5902<div class="api_metadata"> 5903<span>Added in: v0.11.13</span> 5904</div> 5905<ul> 5906<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5907</ul> 5908<p>The timestamp indicating the last time the file status was changed.</p> 5909<h5><code>stats.birthtime</code><span><a class="mark" href="#fs_stats_birthtime" id="fs_stats_birthtime">#</a></span></h5> 5910<div class="api_metadata"> 5911<span>Added in: v0.11.13</span> 5912</div> 5913<ul> 5914<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5915</ul> 5916<p>The timestamp indicating the creation time of this file.</p> 5917<h5>Stat time values<span><a class="mark" href="#fs_stat_time_values" id="fs_stat_time_values">#</a></span></h5> 5918<p>The <code>atimeMs</code>, <code>mtimeMs</code>, <code>ctimeMs</code>, <code>birthtimeMs</code> properties are 5919numeric values that hold the corresponding times in milliseconds. Their 5920precision is platform specific. When <code>bigint: true</code> is passed into the 5921method that generates the object, the properties will be <a href="https://tc39.github.io/proposal-bigint">bigints</a>, 5922otherwise they will be <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type">numbers</a>.</p> 5923<p>The <code>atimeNs</code>, <code>mtimeNs</code>, <code>ctimeNs</code>, <code>birthtimeNs</code> properties are 5924<a href="https://tc39.github.io/proposal-bigint">bigints</a> that hold the corresponding times in nanoseconds. They are 5925only present when <code>bigint: true</code> is passed into the method that generates 5926the object. Their precision is platform specific.</p> 5927<p><code>atime</code>, <code>mtime</code>, <code>ctime</code>, and <code>birthtime</code> are 5928<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 5929<code>Date</code> and number values are not connected. Assigning a new number value, or 5930mutating the <code>Date</code> value, will not be reflected in the corresponding alternate 5931representation.</p> 5932<p>The times in the stat object have the following semantics:</p> 5933<ul> 5934<li><code>atime</code> "Access Time": Time when file data last accessed. Changed 5935by 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> 5936<li><code>mtime</code> "Modified Time": Time when file data last modified. 5937Changed 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> 5938<li><code>ctime</code> "Change Time": Time when file status was last changed 5939(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>, 5940<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>, 5941<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> 5942<li><code>birthtime</code> "Birth Time": Time of file creation. Set once when the 5943file is created. On filesystems where birthtime is not available, 5944this field may instead hold either the <code>ctime</code> or 5945<code>1970-01-01T00:00Z</code> (ie, Unix epoch timestamp <code>0</code>). This value may be greater 5946than <code>atime</code> or <code>mtime</code> in this case. On Darwin and other FreeBSD variants, 5947also set if the <code>atime</code> is explicitly set to an earlier value than the current 5948<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> 5949</ul> 5950<p>Prior to Node.js 0.12, the <code>ctime</code> held the <code>birthtime</code> on Windows systems. As 5951of 0.12, <code>ctime</code> is not "creation time", and on Unix systems, it never was.</p> 5952<h4>Class: <code>fs.WriteStream</code><span><a class="mark" href="#fs_class_fs_writestream" id="fs_class_fs_writestream">#</a></span></h4> 5953<div class="api_metadata"> 5954<span>Added in: v0.1.93</span> 5955</div> 5956<ul> 5957<li>Extends <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li> 5958</ul> 5959<p>Instances of <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> are created and returned using the 5960<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> function.</p> 5961<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_2" id="fs_event_close_2">#</a></span></h5> 5962<div class="api_metadata"> 5963<span>Added in: v0.1.93</span> 5964</div> 5965<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> 5966<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open_1" id="fs_event_open_1">#</a></span></h5> 5967<div class="api_metadata"> 5968<span>Added in: v0.1.93</span> 5969</div> 5970<ul> 5971<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> 5972</ul> 5973<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a>'s file is opened.</p> 5974<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready_1" id="fs_event_ready_1">#</a></span></h5> 5975<div class="api_metadata"> 5976<span>Added in: v9.11.0</span> 5977</div> 5978<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> is ready to be used.</p> 5979<p>Fires immediately after <code>'open'</code>.</p> 5980<h5><code>writeStream.bytesWritten</code><span><a class="mark" href="#fs_writestream_byteswritten" id="fs_writestream_byteswritten">#</a></span></h5> 5981<div class="api_metadata"> 5982<span>Added in: v0.4.7</span> 5983</div> 5984<p>The number of bytes written so far. Does not include data that is still queued 5985for writing.</p> 5986<h5><code>writeStream.close([callback])</code><span><a class="mark" href="#fs_writestream_close_callback" id="fs_writestream_close_callback">#</a></span></h5> 5987<div class="api_metadata"> 5988<span>Added in: v0.9.4</span> 5989</div> 5990<ul> 5991<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5992<ul> 5993<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5994</ul> 5995</li> 5996</ul> 5997<p>Closes <code>writeStream</code>. Optionally accepts a 5998callback that will be executed once the <code>writeStream</code> 5999is closed.</p> 6000<h5><code>writeStream.path</code><span><a class="mark" href="#fs_writestream_path" id="fs_writestream_path">#</a></span></h5> 6001<div class="api_metadata"> 6002<span>Added in: v0.1.93</span> 6003</div> 6004<p>The path to the file the stream is writing to as specified in the first 6005argument to <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>. If <code>path</code> is passed as a string, then 6006<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 6007<code>writeStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 6008<h5><code>writeStream.pending</code><span><a class="mark" href="#fs_writestream_pending" id="fs_writestream_pending">#</a></span></h5> 6009<div class="api_metadata"> 6010<span>Added in: v11.2.0</span> 6011</div> 6012<ul> 6013<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 6014</ul> 6015<p>This property is <code>true</code> if the underlying file has not been opened yet, 6016i.e. before the <code>'ready'</code> event is emitted.</p> 6017<h4><code>fs.constants</code><span><a class="mark" href="#fs_fs_constants" id="fs_fs_constants">#</a></span></h4> 6018<ul> 6019<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 6020</ul> 6021<p>Returns an object containing commonly used constants for file system 6022operations.</p> 6023<h5>FS constants<span><a class="mark" href="#fs_fs_constants_1" id="fs_fs_constants_1">#</a></span></h5> 6024<p>The following constants are exported by <code>fs.constants</code>.</p> 6025<p>Not every constant will be available on every operating system.</p> 6026<p>To use more than one constant, use the bitwise OR <code>|</code> operator.</p> 6027<p>Example:</p> 6028<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>; 6029 6030<span class="hljs-keyword">const</span> { 6031 <span class="hljs-variable constant_">O_RDWR</span>, 6032 <span class="hljs-variable constant_">O_CREAT</span>, 6033 <span class="hljs-variable constant_">O_EXCL</span> 6034} = constants; 6035 6036<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> { 6037 <span class="hljs-comment">// ...</span> 6038});</code></pre> 6039<h6>File access constants<span><a class="mark" href="#fs_file_access_constants" id="fs_file_access_constants">#</a></span></h6> 6040<p>The following constants are meant for use with <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a>.</p> 6041<table> 6042 <tbody><tr> 6043 <th>Constant</th> 6044 <th>Description</th> 6045 </tr> 6046 <tr> 6047 <td><code>F_OK</code></td> 6048 <td>Flag indicating that the file is visible to the calling process. 6049 This is useful for determining if a file exists, but says nothing 6050 about <code>rwx</code> permissions. Default if no mode is specified.</td> 6051 </tr> 6052 <tr> 6053 <td><code>R_OK</code></td> 6054 <td>Flag indicating that the file can be read by the calling process.</td> 6055 </tr> 6056 <tr> 6057 <td><code>W_OK</code></td> 6058 <td>Flag indicating that the file can be written by the calling 6059 process.</td> 6060 </tr> 6061 <tr> 6062 <td><code>X_OK</code></td> 6063 <td>Flag indicating that the file can be executed by the calling 6064 process. This has no effect on Windows 6065 (will behave like <code>fs.constants.F_OK</code>).</td> 6066 </tr> 6067</tbody></table> 6068<h6>File copy constants<span><a class="mark" href="#fs_file_copy_constants" id="fs_file_copy_constants">#</a></span></h6> 6069<p>The following constants are meant for use with <a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile()</code></a>.</p> 6070<table> 6071 <tbody><tr> 6072 <th>Constant</th> 6073 <th>Description</th> 6074 </tr> 6075 <tr> 6076 <td><code>COPYFILE_EXCL</code></td> 6077 <td>If present, the copy operation will fail with an error if the 6078 destination path already exists.</td> 6079 </tr> 6080 <tr> 6081 <td><code>COPYFILE_FICLONE</code></td> 6082 <td>If present, the copy operation will attempt to create a 6083 copy-on-write reflink. If the underlying platform does not support 6084 copy-on-write, then a fallback copy mechanism is used.</td> 6085 </tr> 6086 <tr> 6087 <td><code>COPYFILE_FICLONE_FORCE</code></td> 6088 <td>If present, the copy operation will attempt to create a 6089 copy-on-write reflink. If the underlying platform does not support 6090 copy-on-write, then the operation will fail with an error.</td> 6091 </tr> 6092</tbody></table> 6093<h6>File open constants<span><a class="mark" href="#fs_file_open_constants" id="fs_file_open_constants">#</a></span></h6> 6094<p>The following constants are meant for use with <code>fs.open()</code>.</p> 6095<table> 6096 <tbody><tr> 6097 <th>Constant</th> 6098 <th>Description</th> 6099 </tr> 6100 <tr> 6101 <td><code>O_RDONLY</code></td> 6102 <td>Flag indicating to open a file for read-only access.</td> 6103 </tr> 6104 <tr> 6105 <td><code>O_WRONLY</code></td> 6106 <td>Flag indicating to open a file for write-only access.</td> 6107 </tr> 6108 <tr> 6109 <td><code>O_RDWR</code></td> 6110 <td>Flag indicating to open a file for read-write access.</td> 6111 </tr> 6112 <tr> 6113 <td><code>O_CREAT</code></td> 6114 <td>Flag indicating to create the file if it does not already exist.</td> 6115 </tr> 6116 <tr> 6117 <td><code>O_EXCL</code></td> 6118 <td>Flag indicating that opening a file should fail if the 6119 <code>O_CREAT</code> flag is set and the file already exists.</td> 6120 </tr> 6121 <tr> 6122 <td><code>O_NOCTTY</code></td> 6123 <td>Flag indicating that if path identifies a terminal device, opening the 6124 path shall not cause that terminal to become the controlling terminal for 6125 the process (if the process does not already have one).</td> 6126 </tr> 6127 <tr> 6128 <td><code>O_TRUNC</code></td> 6129 <td>Flag indicating that if the file exists and is a regular file, and the 6130 file is opened successfully for write access, its length shall be truncated 6131 to zero.</td> 6132 </tr> 6133 <tr> 6134 <td><code>O_APPEND</code></td> 6135 <td>Flag indicating that data will be appended to the end of the file.</td> 6136 </tr> 6137 <tr> 6138 <td><code>O_DIRECTORY</code></td> 6139 <td>Flag indicating that the open should fail if the path is not a 6140 directory.</td> 6141 </tr> 6142 <tr> 6143 <td><code>O_NOATIME</code></td> 6144 <td>Flag indicating reading accesses to the file system will no longer 6145 result in an update to the <code>atime</code> information associated with 6146 the file. This flag is available on Linux operating systems only.</td> 6147 </tr> 6148 <tr> 6149 <td><code>O_NOFOLLOW</code></td> 6150 <td>Flag indicating that the open should fail if the path is a symbolic 6151 link.</td> 6152 </tr> 6153 <tr> 6154 <td><code>O_SYNC</code></td> 6155 <td>Flag indicating that the file is opened for synchronized I/O with write 6156 operations waiting for file integrity.</td> 6157 </tr> 6158 <tr> 6159 <td><code>O_DSYNC</code></td> 6160 <td>Flag indicating that the file is opened for synchronized I/O with write 6161 operations waiting for data integrity.</td> 6162 </tr> 6163 <tr> 6164 <td><code>O_SYMLINK</code></td> 6165 <td>Flag indicating to open the symbolic link itself rather than the 6166 resource it is pointing to.</td> 6167 </tr> 6168 <tr> 6169 <td><code>O_DIRECT</code></td> 6170 <td>When set, an attempt will be made to minimize caching effects of file 6171 I/O.</td> 6172 </tr> 6173 <tr> 6174 <td><code>O_NONBLOCK</code></td> 6175 <td>Flag indicating to open the file in nonblocking mode when possible.</td> 6176 </tr> 6177 <tr> 6178 <td><code>UV_FS_O_FILEMAP</code></td> 6179 <td>When set, a memory file mapping is used to access the file. This flag 6180 is available on Windows operating systems only. On other operating systems, 6181 this flag is ignored.</td> 6182 </tr> 6183</tbody></table> 6184<h6>File type constants<span><a class="mark" href="#fs_file_type_constants" id="fs_file_type_constants">#</a></span></h6> 6185<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 6186<code>mode</code> property for determining a file's type.</p> 6187<table> 6188 <tbody><tr> 6189 <th>Constant</th> 6190 <th>Description</th> 6191 </tr> 6192 <tr> 6193 <td><code>S_IFMT</code></td> 6194 <td>Bit mask used to extract the file type code.</td> 6195 </tr> 6196 <tr> 6197 <td><code>S_IFREG</code></td> 6198 <td>File type constant for a regular file.</td> 6199 </tr> 6200 <tr> 6201 <td><code>S_IFDIR</code></td> 6202 <td>File type constant for a directory.</td> 6203 </tr> 6204 <tr> 6205 <td><code>S_IFCHR</code></td> 6206 <td>File type constant for a character-oriented device file.</td> 6207 </tr> 6208 <tr> 6209 <td><code>S_IFBLK</code></td> 6210 <td>File type constant for a block-oriented device file.</td> 6211 </tr> 6212 <tr> 6213 <td><code>S_IFIFO</code></td> 6214 <td>File type constant for a FIFO/pipe.</td> 6215 </tr> 6216 <tr> 6217 <td><code>S_IFLNK</code></td> 6218 <td>File type constant for a symbolic link.</td> 6219 </tr> 6220 <tr> 6221 <td><code>S_IFSOCK</code></td> 6222 <td>File type constant for a socket.</td> 6223 </tr> 6224</tbody></table> 6225<h6>File mode constants<span><a class="mark" href="#fs_file_mode_constants" id="fs_file_mode_constants">#</a></span></h6> 6226<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 6227<code>mode</code> property for determining the access permissions for a file.</p> 6228<table> 6229 <tbody><tr> 6230 <th>Constant</th> 6231 <th>Description</th> 6232 </tr> 6233 <tr> 6234 <td><code>S_IRWXU</code></td> 6235 <td>File mode indicating readable, writable, and executable by owner.</td> 6236 </tr> 6237 <tr> 6238 <td><code>S_IRUSR</code></td> 6239 <td>File mode indicating readable by owner.</td> 6240 </tr> 6241 <tr> 6242 <td><code>S_IWUSR</code></td> 6243 <td>File mode indicating writable by owner.</td> 6244 </tr> 6245 <tr> 6246 <td><code>S_IXUSR</code></td> 6247 <td>File mode indicating executable by owner.</td> 6248 </tr> 6249 <tr> 6250 <td><code>S_IRWXG</code></td> 6251 <td>File mode indicating readable, writable, and executable by group.</td> 6252 </tr> 6253 <tr> 6254 <td><code>S_IRGRP</code></td> 6255 <td>File mode indicating readable by group.</td> 6256 </tr> 6257 <tr> 6258 <td><code>S_IWGRP</code></td> 6259 <td>File mode indicating writable by group.</td> 6260 </tr> 6261 <tr> 6262 <td><code>S_IXGRP</code></td> 6263 <td>File mode indicating executable by group.</td> 6264 </tr> 6265 <tr> 6266 <td><code>S_IRWXO</code></td> 6267 <td>File mode indicating readable, writable, and executable by others.</td> 6268 </tr> 6269 <tr> 6270 <td><code>S_IROTH</code></td> 6271 <td>File mode indicating readable by others.</td> 6272 </tr> 6273 <tr> 6274 <td><code>S_IWOTH</code></td> 6275 <td>File mode indicating writable by others.</td> 6276 </tr> 6277 <tr> 6278 <td><code>S_IXOTH</code></td> 6279 <td>File mode indicating executable by others.</td> 6280 </tr> 6281</tbody></table> 6282</section><section><h3>Notes<span><a class="mark" href="#fs_notes" id="fs_notes">#</a></span></h3> 6283<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> 6284<p>Because they are executed asynchronously by the underlying thread pool, 6285there is no guaranteed ordering when using either the callback or 6286promise-based methods.</p> 6287<p>For example, the following is prone to error because the <code>fs.stat()</code> 6288operation might complete before the <code>fs.rename()</code> operation:</p> 6289<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> { 6290 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6291 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'renamed complete'</span>); 6292}); 6293fs.<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> { 6294 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6295 <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>); 6296});</code></pre> 6297<p>It is important to correctly order the operations by awaiting the results 6298of one before invoking the other:</p> 6299 6300<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>; 6301 6302<span class="hljs-keyword">const</span> <span class="hljs-keyword">from</span> = <span class="hljs-string">'/tmp/hello'</span>; 6303<span class="hljs-keyword">const</span> to = <span class="hljs-string">'/tmp/world'</span>; 6304 6305<span class="hljs-keyword">try</span> { 6306 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6307 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6308 <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>); 6309} <span class="hljs-keyword">catch</span> (error) { 6310 <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>); 6311}</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>); 6312 6313(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params"><span class="hljs-keyword">from</span>, to</span>) { 6314 <span class="hljs-keyword">try</span> { 6315 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6316 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6317 <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>); 6318 } <span class="hljs-keyword">catch</span> (error) { 6319 <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>); 6320 } 6321})(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>);</code></pre> 6322<p>Or, when using the callback APIs, move the <code>fs.stat()</code> call into the callback 6323of the <code>fs.rename()</code> operation:</p> 6324 6325<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>; 6326 6327<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> { 6328 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6329 <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> { 6330 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6331 <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>); 6332 }); 6333});</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>); 6334 6335<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> { 6336 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6337 <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> { 6338 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6339 <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>); 6340 }); 6341});</code></pre> 6342<h4>File paths<span><a class="mark" href="#fs_file_paths" id="fs_file_paths">#</a></span></h4> 6343<p>Most <code>fs</code> operations accept file paths that may be specified in the form of 6344a 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> 6345<h5>String paths<span><a class="mark" href="#fs_string_paths" id="fs_string_paths">#</a></span></h5> 6346<p>String form paths are interpreted as UTF-8 character sequences identifying 6347the absolute or relative filename. Relative paths will be resolved relative 6348to the current working directory as determined by calling <code>process.cwd()</code>.</p> 6349<p>Example using an absolute path on POSIX:</p> 6350<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>; 6351 6352<span class="hljs-keyword">let</span> fd; 6353<span class="hljs-keyword">try</span> { 6354 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>); 6355 <span class="hljs-comment">// Do something with the file</span> 6356} <span class="hljs-keyword">finally</span> { 6357 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6358}</code></pre> 6359<p>Example using a relative path on POSIX (relative to <code>process.cwd()</code>):</p> 6360<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>; 6361 6362<span class="hljs-keyword">let</span> fd; 6363<span class="hljs-keyword">try</span> { 6364 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>); 6365 <span class="hljs-comment">// Do something with the file</span> 6366} <span class="hljs-keyword">finally</span> { 6367 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6368}</code></pre> 6369<h5>File URL paths<span><a class="mark" href="#fs_file_url_paths" id="fs_file_url_paths">#</a></span></h5> 6370<div class="api_metadata"> 6371<span>Added in: v7.6.0</span> 6372</div> 6373<p>For most <code>fs</code> module functions, the <code>path</code> or <code>filename</code> argument may be passed 6374as a <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> object using the <code>file:</code> protocol.</p> 6375<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>; 6376 6377<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> 6378<p><code>file:</code> URLs are always absolute paths.</p> 6379<h6>Platform-specific considerations<span><a class="mark" href="#fs_platform_specific_considerations" id="fs_platform_specific_considerations">#</a></span></h6> 6380<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> 6381<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 6382without a host name nor a drive letter will result in an error:</p> 6383<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>; 6384<span class="hljs-comment">// On Windows :</span> 6385 6386<span class="hljs-comment">// - WHATWG file URLs with hostname convert to UNC path</span> 6387<span class="hljs-comment">// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file</span> 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://hostname/p/a/t/h/file'</span>)); 6389 6390<span class="hljs-comment">// - WHATWG file URLs with drive letters convert to absolute path</span> 6391<span class="hljs-comment">// file:///C:/tmp/hello => C:\tmp\hello</span> 6392<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>)); 6393 6394<span class="hljs-comment">// - WHATWG file URLs without hostname must have a drive letters</span> 6395<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>)); 6396<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>)); 6397<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute</span></code></pre> 6398<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 6399the drive letter. Using another separator will result in an error.</p> 6400<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 6401will result in an error:</p> 6402<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>; 6403<span class="hljs-comment">// On other platforms:</span> 6404 6405<span class="hljs-comment">// - WHATWG file URLs with hostname are unsupported</span> 6406<span class="hljs-comment">// file://hostname/p/a/t/h/file => throw!</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://hostname/p/a/t/h/file'</span>)); 6408<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute</span> 6409 6410<span class="hljs-comment">// - WHATWG file URLs convert to absolute path</span> 6411<span class="hljs-comment">// file:///tmp/hello => /tmp/hello</span> 6412<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> 6413<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 6414platforms:</p> 6415<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>; 6416 6417<span class="hljs-comment">// On Windows</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:///C:/p/a/t/h/%2F'</span>)); 6419<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>)); 6420<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6421\ or / characters */</span> 6422 6423<span class="hljs-comment">// On POSIX</span> 6424<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>)); 6425<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>)); 6426<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6427/ characters */</span></code></pre> 6428<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> 6429<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>; 6430 6431<span class="hljs-comment">// On Windows</span> 6432<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>)); 6433<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>)); 6434<span class="hljs-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6435\ or / characters */</span></code></pre> 6436<h5>Buffer paths<span><a class="mark" href="#fs_buffer_paths" id="fs_buffer_paths">#</a></span></h5> 6437<p>Paths specified using a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> are useful primarily on certain POSIX 6438operating systems that treat file paths as opaque byte sequences. On such 6439systems, it is possible for a single file path to contain sub-sequences that 6440use multiple character encodings. As with string paths, <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> paths may 6441be relative or absolute:</p> 6442<p>Example using an absolute path on POSIX:</p> 6443<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>; 6444 6445<span class="hljs-keyword">let</span> fd; 6446<span class="hljs-keyword">try</span> { 6447 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>); 6448 <span class="hljs-comment">// Do something with the file</span> 6449} <span class="hljs-keyword">finally</span> { 6450 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6451}</code></pre> 6452<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> 6453<p>On Windows, Node.js follows the concept of per-drive working directory. This 6454behavior can be observed when using a drive path without a backslash. For 6455example <code>fs.readdirSync('C:\\')</code> can potentially return a different result than 6456<code>fs.readdirSync('C:')</code>. For more information, see 6457<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths">this MSDN page</a>.</p> 6458<h4>File descriptors<span><a class="mark" href="#fs_file_descriptors_1" id="fs_file_descriptors_1">#</a></span></h4> 6459<p>On POSIX systems, for every process, the kernel maintains a table of currently 6460open files and resources. Each open file is assigned a simple numeric 6461identifier called a <em>file descriptor</em>. At the system-level, all file system 6462operations use these file descriptors to identify and track each specific 6463file. Windows systems use a different but conceptually similar mechanism for 6464tracking resources. To simplify things for users, Node.js abstracts away the 6465differences between operating systems and assigns all open files a numeric file 6466descriptor.</p> 6467<p>The callback-based <code>fs.open()</code>, and synchronous <code>fs.openSync()</code> methods open a 6468file and allocate a new file descriptor. Once allocated, the file descriptor may 6469be used to read data from, write data to, or request information about the file.</p> 6470<p>Operating systems limit the number of file descriptors that may be open 6471at any given time so it is critical to close the descriptor when operations 6472are completed. Failure to do so will result in a memory leak that will 6473eventually cause an application to crash.</p> 6474<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>; 6475 6476<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 6477 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 6478 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6479 }); 6480} 6481 6482<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> { 6483 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6484 <span class="hljs-keyword">try</span> { 6485 <span class="hljs-title function_">fstat</span>(fd, <span class="hljs-function">(<span class="hljs-params">err, stat</span>) =></span> { 6486 <span class="hljs-keyword">if</span> (err) { 6487 <span class="hljs-title function_">closeFd</span>(fd); 6488 <span class="hljs-keyword">throw</span> err; 6489 } 6490 6491 <span class="hljs-comment">// use stat</span> 6492 6493 <span class="hljs-title function_">closeFd</span>(fd); 6494 }); 6495 } <span class="hljs-keyword">catch</span> (err) { 6496 <span class="hljs-title function_">closeFd</span>(fd); 6497 <span class="hljs-keyword">throw</span> err; 6498 } 6499});</code></pre> 6500<p>The promise-based APIs use a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object in place of the numeric 6501file descriptor. These objects are better managed by the system to ensure 6502that resources are not leaked. However, it is still required that they are 6503closed when operations are completed:</p> 6504<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>; 6505 6506<span class="hljs-keyword">let</span> file; 6507<span class="hljs-keyword">try</span> { 6508 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>); 6509 <span class="hljs-keyword">const</span> stat = <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">stat</span>(); 6510 <span class="hljs-comment">// use stat</span> 6511} <span class="hljs-keyword">finally</span> { 6512 <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">close</span>(); 6513}</code></pre> 6514<h4>Threadpool usage<span><a class="mark" href="#fs_threadpool_usage" id="fs_threadpool_usage">#</a></span></h4> 6515<p>All callback and promise-based file system APIs ( with the exception of 6516<code>fs.FSWatcher()</code>) use libuv's threadpool. This can have surprising and negative 6517performance implications for some applications. See the 6518<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p> 6519<h4>File system flags<span><a class="mark" href="#fs_file_system_flags" id="fs_file_system_flags">#</a></span></h4> 6520<p>The following flags are available wherever the <code>flag</code> option takes a 6521string.</p> 6522<ul> 6523<li> 6524<p><code>'a'</code>: Open file for appending. 6525The file is created if it does not exist.</p> 6526</li> 6527<li> 6528<p><code>'ax'</code>: Like <code>'a'</code> but fails if the path exists.</p> 6529</li> 6530<li> 6531<p><code>'a+'</code>: Open file for reading and appending. 6532The file is created if it does not exist.</p> 6533</li> 6534<li> 6535<p><code>'ax+'</code>: Like <code>'a+'</code> but fails if the path exists.</p> 6536</li> 6537<li> 6538<p><code>'as'</code>: Open file for appending in synchronous mode. 6539The file is created if it does not exist.</p> 6540</li> 6541<li> 6542<p><code>'as+'</code>: Open file for reading and appending in synchronous mode. 6543The file is created if it does not exist.</p> 6544</li> 6545<li> 6546<p><code>'r'</code>: Open file for reading. 6547An exception occurs if the file does not exist.</p> 6548</li> 6549<li> 6550<p><code>'r+'</code>: Open file for reading and writing. 6551An exception occurs if the file does not exist.</p> 6552</li> 6553<li> 6554<p><code>'rs+'</code>: Open file for reading and writing in synchronous mode. Instructs 6555the operating system to bypass the local file system cache.</p> 6556<p>This is primarily useful for opening files on NFS mounts as it allows 6557skipping the potentially stale local cache. It has a very real impact on 6558I/O performance so using this flag is not recommended unless it is needed.</p> 6559<p>This doesn't turn <code>fs.open()</code> or <code>fsPromises.open()</code> into a synchronous 6560blocking call. If synchronous operation is desired, something like 6561<code>fs.openSync()</code> should be used.</p> 6562</li> 6563<li> 6564<p><code>'w'</code>: Open file for writing. 6565The file is created (if it does not exist) or truncated (if it exists).</p> 6566</li> 6567<li> 6568<p><code>'wx'</code>: Like <code>'w'</code> but fails if the path exists.</p> 6569</li> 6570<li> 6571<p><code>'w+'</code>: Open file for reading and writing. 6572The file is created (if it does not exist) or truncated (if it exists).</p> 6573</li> 6574<li> 6575<p><code>'wx+'</code>: Like <code>'w+'</code> but fails if the path exists.</p> 6576</li> 6577</ul> 6578<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 6579are available from <code>fs.constants</code>. On Windows, flags are translated to 6580their equivalent ones where applicable, e.g. <code>O_WRONLY</code> to <code>FILE_GENERIC_WRITE</code>, 6581or <code>O_EXCL|O_CREAT</code> to <code>CREATE_NEW</code>, as accepted by <code>CreateFileW</code>.</p> 6582<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 6583return an error if the path already exists. On POSIX, if the path is a symbolic 6584link, using <code>O_EXCL</code> returns an error even if the link is to a path that does 6585not exist. The exclusive flag might not work with network file systems.</p> 6586<p>On Linux, positional writes don't work when the file is opened in append mode. 6587The kernel ignores the position argument and always appends the data to 6588the end of the file.</p> 6589<p>Modifying a file rather than replacing it may require the <code>flag</code> option to be 6590set to <code>'r+'</code> rather than the default <code>'w'</code>.</p> 6591<p>The behavior of some flags are platform-specific. As such, opening a directory 6592on macOS and Linux with the <code>'a+'</code> flag, as in the example below, will return an 6593error. In contrast, on Windows and FreeBSD, a file descriptor or a <code>FileHandle</code> 6594will be returned.</p> 6595<pre><code class="language-js"><span class="hljs-comment">// macOS and Linux</span> 6596fs.<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> { 6597 <span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, open <directory>]</span> 6598}); 6599 6600<span class="hljs-comment">// Windows and FreeBSD</span> 6601fs.<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> { 6602 <span class="hljs-comment">// => null, <fd></span> 6603});</code></pre> 6604<p>On Windows, opening an existing hidden file using the <code>'w'</code> flag (either 6605through <code>fs.open()</code> or <code>fs.writeFile()</code> or <code>fsPromises.open()</code>) will fail with 6606<code>EPERM</code>. Existing hidden files can be opened for writing with the <code>'r+'</code> flag.</p> 6607<p>A call to <code>fs.ftruncate()</code> or <code>filehandle.truncate()</code> can be used to reset 6608the file contents.</p></section> 6609 <!-- API END --> 6610 </div> 6611 </div> 6612 </div> 6613 <script> 6614 'use strict'; 6615 { 6616 const kCustomPreference = 'customDarkTheme'; 6617 const userSettings = sessionStorage.getItem(kCustomPreference); 6618 const themeToggleButton = document.getElementById('theme-toggle-btn'); 6619 if (userSettings === null && window.matchMedia) { 6620 const mq = window.matchMedia('(prefers-color-scheme: dark)'); 6621 if ('onchange' in mq) { 6622 function mqChangeListener(e) { 6623 document.body.classList.toggle('dark-mode', e.matches); 6624 } 6625 mq.addEventListener('change', mqChangeListener); 6626 if (themeToggleButton) { 6627 themeToggleButton.addEventListener('click', function() { 6628 mq.removeEventListener('change', mqChangeListener); 6629 }, { once: true }); 6630 } 6631 } 6632 if (mq.matches) { 6633 document.body.classList.add('dark-mode'); 6634 } 6635 } else if (userSettings === 'true') { 6636 document.body.classList.add('dark-mode'); 6637 } 6638 if (themeToggleButton) { 6639 themeToggleButton.hidden = false; 6640 themeToggleButton.addEventListener('click', function() { 6641 sessionStorage.setItem( 6642 kCustomPreference, 6643 document.body.classList.toggle('dark-mode') 6644 ); 6645 }); 6646 } 6647 } 6648 </script> 6649</body> 6650</html> 6651