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.20.1"> 7 <title>File system | Node.js v14.20.1 Documentation</title> 8 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 9 <link rel="stylesheet" href="assets/style.css"> 10 <link rel="stylesheet" href="assets/hljs.css"> 11 <link rel="canonical" href="https://nodejs.org/api/fs.html"> 12</head> 13<body class="alt apidoc" id="api-section-fs"> 14 <div id="content" class="clearfix"> 15 <div id="column2" class="interior"> 16 <div id="intro" class="interior"> 17 <a href="/" title="Go back to the home page"> 18 Node.js 19 </a> 20 </div> 21 <ul> 22<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 23<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 24</ul> 25<hr class="line"> 26<ul> 27<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 28<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 29<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 30<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 31<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 32<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 33<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 34<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 35<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 36<li><a href="console.html" class="nav-console">Console</a></li> 37<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 38<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 39<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 40<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 41<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 42<li><a href="dns.html" class="nav-dns">DNS</a></li> 43<li><a href="domain.html" class="nav-domain">Domain</a></li> 44<li><a href="errors.html" class="nav-errors">Errors</a></li> 45<li><a href="events.html" class="nav-events">Events</a></li> 46<li><a href="fs.html" class="nav-fs active">File system</a></li> 47<li><a href="globals.html" class="nav-globals">Globals</a></li> 48<li><a href="http.html" class="nav-http">HTTP</a></li> 49<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 50<li><a href="https.html" class="nav-https">HTTPS</a></li> 51<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 52<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 53<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 54<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 55<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li> 56<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 57<li><a href="net.html" class="nav-net">Net</a></li> 58<li><a href="os.html" class="nav-os">OS</a></li> 59<li><a href="path.html" class="nav-path">Path</a></li> 60<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 61<li><a href="policy.html" class="nav-policy">Policies</a></li> 62<li><a href="process.html" class="nav-process">Process</a></li> 63<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 64<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 65<li><a href="readline.html" class="nav-readline">Readline</a></li> 66<li><a href="repl.html" class="nav-repl">REPL</a></li> 67<li><a href="report.html" class="nav-report">Report</a></li> 68<li><a href="stream.html" class="nav-stream">Stream</a></li> 69<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 70<li><a href="timers.html" class="nav-timers">Timers</a></li> 71<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 72<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 73<li><a href="tty.html" class="nav-tty">TTY</a></li> 74<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 75<li><a href="url.html" class="nav-url">URL</a></li> 76<li><a href="util.html" class="nav-util">Utilities</a></li> 77<li><a href="v8.html" class="nav-v8">V8</a></li> 78<li><a href="vm.html" class="nav-vm">VM</a></li> 79<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 80<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 81<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 82</ul> 83<hr class="line"> 84<ul> 85<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 86</ul> 87 </div> 88 89 <div id="column1" data-id="fs" class="interior"> 90 <header> 91 <div class="header-container"> 92 <h1>Node.js v14.20.1 documentation</h1> 93 <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 94 <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 95 <path fill="none" d="M0 0h24v24H0z" /> 96 <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 97 <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 98 </svg> 99 <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 100 <path d="M0 0h24v24H0z" fill="none" /> 101 <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 102 </svg> 103 </button> 104 </div> 105 <div id="gtoc"> 106 <ul> 107 <li> 108 <a href="index.html">Index</a> 109 </li> 110 <li> 111 <a href="all.html">View on single page</a> 112 </li> 113 <li> 114 <a href="fs.json">View as JSON</a> 115 </li> 116 117 <li class="version-picker"> 118 <a href="#">View another version <span>▼</span></a> 119 <ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v18.x/api/fs.html">18.x</a></li> 120<li><a href="https://nodejs.org/docs/latest-v17.x/api/fs.html">17.x</a></li> 121<li><a href="https://nodejs.org/docs/latest-v16.x/api/fs.html">16.x <b>LTS</b></a></li> 122<li><a href="https://nodejs.org/docs/latest-v15.x/api/fs.html">15.x</a></li> 123<li><a href="https://nodejs.org/docs/latest-v14.x/api/fs.html">14.x <b>LTS</b></a></li> 124<li><a href="https://nodejs.org/docs/latest-v13.x/api/fs.html">13.x</a></li> 125<li><a href="https://nodejs.org/docs/latest-v12.x/api/fs.html">12.x <b>LTS</b></a></li> 126<li><a href="https://nodejs.org/docs/latest-v11.x/api/fs.html">11.x</a></li> 127<li><a href="https://nodejs.org/docs/latest-v10.x/api/fs.html">10.x</a></li> 128<li><a href="https://nodejs.org/docs/latest-v9.x/api/fs.html">9.x</a></li> 129<li><a href="https://nodejs.org/docs/latest-v8.x/api/fs.html">8.x</a></li> 130<li><a href="https://nodejs.org/docs/latest-v7.x/api/fs.html">7.x</a></li> 131<li><a href="https://nodejs.org/docs/latest-v6.x/api/fs.html">6.x</a></li> 132<li><a href="https://nodejs.org/docs/latest-v5.x/api/fs.html">5.x</a></li> 133<li><a href="https://nodejs.org/docs/latest-v4.x/api/fs.html">4.x</a></li> 134<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/fs.html">0.12.x</a></li> 135<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/fs.html">0.10.x</a></li></ol> 136 </li> 137 138 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/fs.md">Edit on GitHub</a></li> 139 </ul> 140 </div> 141 <hr> 142 </header> 143 144 <details id="toc" open><summary>Table of contents</summary><ul> 145<li><span class="stability_2"><a href="#fs_file_system">File system</a></span> 146<ul> 147<li><a href="#fs_promise_example">Promise example</a></li> 148<li><a href="#fs_callback_example">Callback example</a></li> 149<li><a href="#fs_synchronous_example">Synchronous example</a></li> 150<li><a href="#fs_promises_api">Promises API</a> 151<ul> 152<li><a href="#fs_class_filehandle">Class: <code>FileHandle</code></a> 153<ul> 154<li><a href="#fs_filehandle_appendfile_data_options"><code>filehandle.appendFile(data[, options])</code></a></li> 155<li><a href="#fs_filehandle_chmod_mode"><code>filehandle.chmod(mode)</code></a></li> 156<li><a href="#fs_filehandle_chown_uid_gid"><code>filehandle.chown(uid, gid)</code></a></li> 157<li><a href="#fs_filehandle_close"><code>filehandle.close()</code></a></li> 158<li><a href="#fs_filehandle_datasync"><code>filehandle.datasync()</code></a></li> 159<li><a href="#fs_filehandle_fd"><code>filehandle.fd</code></a></li> 160<li><a href="#fs_filehandle_read_buffer_offset_length_position"><code>filehandle.read(buffer, offset, length, position)</code></a></li> 161<li><a href="#fs_filehandle_read_options"><code>filehandle.read([options])</code></a></li> 162<li><a href="#fs_filehandle_readfile_options"><code>filehandle.readFile(options)</code></a></li> 163<li><a href="#fs_filehandle_readv_buffers_position"><code>filehandle.readv(buffers[, position])</code></a></li> 164<li><a href="#fs_filehandle_stat_options"><code>filehandle.stat([options])</code></a></li> 165<li><a href="#fs_filehandle_sync"><code>filehandle.sync()</code></a></li> 166<li><a href="#fs_filehandle_truncate_len"><code>filehandle.truncate(len)</code></a></li> 167<li><a href="#fs_filehandle_utimes_atime_mtime"><code>filehandle.utimes(atime, mtime)</code></a></li> 168<li><a href="#fs_filehandle_write_buffer_offset_length_position"><code>filehandle.write(buffer[, offset[, length[, position]]])</code></a></li> 169<li><a href="#fs_filehandle_write_string_position_encoding"><code>filehandle.write(string[, position[, encoding]])</code></a></li> 170<li><a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile(data, options)</code></a></li> 171<li><a href="#fs_filehandle_writev_buffers_position"><code>filehandle.writev(buffers[, position])</code></a></li> 172</ul> 173</li> 174<li><a href="#fs_fspromises_access_path_mode"><code>fsPromises.access(path[, mode])</code></a></li> 175<li><a href="#fs_fspromises_appendfile_path_data_options"><code>fsPromises.appendFile(path, data[, options])</code></a></li> 176<li><a href="#fs_fspromises_chmod_path_mode"><code>fsPromises.chmod(path, mode)</code></a></li> 177<li><a href="#fs_fspromises_chown_path_uid_gid"><code>fsPromises.chown(path, uid, gid)</code></a></li> 178<li><a href="#fs_fspromises_copyfile_src_dest_mode"><code>fsPromises.copyFile(src, dest[, mode])</code></a></li> 179<li><a href="#fs_fspromises_lchmod_path_mode"><code>fsPromises.lchmod(path, mode)</code></a></li> 180<li><a href="#fs_fspromises_lchown_path_uid_gid"><code>fsPromises.lchown(path, uid, gid)</code></a></li> 181<li><a href="#fs_fspromises_lutimes_path_atime_mtime"><code>fsPromises.lutimes(path, atime, mtime)</code></a></li> 182<li><a href="#fs_fspromises_link_existingpath_newpath"><code>fsPromises.link(existingPath, newPath)</code></a></li> 183<li><a href="#fs_fspromises_lstat_path_options"><code>fsPromises.lstat(path[, options])</code></a></li> 184<li><a href="#fs_fspromises_mkdir_path_options"><code>fsPromises.mkdir(path[, options])</code></a></li> 185<li><a href="#fs_fspromises_mkdtemp_prefix_options"><code>fsPromises.mkdtemp(prefix[, options])</code></a></li> 186<li><a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open(path, flags[, mode])</code></a></li> 187<li><a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir(path[, options])</code></a></li> 188<li><a href="#fs_fspromises_readdir_path_options"><code>fsPromises.readdir(path[, options])</code></a></li> 189<li><a href="#fs_fspromises_readfile_path_options"><code>fsPromises.readFile(path[, options])</code></a></li> 190<li><a href="#fs_fspromises_readlink_path_options"><code>fsPromises.readlink(path[, options])</code></a></li> 191<li><a href="#fs_fspromises_realpath_path_options"><code>fsPromises.realpath(path[, options])</code></a></li> 192<li><a href="#fs_fspromises_rename_oldpath_newpath"><code>fsPromises.rename(oldPath, newPath)</code></a></li> 193<li><a href="#fs_fspromises_rmdir_path_options"><code>fsPromises.rmdir(path[, options])</code></a></li> 194<li><a href="#fs_fspromises_rm_path_options"><code>fsPromises.rm(path[, options])</code></a></li> 195<li><a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat(path[, options])</code></a></li> 196<li><a href="#fs_fspromises_symlink_target_path_type"><code>fsPromises.symlink(target, path[, type])</code></a></li> 197<li><a href="#fs_fspromises_truncate_path_len"><code>fsPromises.truncate(path[, len])</code></a></li> 198<li><a href="#fs_fspromises_unlink_path"><code>fsPromises.unlink(path)</code></a></li> 199<li><a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes(path, atime, mtime)</code></a></li> 200<li><a href="#fs_fspromises_watch_filename_options"><code>fsPromises.watch(filename[, options])</code></a></li> 201<li><a href="#fs_fspromises_writefile_file_data_options"><code>fsPromises.writeFile(file, data[, options])</code></a></li> 202</ul> 203</li> 204<li><a href="#fs_callback_api">Callback API</a> 205<ul> 206<li><a href="#fs_fs_access_path_mode_callback"><code>fs.access(path[, mode], callback)</code></a></li> 207<li><a href="#fs_fs_appendfile_path_data_options_callback"><code>fs.appendFile(path, data[, options], callback)</code></a></li> 208<li><a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod(path, mode, callback)</code></a> 209<ul> 210<li><a href="#fs_file_modes">File modes</a></li> 211</ul> 212</li> 213<li><a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown(path, uid, gid, callback)</code></a></li> 214<li><a href="#fs_fs_close_fd_callback"><code>fs.close(fd[, callback])</code></a></li> 215<li><a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile(src, dest[, mode], callback)</code></a></li> 216<li><a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream(path[, options])</code></a></li> 217<li><a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream(path[, options])</code></a></li> 218<li><span class="stability_0"><a href="#fs_fs_exists_path_callback"><code>fs.exists(path, callback)</code></a></span></li> 219<li><a href="#fs_fs_fchmod_fd_mode_callback"><code>fs.fchmod(fd, mode, callback)</code></a></li> 220<li><a href="#fs_fs_fchown_fd_uid_gid_callback"><code>fs.fchown(fd, uid, gid, callback)</code></a></li> 221<li><a href="#fs_fs_fdatasync_fd_callback"><code>fs.fdatasync(fd, callback)</code></a></li> 222<li><a href="#fs_fs_fstat_fd_options_callback"><code>fs.fstat(fd[, options], callback)</code></a></li> 223<li><a href="#fs_fs_fsync_fd_callback"><code>fs.fsync(fd, callback)</code></a></li> 224<li><a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate(fd[, len], callback)</code></a></li> 225<li><a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes(fd, atime, mtime, callback)</code></a></li> 226<li><a href="#fs_fs_lchmod_path_mode_callback"><code>fs.lchmod(path, mode, callback)</code></a></li> 227<li><a href="#fs_fs_lchown_path_uid_gid_callback"><code>fs.lchown(path, uid, gid, callback)</code></a></li> 228<li><a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes(path, atime, mtime, callback)</code></a></li> 229<li><a href="#fs_fs_link_existingpath_newpath_callback"><code>fs.link(existingPath, newPath, callback)</code></a></li> 230<li><a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat(path[, options], callback)</code></a></li> 231<li><a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir(path[, options], callback)</code></a></li> 232<li><a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp(prefix[, options], callback)</code></a></li> 233<li><a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open(path[, flags[, mode]], callback)</code></a></li> 234<li><a href="#fs_fs_opendir_path_options_callback"><code>fs.opendir(path[, options], callback)</code></a></li> 235<li><a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read(fd, buffer, offset, length, position, callback)</code></a></li> 236<li><a href="#fs_fs_read_fd_options_callback"><code>fs.read(fd, [options,] callback)</code></a></li> 237<li><a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir(path[, options], callback)</code></a></li> 238<li><a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile(path[, options], callback)</code></a> 239<ul> 240<li><a href="#fs_file_descriptors">File descriptors</a></li> 241<li><a href="#fs_performance_considerations">Performance Considerations</a></li> 242</ul> 243</li> 244<li><a href="#fs_fs_readlink_path_options_callback"><code>fs.readlink(path[, options], callback)</code></a></li> 245<li><a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv(fd, buffers[, position], callback)</code></a></li> 246<li><a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath(path[, options], callback)</code></a></li> 247<li><a href="#fs_fs_realpath_native_path_options_callback"><code>fs.realpath.native(path[, options], callback)</code></a></li> 248<li><a href="#fs_fs_rename_oldpath_newpath_callback"><code>fs.rename(oldPath, newPath, callback)</code></a></li> 249<li><a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir(path[, options], callback)</code></a></li> 250<li><a href="#fs_fs_rm_path_options_callback"><code>fs.rm(path[, options], callback)</code></a></li> 251<li><a href="#fs_fs_stat_path_options_callback"><code>fs.stat(path[, options], callback)</code></a></li> 252<li><a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink(target, path[, type], callback)</code></a></li> 253<li><a href="#fs_fs_truncate_path_len_callback"><code>fs.truncate(path[, len], callback)</code></a></li> 254<li><a href="#fs_fs_unlink_path_callback"><code>fs.unlink(path, callback)</code></a></li> 255<li><a href="#fs_fs_unwatchfile_filename_listener"><code>fs.unwatchFile(filename[, listener])</code></a></li> 256<li><a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes(path, atime, mtime, callback)</code></a></li> 257<li><a href="#fs_fs_watch_filename_options_listener"><code>fs.watch(filename[, options][, listener])</code></a> 258<ul> 259<li><a href="#fs_caveats">Caveats</a> 260<ul> 261<li><a href="#fs_availability">Availability</a></li> 262<li><a href="#fs_inodes">Inodes</a></li> 263<li><a href="#fs_filename_argument">Filename argument</a></li> 264</ul> 265</li> 266</ul> 267</li> 268<li><a href="#fs_fs_watchfile_filename_options_listener"><code>fs.watchFile(filename[, options], listener)</code></a></li> 269<li><a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer[, offset[, length[, position]]], callback)</code></a></li> 270<li><a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string[, position[, encoding]], callback)</code></a></li> 271<li><a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile(file, data[, options], callback)</code></a> 272<ul> 273<li><a href="#fs_using_fs_writefile_with_file_descriptors">Using <code>fs.writeFile()</code> with file descriptors</a></li> 274</ul> 275</li> 276<li><a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev(fd, buffers[, position], callback)</code></a></li> 277</ul> 278</li> 279<li><a href="#fs_synchronous_api">Synchronous API</a> 280<ul> 281<li><a href="#fs_fs_accesssync_path_mode"><code>fs.accessSync(path[, mode])</code></a></li> 282<li><a href="#fs_fs_appendfilesync_path_data_options"><code>fs.appendFileSync(path, data[, options])</code></a></li> 283<li><a href="#fs_fs_chmodsync_path_mode"><code>fs.chmodSync(path, mode)</code></a></li> 284<li><a href="#fs_fs_chownsync_path_uid_gid"><code>fs.chownSync(path, uid, gid)</code></a></li> 285<li><a href="#fs_fs_closesync_fd"><code>fs.closeSync(fd)</code></a></li> 286<li><a href="#fs_fs_copyfilesync_src_dest_mode"><code>fs.copyFileSync(src, dest[, mode])</code></a></li> 287<li><a href="#fs_fs_existssync_path"><code>fs.existsSync(path)</code></a></li> 288<li><a href="#fs_fs_fchmodsync_fd_mode"><code>fs.fchmodSync(fd, mode)</code></a></li> 289<li><a href="#fs_fs_fchownsync_fd_uid_gid"><code>fs.fchownSync(fd, uid, gid)</code></a></li> 290<li><a href="#fs_fs_fdatasyncsync_fd"><code>fs.fdatasyncSync(fd)</code></a></li> 291<li><a href="#fs_fs_fstatsync_fd_options"><code>fs.fstatSync(fd[, options])</code></a></li> 292<li><a href="#fs_fs_fsyncsync_fd"><code>fs.fsyncSync(fd)</code></a></li> 293<li><a href="#fs_fs_ftruncatesync_fd_len"><code>fs.ftruncateSync(fd[, len])</code></a></li> 294<li><a href="#fs_fs_futimessync_fd_atime_mtime"><code>fs.futimesSync(fd, atime, mtime)</code></a></li> 295<li><a href="#fs_fs_lchmodsync_path_mode"><code>fs.lchmodSync(path, mode)</code></a></li> 296<li><a href="#fs_fs_lchownsync_path_uid_gid"><code>fs.lchownSync(path, uid, gid)</code></a></li> 297<li><a href="#fs_fs_lutimessync_path_atime_mtime"><code>fs.lutimesSync(path, atime, mtime)</code></a></li> 298<li><a href="#fs_fs_linksync_existingpath_newpath"><code>fs.linkSync(existingPath, newPath)</code></a></li> 299<li><a href="#fs_fs_lstatsync_path_options"><code>fs.lstatSync(path[, options])</code></a></li> 300<li><a href="#fs_fs_mkdirsync_path_options"><code>fs.mkdirSync(path[, options])</code></a></li> 301<li><a href="#fs_fs_mkdtempsync_prefix_options"><code>fs.mkdtempSync(prefix[, options])</code></a></li> 302<li><a href="#fs_fs_opendirsync_path_options"><code>fs.opendirSync(path[, options])</code></a></li> 303<li><a href="#fs_fs_opensync_path_flags_mode"><code>fs.openSync(path[, flags[, mode]])</code></a></li> 304<li><a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync(path[, options])</code></a></li> 305<li><a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync(path[, options])</code></a></li> 306<li><a href="#fs_fs_readlinksync_path_options"><code>fs.readlinkSync(path[, options])</code></a></li> 307<li><a href="#fs_fs_readsync_fd_buffer_offset_length_position"><code>fs.readSync(fd, buffer, offset, length, position)</code></a></li> 308<li><a href="#fs_fs_readsync_fd_buffer_options"><code>fs.readSync(fd, buffer, [options])</code></a></li> 309<li><a href="#fs_fs_readvsync_fd_buffers_position"><code>fs.readvSync(fd, buffers[, position])</code></a></li> 310<li><a href="#fs_fs_realpathsync_path_options"><code>fs.realpathSync(path[, options])</code></a></li> 311<li><a href="#fs_fs_realpathsync_native_path_options"><code>fs.realpathSync.native(path[, options])</code></a></li> 312<li><a href="#fs_fs_renamesync_oldpath_newpath"><code>fs.renameSync(oldPath, newPath)</code></a></li> 313<li><a href="#fs_fs_rmdirsync_path_options"><code>fs.rmdirSync(path[, options])</code></a></li> 314<li><a href="#fs_fs_rmsync_path_options"><code>fs.rmSync(path[, options])</code></a></li> 315<li><a href="#fs_fs_statsync_path_options"><code>fs.statSync(path[, options])</code></a></li> 316<li><a href="#fs_fs_symlinksync_target_path_type"><code>fs.symlinkSync(target, path[, type])</code></a></li> 317<li><a href="#fs_fs_truncatesync_path_len"><code>fs.truncateSync(path[, len])</code></a></li> 318<li><a href="#fs_fs_unlinksync_path"><code>fs.unlinkSync(path)</code></a></li> 319<li><a href="#fs_fs_utimessync_path_atime_mtime"><code>fs.utimesSync(path, atime, mtime)</code></a></li> 320<li><a href="#fs_fs_writefilesync_file_data_options"><code>fs.writeFileSync(file, data[, options])</code></a></li> 321<li><a href="#fs_fs_writesync_fd_buffer_offset_length_position"><code>fs.writeSync(fd, buffer[, offset[, length[, position]]])</code></a></li> 322<li><a href="#fs_fs_writesync_fd_string_position_encoding"><code>fs.writeSync(fd, string[, position[, encoding]])</code></a></li> 323<li><a href="#fs_fs_writevsync_fd_buffers_position"><code>fs.writevSync(fd, buffers[, position])</code></a></li> 324</ul> 325</li> 326<li><a href="#fs_common_objects">Common Objects</a> 327<ul> 328<li><a href="#fs_class_fs_dir">Class: <code>fs.Dir</code></a> 329<ul> 330<li><a href="#fs_dir_close"><code>dir.close()</code></a></li> 331<li><a href="#fs_dir_close_callback"><code>dir.close(callback)</code></a></li> 332<li><a href="#fs_dir_closesync"><code>dir.closeSync()</code></a></li> 333<li><a href="#fs_dir_path"><code>dir.path</code></a></li> 334<li><a href="#fs_dir_read"><code>dir.read()</code></a></li> 335<li><a href="#fs_dir_read_callback"><code>dir.read(callback)</code></a></li> 336<li><a href="#fs_dir_readsync"><code>dir.readSync()</code></a></li> 337<li><a href="#fs_dir_symbol_asynciterator"><code>dir[Symbol.asyncIterator]()</code></a></li> 338</ul> 339</li> 340<li><a href="#fs_class_fs_dirent">Class: <code>fs.Dirent</code></a> 341<ul> 342<li><a href="#fs_dirent_isblockdevice"><code>dirent.isBlockDevice()</code></a></li> 343<li><a href="#fs_dirent_ischaracterdevice"><code>dirent.isCharacterDevice()</code></a></li> 344<li><a href="#fs_dirent_isdirectory"><code>dirent.isDirectory()</code></a></li> 345<li><a href="#fs_dirent_isfifo"><code>dirent.isFIFO()</code></a></li> 346<li><a href="#fs_dirent_isfile"><code>dirent.isFile()</code></a></li> 347<li><a href="#fs_dirent_issocket"><code>dirent.isSocket()</code></a></li> 348<li><a href="#fs_dirent_issymboliclink"><code>dirent.isSymbolicLink()</code></a></li> 349<li><a href="#fs_dirent_name"><code>dirent.name</code></a></li> 350</ul> 351</li> 352<li><a href="#fs_class_fs_fswatcher">Class: <code>fs.FSWatcher</code></a> 353<ul> 354<li><a href="#fs_event_change">Event: <code>'change'</code></a></li> 355<li><a href="#fs_event_close">Event: <code>'close'</code></a></li> 356<li><a href="#fs_event_error">Event: <code>'error'</code></a></li> 357<li><a href="#fs_watcher_close"><code>watcher.close()</code></a></li> 358<li><a href="#fs_watcher_ref"><code>watcher.ref()</code></a></li> 359<li><a href="#fs_watcher_unref"><code>watcher.unref()</code></a></li> 360</ul> 361</li> 362<li><a href="#fs_class_fs_statwatcher">Class: <code>fs.StatWatcher</code></a> 363<ul> 364<li><a href="#fs_watcher_ref_1"><code>watcher.ref()</code></a></li> 365<li><a href="#fs_watcher_unref_1"><code>watcher.unref()</code></a></li> 366</ul> 367</li> 368<li><a href="#fs_class_fs_readstream">Class: <code>fs.ReadStream</code></a> 369<ul> 370<li><a href="#fs_event_close_1">Event: <code>'close'</code></a></li> 371<li><a href="#fs_event_open">Event: <code>'open'</code></a></li> 372<li><a href="#fs_event_ready">Event: <code>'ready'</code></a></li> 373<li><a href="#fs_readstream_bytesread"><code>readStream.bytesRead</code></a></li> 374<li><a href="#fs_readstream_path"><code>readStream.path</code></a></li> 375<li><a href="#fs_readstream_pending"><code>readStream.pending</code></a></li> 376</ul> 377</li> 378<li><a href="#fs_class_fs_stats">Class: <code>fs.Stats</code></a> 379<ul> 380<li><a href="#fs_stats_isblockdevice"><code>stats.isBlockDevice()</code></a></li> 381<li><a href="#fs_stats_ischaracterdevice"><code>stats.isCharacterDevice()</code></a></li> 382<li><a href="#fs_stats_isdirectory"><code>stats.isDirectory()</code></a></li> 383<li><a href="#fs_stats_isfifo"><code>stats.isFIFO()</code></a></li> 384<li><a href="#fs_stats_isfile"><code>stats.isFile()</code></a></li> 385<li><a href="#fs_stats_issocket"><code>stats.isSocket()</code></a></li> 386<li><a href="#fs_stats_issymboliclink"><code>stats.isSymbolicLink()</code></a></li> 387<li><a href="#fs_stats_dev"><code>stats.dev</code></a></li> 388<li><a href="#fs_stats_ino"><code>stats.ino</code></a></li> 389<li><a href="#fs_stats_mode"><code>stats.mode</code></a></li> 390<li><a href="#fs_stats_nlink"><code>stats.nlink</code></a></li> 391<li><a href="#fs_stats_uid"><code>stats.uid</code></a></li> 392<li><a href="#fs_stats_gid"><code>stats.gid</code></a></li> 393<li><a href="#fs_stats_rdev"><code>stats.rdev</code></a></li> 394<li><a href="#fs_stats_size"><code>stats.size</code></a></li> 395<li><a href="#fs_stats_blksize"><code>stats.blksize</code></a></li> 396<li><a href="#fs_stats_blocks"><code>stats.blocks</code></a></li> 397<li><a href="#fs_stats_atimems"><code>stats.atimeMs</code></a></li> 398<li><a href="#fs_stats_mtimems"><code>stats.mtimeMs</code></a></li> 399<li><a href="#fs_stats_ctimems"><code>stats.ctimeMs</code></a></li> 400<li><a href="#fs_stats_birthtimems"><code>stats.birthtimeMs</code></a></li> 401<li><a href="#fs_stats_atimens"><code>stats.atimeNs</code></a></li> 402<li><a href="#fs_stats_mtimens"><code>stats.mtimeNs</code></a></li> 403<li><a href="#fs_stats_ctimens"><code>stats.ctimeNs</code></a></li> 404<li><a href="#fs_stats_birthtimens"><code>stats.birthtimeNs</code></a></li> 405<li><a href="#fs_stats_atime"><code>stats.atime</code></a></li> 406<li><a href="#fs_stats_mtime"><code>stats.mtime</code></a></li> 407<li><a href="#fs_stats_ctime"><code>stats.ctime</code></a></li> 408<li><a href="#fs_stats_birthtime"><code>stats.birthtime</code></a></li> 409<li><a href="#fs_stat_time_values">Stat time values</a></li> 410</ul> 411</li> 412<li><a href="#fs_class_fs_writestream">Class: <code>fs.WriteStream</code></a> 413<ul> 414<li><a href="#fs_event_close_2">Event: <code>'close'</code></a></li> 415<li><a href="#fs_event_open_1">Event: <code>'open'</code></a></li> 416<li><a href="#fs_event_ready_1">Event: <code>'ready'</code></a></li> 417<li><a href="#fs_writestream_byteswritten"><code>writeStream.bytesWritten</code></a></li> 418<li><a href="#fs_writestream_close_callback"><code>writeStream.close([callback])</code></a></li> 419<li><a href="#fs_writestream_path"><code>writeStream.path</code></a></li> 420<li><a href="#fs_writestream_pending"><code>writeStream.pending</code></a></li> 421</ul> 422</li> 423<li><a href="#fs_fs_constants"><code>fs.constants</code></a> 424<ul> 425<li><a href="#fs_fs_constants_1">FS constants</a> 426<ul> 427<li><a href="#fs_file_access_constants">File access constants</a></li> 428<li><a href="#fs_file_copy_constants">File copy constants</a></li> 429<li><a href="#fs_file_open_constants">File open constants</a></li> 430<li><a href="#fs_file_type_constants">File type constants</a></li> 431<li><a href="#fs_file_mode_constants">File mode constants</a></li> 432</ul> 433</li> 434</ul> 435</li> 436</ul> 437</li> 438<li><a href="#fs_notes">Notes</a> 439<ul> 440<li><a href="#fs_ordering_of_callback_and_promise_based_operations">Ordering of callback and promise-based operations</a></li> 441<li><a href="#fs_file_paths">File paths</a> 442<ul> 443<li><a href="#fs_string_paths">String paths</a></li> 444<li><a href="#fs_file_url_paths">File URL paths</a> 445<ul> 446<li><a href="#fs_platform_specific_considerations">Platform-specific considerations</a></li> 447</ul> 448</li> 449<li><a href="#fs_buffer_paths">Buffer paths</a></li> 450<li><a href="#fs_per_drive_working_directories_on_windows">Per-drive working directories on Windows</a></li> 451</ul> 452</li> 453<li><a href="#fs_file_descriptors_1">File descriptors</a></li> 454<li><a href="#fs_threadpool_usage">Threadpool usage</a></li> 455<li><a href="#fs_file_system_flags">File system flags</a></li> 456</ul> 457</li> 458</ul> 459</li> 460</ul></details> 461 462 <div id="apicontent"> 463 <h2>File system<span><a class="mark" href="#fs_file_system" id="fs_file_system">#</a></span></h2> 464 465<p></p><div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p></p> 466 467<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v14.20.1/lib/fs.js">lib/fs.js</a></p> 468<p>The <code>fs</code> module enables interacting with the file system in a 469way modeled on standard POSIX functions.</p> 470<p>To use the promise-based APIs:</p> 471 472<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> 473<p>To use the callback and sync APIs:</p> 474 475<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> 476<p>All file system operations have synchronous, callback, and promise-based 477forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).</p> 478<section><h3>Promise example<span><a class="mark" href="#fs_promise_example" id="fs_promise_example">#</a></span></h3> 479<p>Promise-based operations return a promise that is fulfilled when the 480asynchronous operation is complete.</p> 481 482<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>; 483 484<span class="hljs-keyword">try</span> { 485 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(<span class="hljs-string">'/tmp/hello'</span>); 486 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 487} <span class="hljs-keyword">catch</span> (error) { 488 <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>); 489}</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>); 490 491(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params">path</span>) { 492 <span class="hljs-keyword">try</span> { 493 <span class="hljs-keyword">await</span> <span class="hljs-title function_">unlink</span>(path); 494 <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>); 495 } <span class="hljs-keyword">catch</span> (error) { 496 <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>); 497 } 498})(<span class="hljs-string">'/tmp/hello'</span>);</code></pre> 499</section><section><h3>Callback example<span><a class="mark" href="#fs_callback_example" id="fs_callback_example">#</a></span></h3> 500<p>The callback form takes a completion callback function as its last 501argument and invokes the operation asynchronously. The arguments passed to 502the completion callback depend on the method, but the first argument is always 503reserved for an exception. If the operation is completed successfully, then 504the first argument is <code>null</code> or <code>undefined</code>.</p> 505 506<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>; 507 508<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> { 509 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 510 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 511});</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>); 512 513<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> { 514 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 515 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 516});</code></pre> 517<p>The callback-based versions of the <code>fs</code> module APIs are preferable over 518the use of the promise APIs when maximal performance (both in terms of 519execution time and memory allocation are required).</p> 520</section><section><h3>Synchronous example<span><a class="mark" href="#fs_synchronous_example" id="fs_synchronous_example">#</a></span></h3> 521<p>The synchronous APIs block the Node.js event loop and further JavaScript 522execution until the operation is complete. Exceptions are thrown immediately 523and can be handled using <code>try…catch</code>, or can be allowed to bubble up.</p> 524 525<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>; 526 527<span class="hljs-keyword">try</span> { 528 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 529 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 530} <span class="hljs-keyword">catch</span> (err) { 531 <span class="hljs-comment">// handle the error</span> 532}</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>); 533 534<span class="hljs-keyword">try</span> { 535 <span class="hljs-title function_">unlinkSync</span>(<span class="hljs-string">'/tmp/hello'</span>); 536 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'successfully deleted /tmp/hello'</span>); 537} <span class="hljs-keyword">catch</span> (err) { 538 <span class="hljs-comment">// handle the error</span> 539}</code></pre> 540</section><section><h3>Promises API<span><a class="mark" href="#fs_promises_api" id="fs_promises_api">#</a></span></h3> 541<div class="api_metadata"> 542<details class="changelog"><summary>History</summary> 543<table> 544<tbody><tr><th>Version</th><th>Changes</th></tr> 545<tr><td>v14.0.0</td> 546<td><p>Exposed as <code>require('fs/promises')</code>.</p></td></tr> 547<tr><td>v11.14.0, v10.17.0</td> 548<td><p>This API is no longer experimental.</p></td></tr> 549<tr><td>v10.1.0</td> 550<td><p>The API is accessible via <code>require('fs').promises</code> only.</p></td></tr> 551<tr><td>v10.0.0</td> 552<td><p><span>Added in: v10.0.0</span></p></td></tr> 553</tbody></table> 554</details> 555</div> 556<p>The <code>fs/promises</code> API provides asynchronous file system methods that return 557promises.</p> 558<p>The promise APIs use the underlying Node.js threadpool to perform file 559system operations off the event loop thread. These operations are not 560synchronized or threadsafe. Care must be taken when performing multiple 561concurrent modifications on the same file or data corruption may occur.</p> 562<h4>Class: <code>FileHandle</code><span><a class="mark" href="#fs_class_filehandle" id="fs_class_filehandle">#</a></span></h4> 563<div class="api_metadata"> 564<span>Added in: v10.0.0</span> 565</div> 566<p>A <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object is an object wrapper for a numeric file descriptor.</p> 567<p>Instances of the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object are created by the <code>fsPromises.open()</code> 568method.</p> 569<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> 570<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 571try to automatically close the file descriptor and emit a process warning, 572helping to prevent memory leaks. Please do not rely on this behavior because 573it can be unreliable and the file may not be closed. Instead, always explicitly 574close <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>s. Node.js may change this behavior in the future.</p> 575<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> 576<div class="api_metadata"> 577<details class="changelog"><summary>History</summary> 578<table> 579<tbody><tr><th>Version</th><th>Changes</th></tr> 580<tr><td>v14.18.0</td> 581<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 582<tr><td>v14.0.0</td> 583<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 584<tr><td>v10.0.0</td> 585<td><p><span>Added in: v10.0.0</span></p></td></tr> 586</tbody></table> 587</details> 588</div> 589<ul> 590<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> 591<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> 592<ul> 593<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> 594</ul> 595</li> 596<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> 597</ul> 598<p>Alias of <a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 599<p>When operating on file handles, the mode cannot be changed from what it was set 600to with <a href="#fs_fspromises_open_path_flags_mode"><code>fsPromises.open()</code></a>. Therefore, this is equivalent to 601<a href="#fs_filehandle_writefile_data_options"><code>filehandle.writeFile()</code></a>.</p> 602<h5><code>filehandle.chmod(mode)</code><span><a class="mark" href="#fs_filehandle_chmod_mode" id="fs_filehandle_chmod_mode">#</a></span></h5> 603<div class="api_metadata"> 604<span>Added in: v10.0.0</span> 605</div> 606<ul> 607<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> 608<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> 609</ul> 610<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> 611<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> 612<div class="api_metadata"> 613<span>Added in: v10.0.0</span> 614</div> 615<ul> 616<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> 617<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> 618<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> 619</ul> 620<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> 621<h5><code>filehandle.close()</code><span><a class="mark" href="#fs_filehandle_close" id="fs_filehandle_close">#</a></span></h5> 622<div class="api_metadata"> 623<span>Added in: v10.0.0</span> 624</div> 625<ul> 626<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> 627</ul> 628<p>Closes the file handle after waiting for any pending operation on the handle to 629complete.</p> 630<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>; 631 632<span class="hljs-keyword">let</span> filehandle; 633<span class="hljs-keyword">try</span> { 634 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>); 635} <span class="hljs-keyword">finally</span> { 636 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 637}</code></pre> 638<h5><code>filehandle.datasync()</code><span><a class="mark" href="#fs_filehandle_datasync" id="fs_filehandle_datasync">#</a></span></h5> 639<div class="api_metadata"> 640<span>Added in: v10.0.0</span> 641</div> 642<ul> 643<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> 644</ul> 645<p>Forces all currently queued I/O operations associated with the file to the 646operating system's synchronized I/O completion state. Refer to the POSIX 647<a href="http://man7.org/linux/man-pages/man2/fdatasync.2.html"><code>fdatasync(2)</code></a> documentation for details.</p> 648<p>Unlike <code>filehandle.sync</code> this method does not flush modified metadata.</p> 649<h5><code>filehandle.fd</code><span><a class="mark" href="#fs_filehandle_fd" id="fs_filehandle_fd">#</a></span></h5> 650<div class="api_metadata"> 651<span>Added in: v10.0.0</span> 652</div> 653<ul> 654<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> 655</ul> 656<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> 657<div class="api_metadata"> 658<span>Added in: v10.0.0</span> 659</div> 660<ul> 661<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 662file data read.</li> 663<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. 664<strong>Default:</strong> <code>0</code></li> 665<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> 666<code>buffer.byteLength</code></li> 667<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 668file. If <code>null</code>, data will be read from the current file position, and 669the position will be updated. If <code>position</code> is an integer, the current 670file position will remain unchanged.</li> 671<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: 672<ul> 673<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> 674<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> 675argument.</li> 676</ul> 677</li> 678</ul> 679<p>Reads data from the file and stores that in the given buffer.</p> 680<p>If the file is not modified concurrently, the end-of-file is reached when the 681number of bytes read is zero.</p> 682<h5><code>filehandle.read([options])</code><span><a class="mark" href="#fs_filehandle_read_options" id="fs_filehandle_read_options">#</a></span></h5> 683<div class="api_metadata"> 684<span>Added in: v13.11.0, v12.17.0</span> 685</div> 686<ul> 687<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 688<ul> 689<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 690file data read. <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li> 691<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. 692<strong>Default:</strong> <code>0</code></li> 693<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> 694<code>buffer.byteLength</code></li> 695<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 696file. If <code>null</code>, data will be read from the current file position, and 697the position will be updated. If <code>position</code> is an integer, the current 698file position will remain unchanged. <strong>Default:</strong>: <code>null</code></li> 699</ul> 700</li> 701<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: 702<ul> 703<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> 704<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> 705argument.</li> 706</ul> 707</li> 708</ul> 709<p>Reads data from the file and stores that in the given buffer.</p> 710<p>If the file is not modified concurrently, the end-of-file is reached when the 711number of bytes read is zero.</p> 712<h5><code>filehandle.readFile(options)</code><span><a class="mark" href="#fs_filehandle_readfile_options" id="fs_filehandle_readfile_options">#</a></span></h5> 713<div class="api_metadata"> 714<span>Added in: v10.0.0</span> 715</div> 716<ul> 717<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> 718<ul> 719<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> 720<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 721</ul> 722</li> 723<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 724file. If no encoding is specified (using <code>options.encoding</code>), the data is 725returned as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</li> 726</ul> 727<p>Asynchronously reads the entire contents of a file.</p> 728<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 729<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 730<p>If one or more <code>filehandle.read()</code> calls are made on a file handle and then a 731<code>filehandle.readFile()</code> call is made, the data will be read from the current 732position till the end of the file. It doesn't always read from the beginning 733of the file.</p> 734<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> 735<div class="api_metadata"> 736<span>Added in: v13.13.0, v12.17.0</span> 737</div> 738<ul> 739<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> 740<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 741should be read from. If <code>position</code> is not a <code>number</code>, the data will be read 742from the current position.</li> 743<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: 744<ul> 745<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> 746<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 747a reference to the <code>buffers</code> input.</li> 748</ul> 749</li> 750</ul> 751<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> 752<h5><code>filehandle.stat([options])</code><span><a class="mark" href="#fs_filehandle_stat_options" id="fs_filehandle_stat_options">#</a></span></h5> 753<div class="api_metadata"> 754<details class="changelog"><summary>History</summary> 755<table> 756<tbody><tr><th>Version</th><th>Changes</th></tr> 757<tr><td>v10.5.0</td> 758<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 759<tr><td>v10.0.0</td> 760<td><p><span>Added in: v10.0.0</span></p></td></tr> 761</tbody></table> 762</details> 763</div> 764<ul> 765<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 766<ul> 767<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 768<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> 769</ul> 770</li> 771<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> 772</ul> 773<h5><code>filehandle.sync()</code><span><a class="mark" href="#fs_filehandle_sync" id="fs_filehandle_sync">#</a></span></h5> 774<div class="api_metadata"> 775<span>Added in: v10.0.0</span> 776</div> 777<ul> 778<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> 779</ul> 780<p>Request that all data for the open file descriptor is flushed to the storage 781device. The specific implementation is operating system and device specific. 782Refer 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> 783<h5><code>filehandle.truncate(len)</code><span><a class="mark" href="#fs_filehandle_truncate_len" id="fs_filehandle_truncate_len">#</a></span></h5> 784<div class="api_metadata"> 785<span>Added in: v10.0.0</span> 786</div> 787<ul> 788<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> 789<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> 790</ul> 791<p>Truncates the file.</p> 792<p>If the file was larger than <code>len</code> bytes, only the first <code>len</code> bytes will be 793retained in the file.</p> 794<p>The following example retains only the first four bytes of the file:</p> 795<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>; 796 797<span class="hljs-keyword">let</span> filehandle = <span class="hljs-literal">null</span>; 798<span class="hljs-keyword">try</span> { 799 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>); 800 <span class="hljs-keyword">await</span> filehandle.<span class="hljs-title function_">truncate</span>(<span class="hljs-number">4</span>); 801} <span class="hljs-keyword">finally</span> { 802 <span class="hljs-keyword">await</span> filehandle?.<span class="hljs-title function_">close</span>(); 803}</code></pre> 804<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the 805extended part is filled with null bytes (<code>'\0'</code>):</p> 806<p>If <code>len</code> is negative then <code>0</code> will be used.</p> 807<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> 808<div class="api_metadata"> 809<span>Added in: v10.0.0</span> 810</div> 811<ul> 812<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> 813<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> 814<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 815</ul> 816<p>Change the file system timestamps of the object referenced by the <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> 817then resolves the promise with no arguments upon success.</p> 818<p>This function does not work on AIX versions before 7.1, it will reject the 819promise with an error using code <code>UV_ENOSYS</code>.</p> 820<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> 821<div class="api_metadata"> 822<details class="changelog"><summary>History</summary> 823<table> 824<tbody><tr><th>Version</th><th>Changes</th></tr> 825<tr><td>v14.0.0</td> 826<td><p>The <code>buffer</code> parameter won't coerce unsupported input to buffers anymore.</p></td></tr> 827<tr><td>v10.0.0</td> 828<td><p><span>Added in: v10.0.0</span></p></td></tr> 829</tbody></table> 830</details> 831</div> 832<ul> 833<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> 834<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 835to write begins. <strong>Default:</strong> <code>0</code></li> 836<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> 837<code>buffer.byteLength - offset</code></li> 838<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 839data from <code>buffer</code> should be written. If <code>position</code> is not a <code>number</code>, 840the 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> 841documentation for more detail.</li> 842<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 843</ul> 844<p>Write <code>buffer</code> to the file.</p> 845<p>The promise is resolved with an object containing two properties:</p> 846<ul> 847<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> 848<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 849<code>buffer</code> written.</li> 850</ul> 851<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 852without waiting for the promise to be resolved (or rejected). For this 853scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 854<p>On Linux, positional writes do not work when the file is opened in append mode. 855The kernel ignores the position argument and always appends the data to 856the end of the file.</p> 857<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> 858<div class="api_metadata"> 859<details class="changelog"><summary>History</summary> 860<table> 861<tbody><tr><th>Version</th><th>Changes</th></tr> 862<tr><td>v14.0.0</td> 863<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 864<tr><td>v10.0.0</td> 865<td><p><span>Added in: v10.0.0</span></p></td></tr> 866</tbody></table> 867</details> 868</div> 869<ul> 870<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 871<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 872data from <code>string</code> should be written. If <code>position</code> is not a <code>number</code> the 873data 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> 874documentation for more detail.</li> 875<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> 876<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 877</ul> 878<p>Write <code>string</code> to the file. If <code>string</code> is not a string, the promise is 879rejected with an error.</p> 880<p>The promise is resolved with an object containing two properties:</p> 881<ul> 882<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> 883<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> 884</ul> 885<p>It is unsafe to use <code>filehandle.write()</code> multiple times on the same file 886without waiting for the promise to be resolved (or rejected). For this 887scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 888<p>On Linux, positional writes do not work when the file is opened in append mode. 889The kernel ignores the position argument and always appends the data to 890the end of the file.</p> 891<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> 892<div class="api_metadata"> 893<details class="changelog"><summary>History</summary> 894<table> 895<tbody><tr><th>Version</th><th>Changes</th></tr> 896<tr><td>v14.18.0</td> 897<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 898<tr><td>v14.0.0</td> 899<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 900<tr><td>v10.0.0</td> 901<td><p><span>Added in: v10.0.0</span></p></td></tr> 902</tbody></table> 903</details> 904</div> 905<ul> 906<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> 907<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> 908<ul> 909<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 910string. <strong>Default:</strong> <code>'utf8'</code></li> 911</ul> 912</li> 913<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 914</ul> 915<p>Asynchronously writes data to a file, replacing the file if it already exists. 916<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. 917The promise is resolved with no arguments upon success.</p> 918<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 919<p>The <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support writing.</p> 920<p>It is unsafe to use <code>filehandle.writeFile()</code> multiple times on the same file 921without waiting for the promise to be resolved (or rejected).</p> 922<p>If one or more <code>filehandle.write()</code> calls are made on a file handle and then a 923<code>filehandle.writeFile()</code> call is made, the data will be written from the 924current position till the end of the file. It doesn't always write from the 925beginning of the file.</p> 926<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> 927<div class="api_metadata"> 928<span>Added in: v12.9.0</span> 929</div> 930<ul> 931<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> 932<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 933data from <code>buffers</code> should be written. If <code>position</code> is not a <code>number</code>, 934the data will be written at the current position.</li> 935<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 936</ul> 937<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> 938<p>The promise is resolved with an object containing a two properties:</p> 939<ul> 940<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> 941<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> 942input.</li> 943</ul> 944<p>It is unsafe to call <code>writev()</code> multiple times on the same file without waiting 945for the promise to be resolved (or rejected).</p> 946<p>On Linux, positional writes don't work when the file is opened in append mode. 947The kernel ignores the position argument and always appends the data to 948the end of the file.</p> 949<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> 950<div class="api_metadata"> 951<span>Added in: v10.0.0</span> 952</div> 953<ul> 954<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> 955<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> 956<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> 957</ul> 958<p>Tests a user's permissions for the file or directory specified by <code>path</code>. 959The <code>mode</code> argument is an optional integer that specifies the accessibility 960checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values 961of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of 962two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 963<p>If the accessibility check is successful, the promise is resolved with no 964value. If any of the accessibility checks fail, the promise is rejected 965with 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 966<code>/etc/passwd</code> can be read and written by the current process.</p> 967<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>; 968<span class="hljs-keyword">import</span> { constants } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 969 970<span class="hljs-keyword">try</span> { 971 <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>); 972 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can access'</span>); 973} <span class="hljs-keyword">catch</span> { 974 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'cannot access'</span>); 975}</code></pre> 976<p>Using <code>fsPromises.access()</code> to check for the accessibility of a file before 977calling <code>fsPromises.open()</code> is not recommended. Doing so introduces a race 978condition, since other processes may change the file's state between the two 979calls. Instead, user code should open/read/write the file directly and handle 980the error raised if the file is not accessible.</p> 981<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> 982<div class="api_metadata"> 983<span>Added in: v10.0.0</span> 984</div> 985<ul> 986<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> 987<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> 988<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> 989<ul> 990<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> 991<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> 992<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> 993</ul> 994</li> 995<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> 996</ul> 997<p>Asynchronously append data to a file, creating the file if it does not yet 998exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 999<p>If <code>options</code> is a string, then it specifies the <code>encoding</code>.</p> 1000<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> 1001for more details.</p> 1002<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 1003for appending (using <code>fsPromises.open()</code>).</p> 1004<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> 1005<div class="api_metadata"> 1006<span>Added in: v10.0.0</span> 1007</div> 1008<ul> 1009<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> 1010<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> 1011<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> 1012</ul> 1013<p>Changes the permissions of a file.</p> 1014<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> 1015<div class="api_metadata"> 1016<span>Added in: v10.0.0</span> 1017</div> 1018<ul> 1019<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> 1020<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1021<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1022<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> 1023</ul> 1024<p>Changes the ownership of a file.</p> 1025<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> 1026<div class="api_metadata"> 1027<details class="changelog"><summary>History</summary> 1028<table> 1029<tbody><tr><th>Version</th><th>Changes</th></tr> 1030<tr><td>v14.0.0</td> 1031<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 1032<tr><td>v10.0.0</td> 1033<td><p><span>Added in: v10.0.0</span></p></td></tr> 1034</tbody></table> 1035</details> 1036</div> 1037<ul> 1038<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> 1039<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> 1040<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 1041operation. It is possible to create a mask consisting of the bitwise OR of 1042two or more values (e.g. 1043<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>) 1044<strong>Default:</strong> <code>0</code>. 1045<ul> 1046<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> 1047already exists.</li> 1048<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create 1049a copy-on-write reflink. If the platform does not support copy-on-write, 1050then a fallback copy mechanism is used.</li> 1051<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 1052create a copy-on-write reflink. If the platform does not support 1053copy-on-write, then the operation will fail.</li> 1054</ul> 1055</li> 1056<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> 1057</ul> 1058<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 1059already exists.</p> 1060<p>No guarantees are made about the atomicity of the copy operation. If an 1061error occurs after the destination file has been opened for writing, an attempt 1062will be made to remove the destination.</p> 1063<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>; 1064<span class="hljs-keyword">import</span> { copyFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>; 1065 1066<span class="hljs-keyword">try</span> { 1067 <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>); 1068 <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>); 1069} <span class="hljs-keyword">catch</span> { 1070 <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>); 1071} 1072 1073<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 1074<span class="hljs-keyword">try</span> { 1075 <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>); 1076 <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>); 1077} <span class="hljs-keyword">catch</span> { 1078 <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>); 1079}</code></pre> 1080<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> 1081<div class="api_metadata"> 1082<span>Deprecated since: v10.0.0</span> 1083</div> 1084<ul> 1085<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> 1086<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1087<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> 1088</ul> 1089<p>Changes the permissions on a symbolic link.</p> 1090<p>This method is only implemented on macOS.</p> 1091<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> 1092<div class="api_metadata"> 1093<details class="changelog"><summary>History</summary> 1094<table> 1095<tbody><tr><th>Version</th><th>Changes</th></tr> 1096<tr><td>v10.6.0</td> 1097<td><p>This API is no longer deprecated.</p></td></tr> 1098<tr><td>v10.0.0</td> 1099<td><p><span>Added in: v10.0.0</span></p></td></tr> 1100</tbody></table> 1101</details> 1102</div> 1103<ul> 1104<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> 1105<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1106<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 1107<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> 1108</ul> 1109<p>Changes the ownership on a symbolic link.</p> 1110<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> 1111<div class="api_metadata"> 1112<span>Added in: v14.5.0, v12.19.0</span> 1113</div> 1114<ul> 1115<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> 1116<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> 1117<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> 1118<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> 1119</ul> 1120<p>Changes the access and modification times of a file in the same way as 1121<a href="#fs_fspromises_utimes_path_atime_mtime"><code>fsPromises.utimes()</code></a>, with the difference that if the path refers to a 1122symbolic link, then the link is not dereferenced: instead, the timestamps of 1123the symbolic link itself are changed.</p> 1124<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> 1125<div class="api_metadata"> 1126<span>Added in: v10.0.0</span> 1127</div> 1128<ul> 1129<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> 1130<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> 1131<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> 1132</ul> 1133<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 1134<a href="http://man7.org/linux/man-pages/man2/link.2.html"><code>link(2)</code></a> documentation for more detail.</p> 1135<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> 1136<div class="api_metadata"> 1137<details class="changelog"><summary>History</summary> 1138<table> 1139<tbody><tr><th>Version</th><th>Changes</th></tr> 1140<tr><td>v10.5.0</td> 1141<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1142<tr><td>v10.0.0</td> 1143<td><p><span>Added in: v10.0.0</span></p></td></tr> 1144</tbody></table> 1145</details> 1146</div> 1147<ul> 1148<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> 1149<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1150<ul> 1151<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 1152<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> 1153</ul> 1154</li> 1155<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 1156symbolic link <code>path</code>.</li> 1157</ul> 1158<p>Equivalent to <a href="#fs_fspromises_stat_path_options"><code>fsPromises.stat()</code></a> unless <code>path</code> refers to a symbolic link, 1159in which case the link itself is stat-ed, not the file that it refers to. 1160Refer 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> 1161<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> 1162<div class="api_metadata"> 1163<span>Added in: v10.0.0</span> 1164</div> 1165<ul> 1166<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> 1167<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> 1168<ul> 1169<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> 1170<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> 1171</ul> 1172</li> 1173<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> 1174is <code>false</code>, or the first directory path created if <code>recursive</code> is <code>true</code>.</li> 1175</ul> 1176<p>Asynchronously creates a directory.</p> 1177<p>The optional <code>options</code> argument can be an integer specifying <code>mode</code> (permission 1178and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code> 1179property indicating whether parent directories should be created. Calling 1180<code>fsPromises.mkdir()</code> when <code>path</code> is a directory that exists results in a 1181rejection only when <code>recursive</code> is false.</p> 1182<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> 1183<div class="api_metadata"> 1184<details class="changelog"><summary>History</summary> 1185<table> 1186<tbody><tr><th>Version</th><th>Changes</th></tr> 1187<tr><td>v14.18.0</td> 1188<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 1189<tr><td>v10.0.0</td> 1190<td><p><span>Added in: v10.0.0</span></p></td></tr> 1191</tbody></table> 1192</details> 1193</div> 1194<ul> 1195<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 1196<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> 1197<ul> 1198<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> 1199</ul> 1200</li> 1201<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 1202of the newly created temporary directory.</li> 1203</ul> 1204<p>Creates a unique temporary directory. A unique directory name is generated by 1205appending six random characters to the end of the provided <code>prefix</code>. Due to 1206platform inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some 1207platforms, notably the BSDs, can return more than six random characters, and 1208replace trailing <code>X</code> characters in <code>prefix</code> with random characters.</p> 1209<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1210object with an <code>encoding</code> property specifying the character encoding to use.</p> 1211<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>; 1212 1213<span class="hljs-keyword">try</span> { 1214 <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>)); 1215} <span class="hljs-keyword">catch</span> (err) { 1216 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1217}</code></pre> 1218<p>The <code>fsPromises.mkdtemp()</code> method will append the six randomly selected 1219characters directly to the <code>prefix</code> string. For instance, given a directory 1220<code>/tmp</code>, if the intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the 1221<code>prefix</code> must end with a trailing platform-specific path separator 1222(<code>require('path').sep</code>).</p> 1223<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> 1224<div class="api_metadata"> 1225<details class="changelog"><summary>History</summary> 1226<table> 1227<tbody><tr><th>Version</th><th>Changes</th></tr> 1228<tr><td>v11.1.0</td> 1229<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 1230<tr><td>v10.0.0</td> 1231<td><p><span>Added in: v10.0.0</span></p></td></tr> 1232</tbody></table> 1233</details> 1234</div> 1235<ul> 1236<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> 1237<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>. 1238<strong>Default:</strong> <code>'r'</code>.</li> 1239<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) 1240if the file is created. <strong>Default:</strong> <code>0o666</code> (readable and writable)</li> 1241<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> 1242</ul> 1243<p>Opens a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a>.</p> 1244<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> 1245<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented 1246by <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 1247a colon, Node.js will open a file system stream, as described by 1248<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p> 1249<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> 1250<div class="api_metadata"> 1251<details class="changelog"><summary>History</summary> 1252<table> 1253<tbody><tr><th>Version</th><th>Changes</th></tr> 1254<tr><td>v13.1.0, v12.16.0</td> 1255<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 1256<tr><td>v12.12.0</td> 1257<td><p><span>Added in: v12.12.0</span></p></td></tr> 1258</tbody></table> 1259</details> 1260</div> 1261<ul> 1262<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> 1263<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1264<ul> 1265<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> 1266<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 1267internally when reading from the directory. Higher values lead to better 1268performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 1269</ul> 1270</li> 1271<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> 1272</ul> 1273<p>Asynchronously open a directory for iterative scanning. See the POSIX 1274<a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a> documentation for more detail.</p> 1275<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 1276and cleaning up the directory.</p> 1277<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 1278directory and subsequent read operations.</p> 1279<p>Example using async iteration:</p> 1280<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>; 1281 1282<span class="hljs-keyword">try</span> { 1283 <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>); 1284 <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) 1285 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 1286} <span class="hljs-keyword">catch</span> (err) { 1287 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1288}</code></pre> 1289<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 1290closed after the iterator exits.</p> 1291<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> 1292<div class="api_metadata"> 1293<details class="changelog"><summary>History</summary> 1294<table> 1295<tbody><tr><th>Version</th><th>Changes</th></tr> 1296<tr><td>v10.11.0</td> 1297<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 1298<tr><td>v10.0.0</td> 1299<td><p><span>Added in: v10.0.0</span></p></td></tr> 1300</tbody></table> 1301</details> 1302</div> 1303<ul> 1304<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> 1305<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> 1306<ul> 1307<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> 1308<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> 1309</ul> 1310</li> 1311<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 1312the directory excluding <code>'.'</code> and <code>'..'</code>.</li> 1313</ul> 1314<p>Reads the contents of a directory.</p> 1315<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1316object with an <code>encoding</code> property specifying the character encoding to use for 1317the filenames. If the <code>encoding</code> is set to <code>'buffer'</code>, the filenames returned 1318will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 1319<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the resolved array will contain 1320<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 1321<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>; 1322 1323<span class="hljs-keyword">try</span> { 1324 <span class="hljs-keyword">const</span> files = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readdir</span>(path); 1325 <span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> file <span class="hljs-keyword">of</span> files) 1326 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(file); 1327} <span class="hljs-keyword">catch</span> (err) { 1328 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1329}</code></pre> 1330<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> 1331<div class="api_metadata"> 1332<details class="changelog"><summary>History</summary> 1333<table> 1334<tbody><tr><th>Version</th><th>Changes</th></tr> 1335<tr><td>v14.17.0</td> 1336<td><p>The options argument may include an AbortSignal to abort an ongoing readFile request.</p></td></tr> 1337<tr><td>v10.0.0</td> 1338<td><p><span>Added in: v10.0.0</span></p></td></tr> 1339</tbody></table> 1340</details> 1341</div> 1342<ul> 1343<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> 1344<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> 1345<ul> 1346<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> 1347<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> 1348<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 1349</ul> 1350</li> 1351<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> 1352</ul> 1353<p>Asynchronously reads the entire contents of a file.</p> 1354<p>If no encoding is specified (using <code>options.encoding</code>), the data is returned 1355as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object. Otherwise, the data will be a string.</p> 1356<p>If <code>options</code> is a string, then it specifies the encoding.</p> 1357<p>When the <code>path</code> is a directory, the behavior of <code>fsPromises.readFile()</code> is 1358platform-specific. On macOS, Linux, and Windows, the promise will be rejected 1359with an error. On FreeBSD, a representation of the directory's contents will be 1360returned.</p> 1361<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 1362request is aborted the promise returned is rejected with an <code>AbortError</code>:</p> 1363<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>; 1364 1365<span class="hljs-keyword">try</span> { 1366 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1367 <span class="hljs-keyword">const</span> { signal } = controller; 1368 <span class="hljs-keyword">const</span> promise = <span class="hljs-title function_">readFile</span>(fileName, { signal }); 1369 1370 <span class="hljs-comment">// Abort the request before the promise settles.</span> 1371 controller.<span class="hljs-title function_">abort</span>(); 1372 1373 <span class="hljs-keyword">await</span> promise; 1374} <span class="hljs-keyword">catch</span> (err) { 1375 <span class="hljs-comment">// When a request is aborted - err is an AbortError</span> 1376 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1377}</code></pre> 1378<p>Aborting an ongoing request does not abort individual operating 1379system requests but rather the internal buffering <code>fs.readFile</code> performs.</p> 1380<p>Any specified <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support reading.</p> 1381<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> 1382<div class="api_metadata"> 1383<span>Added in: v10.0.0</span> 1384</div> 1385<ul> 1386<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> 1387<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> 1388<ul> 1389<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> 1390</ul> 1391</li> 1392<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> 1393</ul> 1394<p>Reads the contents of the symbolic link referred to by <code>path</code>. See the POSIX 1395<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 1396<code>linkString</code> upon success.</p> 1397<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1398object with an <code>encoding</code> property specifying the character encoding to use for 1399the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, the link path 1400returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1401<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> 1402<div class="api_metadata"> 1403<span>Added in: v10.0.0</span> 1404</div> 1405<ul> 1406<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> 1407<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> 1408<ul> 1409<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> 1410</ul> 1411</li> 1412<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> 1413</ul> 1414<p>Determines the actual location of <code>path</code> using the same semantics as the 1415<code>fs.realpath.native()</code> function.</p> 1416<p>Only paths that can be converted to UTF8 strings are supported.</p> 1417<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 1418object with an <code>encoding</code> property specifying the character encoding to use for 1419the path. If the <code>encoding</code> is set to <code>'buffer'</code>, the path returned will be 1420passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 1421<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 1422be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 1423this restriction.</p> 1424<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> 1425<div class="api_metadata"> 1426<span>Added in: v10.0.0</span> 1427</div> 1428<ul> 1429<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> 1430<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> 1431<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> 1432</ul> 1433<p>Renames <code>oldPath</code> to <code>newPath</code>.</p> 1434<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> 1435<div class="api_metadata"> 1436<details class="changelog"><summary>History</summary> 1437<table> 1438<tbody><tr><th>Version</th><th>Changes</th></tr> 1439<tr><td>v14.14.0</td> 1440<td><p>The <code>recursive</code> option is deprecated, use <code>fsPromises.rm</code> instead.</p></td></tr> 1441<tr><td>v13.3.0, v12.16.0</td> 1442<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> 1443<tr><td>v12.10.0</td> 1444<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 1445<tr><td>v10.0.0</td> 1446<td><p><span>Added in: v10.0.0</span></p></td></tr> 1447</tbody></table> 1448</details> 1449</div> 1450<ul> 1451<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> 1452<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1453<ul> 1454<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 1455<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 1456backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1457represents the number of retries. This option is ignored if the <code>recursive</code> 1458option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1459<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 1460recursive mode, errors are not reported if <code>path</code> does not exist, and 1461operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1462<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 1463retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1464<strong>Default:</strong> <code>100</code>.</li> 1465</ul> 1466</li> 1467<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> 1468</ul> 1469<p>Removes the directory identified by <code>path</code>.</p> 1470<p>Using <code>fsPromises.rmdir()</code> on a file (not a directory) results in the 1471promise being rejected with an <code>ENOENT</code> error on Windows and an <code>ENOTDIR</code> 1472error on POSIX.</p> 1473<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 1474<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 1475that represent files will be deleted. The permissive behavior of the 1476<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 1477the future.</p> 1478<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> 1479<div class="api_metadata"> 1480<span>Added in: v14.14.0</span> 1481</div> 1482<ul> 1483<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> 1484<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1485<ul> 1486<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 1487not exist. <strong>Default:</strong> <code>false</code>.</li> 1488<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 1489<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 1490backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 1491represents the number of retries. This option is ignored if the <code>recursive</code> 1492option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 1493<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 1494recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 1495<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 1496retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 1497<strong>Default:</strong> <code>100</code>.</li> 1498</ul> 1499</li> 1500<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> 1501</ul> 1502<p>Removes files and directories (modeled on the standard POSIX <code>rm</code> utility).</p> 1503<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> 1504<div class="api_metadata"> 1505<details class="changelog"><summary>History</summary> 1506<table> 1507<tbody><tr><th>Version</th><th>Changes</th></tr> 1508<tr><td>v10.5.0</td> 1509<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 1510<tr><td>v10.0.0</td> 1511<td><p><span>Added in: v10.0.0</span></p></td></tr> 1512</tbody></table> 1513</details> 1514</div> 1515<ul> 1516<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> 1517<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 1518<ul> 1519<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 1520<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> 1521</ul> 1522</li> 1523<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 1524given <code>path</code>.</li> 1525</ul> 1526<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> 1527<div class="api_metadata"> 1528<span>Added in: v10.0.0</span> 1529</div> 1530<ul> 1531<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> 1532<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> 1533<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> 1534<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> 1535</ul> 1536<p>Creates a symbolic link.</p> 1537<p>The <code>type</code> argument is only used on Windows platforms and can be one of <code>'dir'</code>, 1538<code>'file'</code>, or <code>'junction'</code>. Windows junction points require the destination path 1539to be absolute. When using <code>'junction'</code>, the <code>target</code> argument will 1540automatically be normalized to absolute path.</p> 1541<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> 1542<div class="api_metadata"> 1543<span>Added in: v10.0.0</span> 1544</div> 1545<ul> 1546<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> 1547<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> 1548<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> 1549</ul> 1550<p>Truncates (shortens or extends the length) of the content at <code>path</code> to <code>len</code> 1551bytes.</p> 1552<h4><code>fsPromises.unlink(path)</code><span><a class="mark" href="#fs_fspromises_unlink_path" id="fs_fspromises_unlink_path">#</a></span></h4> 1553<div class="api_metadata"> 1554<span>Added in: v10.0.0</span> 1555</div> 1556<ul> 1557<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> 1558<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> 1559</ul> 1560<p>If <code>path</code> refers to a symbolic link, then the link is removed without affecting 1561the file or directory to which that link refers. If the <code>path</code> refers to a file 1562path 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> 1563documentation for more detail.</p> 1564<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> 1565<div class="api_metadata"> 1566<span>Added in: v10.0.0</span> 1567</div> 1568<ul> 1569<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> 1570<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> 1571<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> 1572<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> 1573</ul> 1574<p>Change the file system timestamps of the object referenced by <code>path</code>.</p> 1575<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p> 1576<ul> 1577<li>Values can be either numbers representing Unix epoch time, <code>Date</code>s, or a 1578numeric string like <code>'123456789.0'</code>.</li> 1579<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or 1580<code>-Infinity</code>, an <code>Error</code> will be thrown.</li> 1581</ul> 1582<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> 1583<div class="api_metadata"> 1584<span>Added in: v14.18.0</span> 1585</div> 1586<ul> 1587<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> 1588<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> 1589<ul> 1590<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 1591as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li> 1592<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 1593watched, or only the current directory. This applies when a directory is 1594specified, and only on supported platforms (See <a href="#fs_caveats">caveats</a>). <strong>Default:</strong> 1595<code>false</code>.</li> 1596<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 1597filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li> 1598<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 1599should stop.</li> 1600</ul> 1601</li> 1602<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> of objects with the properties: 1603<ul> 1604<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> 1605<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> 1606</ul> 1607</li> 1608</ul> 1609<p>Returns an async iterator that watches for changes on <code>filename</code>, where <code>filename</code> 1610is either a file or a directory.</p> 1611<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>); 1612 1613<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1614<span class="hljs-keyword">const</span> { signal } = ac; 1615<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>); 1616 1617(<span class="hljs-keyword">async</span> () => { 1618 <span class="hljs-keyword">try</span> { 1619 <span class="hljs-keyword">const</span> watcher = <span class="hljs-title function_">watch</span>(__filename, { signal }); 1620 <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) 1621 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event); 1622 } <span class="hljs-keyword">catch</span> (err) { 1623 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">name</span> === <span class="hljs-string">'AbortError'</span>) 1624 <span class="hljs-keyword">return</span>; 1625 <span class="hljs-keyword">throw</span> err; 1626 } 1627})();</code></pre> 1628<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or 1629disappears in the directory.</p> 1630<p>All the <a href="#fs_caveats">caveats</a> for <code>fs.watch()</code> also apply to <code>fsPromises.watch()</code>.</p> 1631<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> 1632<div class="api_metadata"> 1633<details class="changelog"><summary>History</summary> 1634<table> 1635<tbody><tr><th>Version</th><th>Changes</th></tr> 1636<tr><td>v14.18.0</td> 1637<td><p>The <code>data</code> argument supports <code>AsyncIterable</code>, <code>Iterable</code> and <code>Stream</code>.</p></td></tr> 1638<tr><td>v14.17.0</td> 1639<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 1640<tr><td>v14.0.0</td> 1641<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 1642<tr><td>v10.0.0</td> 1643<td><p><span>Added in: v10.0.0</span></p></td></tr> 1644</tbody></table> 1645</details> 1646</div> 1647<ul> 1648<li><code>file</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> | <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> filename or <code>FileHandle</code></li> 1649<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray" class="type"><TypedArray></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView" class="type"><DataView></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="stream.html#stream_stream" class="type"><Stream></a></li> 1650<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> 1651<ul> 1652<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> <strong>Default:</strong> <code>'utf8'</code></li> 1653<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> <strong>Default:</strong> <code>0o666</code></li> 1654<li><code>flag</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>. <strong>Default:</strong> <code>'w'</code>.</li> 1655<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 1656</ul> 1657</li> 1658<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills with <code>undefined</code> upon success.</li> 1659</ul> 1660<p>Asynchronously writes data to a file, replacing the file if it already exists. 1661<code>data</code> can be a string, a 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> 1662<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p> 1663<p>If <code>options</code> is a string, then it specifies the encoding.</p> 1664<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> 1665for more details.</p> 1666<p>Any specified <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> has to support writing.</p> 1667<p>It is unsafe to use <code>fsPromises.writeFile()</code> multiple times on the same file 1668without waiting for the promise to be settled.</p> 1669<p>Similarly to <code>fsPromises.readFile</code> - <code>fsPromises.writeFile</code> is a convenience 1670method that performs multiple <code>write</code> calls internally to write the buffer 1671passed to it. For performance sensitive code consider using 1672<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 1673<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>. 1674Cancelation is "best effort", and some amount of data is likely still 1675to be written.</p> 1676<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>; 1677 1678<span class="hljs-keyword">try</span> { 1679 <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 1680 <span class="hljs-keyword">const</span> { signal } = controller; 1681 <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>)); 1682 <span class="hljs-keyword">const</span> promise = <span class="hljs-title function_">writeFile</span>(<span class="hljs-string">'message.txt'</span>, data, { signal }); 1683 1684 <span class="hljs-comment">// Abort the request before the promise settles.</span> 1685 controller.<span class="hljs-title function_">abort</span>(); 1686 1687 <span class="hljs-keyword">await</span> promise; 1688} <span class="hljs-keyword">catch</span> (err) { 1689 <span class="hljs-comment">// When a request is aborted - err is an AbortError</span> 1690 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 1691}</code></pre> 1692<p>Aborting an ongoing request does not abort individual operating 1693system requests but rather the internal buffering <code>fs.writeFile</code> performs.</p> 1694</section><section><h3>Callback API<span><a class="mark" href="#fs_callback_api" id="fs_callback_api">#</a></span></h3> 1695<p>The callback APIs perform all operations asynchronously, without blocking the 1696event loop, then invoke a callback function upon completion or error.</p> 1697<p>The callback APIs use the underlying Node.js threadpool to perform file 1698system operations off the event loop thread. These operations are not 1699synchronized or threadsafe. Care must be taken when performing multiple 1700concurrent modifications on the same file or data corruption may occur.</p> 1701<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> 1702<div class="api_metadata"> 1703<details class="changelog"><summary>History</summary> 1704<table> 1705<tbody><tr><th>Version</th><th>Changes</th></tr> 1706<tr><td>v7.6.0</td> 1707<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 1708<tr><td>v6.3.0</td> 1709<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> 1710<tr><td>v0.11.15</td> 1711<td><p><span>Added in: v0.11.15</span></p></td></tr> 1712</tbody></table> 1713</details> 1714</div> 1715<ul> 1716<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> 1717<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> 1718<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1719<ul> 1720<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1721</ul> 1722</li> 1723</ul> 1724<p>Tests a user's permissions for the file or directory specified by <code>path</code>. 1725The <code>mode</code> argument is an optional integer that specifies the accessibility 1726checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for possible values 1727of <code>mode</code>. It is possible to create a mask consisting of the bitwise OR of 1728two or more values (e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 1729<p>The final argument, <code>callback</code>, is a callback function that is invoked with 1730a possible error argument. If any of the accessibility checks fail, the error 1731argument will be an <code>Error</code> object. The following examples check if 1732<code>package.json</code> exists, and if it is readable or writable.</p> 1733<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>; 1734 1735<span class="hljs-keyword">const</span> file = <span class="hljs-string">'package.json'</span>; 1736 1737<span class="hljs-comment">// Check if the file exists in the current directory.</span> 1738<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> { 1739 <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>); 1740}); 1741 1742<span class="hljs-comment">// Check if the file is readable.</span> 1743<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> { 1744 <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>); 1745}); 1746 1747<span class="hljs-comment">// Check if the file is writable.</span> 1748<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> { 1749 <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>); 1750}); 1751 1752<span class="hljs-comment">// Check if the file exists in the current directory, and if it is writable.</span> 1753<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> { 1754 <span class="hljs-keyword">if</span> (err) { 1755 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>( 1756 <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>); 1757 } <span class="hljs-keyword">else</span> { 1758 <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>); 1759 } 1760});</code></pre> 1761<p>Do not use <code>fs.access()</code> to check for the accessibility of a file before calling 1762<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code>. Doing 1763so introduces a race condition, since other processes may change the file's 1764state between the two calls. Instead, user code should open/read/write the 1765file directly and handle the error raised if the file is not accessible.</p> 1766<p><strong>write (NOT RECOMMENDED)</strong></p> 1767<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>; 1768 1769<span class="hljs-title function_">access</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1770 <span class="hljs-keyword">if</span> (!err) { 1771 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 1772 <span class="hljs-keyword">return</span>; 1773 } 1774 1775 <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> { 1776 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1777 1778 <span class="hljs-keyword">try</span> { 1779 <span class="hljs-title function_">writeMyData</span>(fd); 1780 } <span class="hljs-keyword">finally</span> { 1781 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1782 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1783 }); 1784 } 1785 }); 1786});</code></pre> 1787<p><strong>write (RECOMMENDED)</strong></p> 1788<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>; 1789 1790<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> { 1791 <span class="hljs-keyword">if</span> (err) { 1792 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'EEXIST'</span>) { 1793 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 1794 <span class="hljs-keyword">return</span>; 1795 } 1796 1797 <span class="hljs-keyword">throw</span> err; 1798 } 1799 1800 <span class="hljs-keyword">try</span> { 1801 <span class="hljs-title function_">writeMyData</span>(fd); 1802 } <span class="hljs-keyword">finally</span> { 1803 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1804 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1805 }); 1806 } 1807});</code></pre> 1808<p><strong>read (NOT RECOMMENDED)</strong></p> 1809<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>; 1810<span class="hljs-title function_">access</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1811 <span class="hljs-keyword">if</span> (err) { 1812 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 1813 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 1814 <span class="hljs-keyword">return</span>; 1815 } 1816 1817 <span class="hljs-keyword">throw</span> err; 1818 } 1819 1820 <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> { 1821 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1822 1823 <span class="hljs-keyword">try</span> { 1824 <span class="hljs-title function_">readMyData</span>(fd); 1825 } <span class="hljs-keyword">finally</span> { 1826 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1827 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1828 }); 1829 } 1830 }); 1831});</code></pre> 1832<p><strong>read (RECOMMENDED)</strong></p> 1833<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>; 1834 1835<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> { 1836 <span class="hljs-keyword">if</span> (err) { 1837 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 1838 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 1839 <span class="hljs-keyword">return</span>; 1840 } 1841 1842 <span class="hljs-keyword">throw</span> err; 1843 } 1844 1845 <span class="hljs-keyword">try</span> { 1846 <span class="hljs-title function_">readMyData</span>(fd); 1847 } <span class="hljs-keyword">finally</span> { 1848 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1849 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1850 }); 1851 } 1852});</code></pre> 1853<p>The "not recommended" examples above check for accessibility and then use the 1854file; the "recommended" examples are better because they use the file directly 1855and handle the error, if any.</p> 1856<p>In general, check for the accessibility of a file only if the file will not be 1857used directly, for example when its accessibility is a signal from another 1858process.</p> 1859<p>On Windows, access-control policies (ACLs) on a directory may limit access to 1860a file or directory. The <code>fs.access()</code> function, however, does not check the 1861ACL and therefore may report that a path is accessible even if the ACL restricts 1862the user from reading or writing to it.</p> 1863<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> 1864<div class="api_metadata"> 1865<details class="changelog"><summary>History</summary> 1866<table> 1867<tbody><tr><th>Version</th><th>Changes</th></tr> 1868<tr><td>v10.0.0</td> 1869<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> 1870<tr><td>v7.0.0</td> 1871<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> 1872<tr><td>v7.0.0</td> 1873<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 1874<tr><td>v5.0.0</td> 1875<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 1876<tr><td>v0.6.7</td> 1877<td><p><span>Added in: v0.6.7</span></p></td></tr> 1878</tbody></table> 1879</details> 1880</div> 1881<ul> 1882<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> 1883<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> 1884<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> 1885<ul> 1886<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> 1887<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> 1888<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> 1889</ul> 1890</li> 1891<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1892<ul> 1893<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1894</ul> 1895</li> 1896</ul> 1897<p>Asynchronously append data to a file, creating the file if it does not yet 1898exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 1899<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> 1900for more details.</p> 1901<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>; 1902 1903<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> { 1904 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1905 <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>); 1906});</code></pre> 1907<p>If <code>options</code> is a string, then it specifies the encoding:</p> 1908<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>; 1909 1910<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> 1911<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened 1912for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will 1913not be closed automatically.</p> 1914<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>; 1915 1916<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 1917 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 1918 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1919 }); 1920} 1921 1922<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> { 1923 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1924 1925 <span class="hljs-keyword">try</span> { 1926 <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> { 1927 <span class="hljs-title function_">closeFd</span>(fd); 1928 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1929 }); 1930 } <span class="hljs-keyword">catch</span> (err) { 1931 <span class="hljs-title function_">closeFd</span>(fd); 1932 <span class="hljs-keyword">throw</span> err; 1933 } 1934});</code></pre> 1935<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> 1936<div class="api_metadata"> 1937<details class="changelog"><summary>History</summary> 1938<table> 1939<tbody><tr><th>Version</th><th>Changes</th></tr> 1940<tr><td>v10.0.0</td> 1941<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> 1942<tr><td>v7.6.0</td> 1943<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 1944<tr><td>v7.0.0</td> 1945<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> 1946<tr><td>v0.1.30</td> 1947<td><p><span>Added in: v0.1.30</span></p></td></tr> 1948</tbody></table> 1949</details> 1950</div> 1951<ul> 1952<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> 1953<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> 1954<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 1955<ul> 1956<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 1957</ul> 1958</li> 1959</ul> 1960<p>Asynchronously changes the permissions of a file. No arguments other than a 1961possible exception are given to the completion callback.</p> 1962<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> 1963<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>; 1964 1965<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> { 1966 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 1967 <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>); 1968});</code></pre> 1969<h5>File modes<span><a class="mark" href="#fs_file_modes" id="fs_file_modes">#</a></span></h5> 1970<p>The <code>mode</code> argument used in both the <code>fs.chmod()</code> and <code>fs.chmodSync()</code> 1971methods is a numeric bitmask created using a logical OR of the following 1972constants:</p> 1973 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<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> 2029<p>An easier method of constructing the <code>mode</code> is to use a sequence of three 2030octal digits (e.g. <code>765</code>). The left-most digit (<code>7</code> in the example), specifies 2031the permissions for the file owner. The middle digit (<code>6</code> in the example), 2032specifies permissions for the group. The right-most digit (<code>5</code> in the example), 2033specifies the permissions for others.</p> 2034 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<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> 2076<p>For example, the octal value <code>0o765</code> means:</p> 2077<ul> 2078<li>The owner may read, write and execute the file.</li> 2079<li>The group may read and write the file.</li> 2080<li>Others may read and execute the file.</li> 2081</ul> 2082<p>When using raw numbers where file modes are expected, any value larger than 2083<code>0o777</code> may result in platform-specific behaviors that are not supported to work 2084consistently. Therefore constants like <code>S_ISVTX</code>, <code>S_ISGID</code> or <code>S_ISUID</code> are not 2085exposed in <code>fs.constants</code>.</p> 2086<p>Caveats: on Windows only the write permission can be changed, and the 2087distinction among the permissions of group, owner or others is not 2088implemented.</p> 2089<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> 2090<div class="api_metadata"> 2091<details class="changelog"><summary>History</summary> 2092<table> 2093<tbody><tr><th>Version</th><th>Changes</th></tr> 2094<tr><td>v10.0.0</td> 2095<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> 2096<tr><td>v7.6.0</td> 2097<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2098<tr><td>v7.0.0</td> 2099<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> 2100<tr><td>v0.1.97</td> 2101<td><p><span>Added in: v0.1.97</span></p></td></tr> 2102</tbody></table> 2103</details> 2104</div> 2105<ul> 2106<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> 2107<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2108<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2109<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2110<ul> 2111<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2112</ul> 2113</li> 2114</ul> 2115<p>Asynchronously changes owner and group of a file. No arguments other than a 2116possible exception are given to the completion callback.</p> 2117<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> 2118<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> 2119<div class="api_metadata"> 2120<details class="changelog"><summary>History</summary> 2121<table> 2122<tbody><tr><th>Version</th><th>Changes</th></tr> 2123<tr><td>v14.17.0</td> 2124<td><p>A default callback is now used if one is not provided.</p></td></tr> 2125<tr><td>v10.0.0</td> 2126<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> 2127<tr><td>v7.0.0</td> 2128<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> 2129<tr><td>v0.0.2</td> 2130<td><p><span>Added in: v0.0.2</span></p></td></tr> 2131</tbody></table> 2132</details> 2133</div> 2134<ul> 2135<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2136<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2137<ul> 2138<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2139</ul> 2140</li> 2141</ul> 2142<p>Closes the file descriptor. No arguments other than a possible exception are 2143given to the completion callback.</p> 2144<p>Calling <code>fs.close()</code> on any file descriptor (<code>fd</code>) that is currently in use 2145through any other <code>fs</code> operation may lead to undefined behavior.</p> 2146<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> 2147<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> 2148<div class="api_metadata"> 2149<details class="changelog"><summary>History</summary> 2150<table> 2151<tbody><tr><th>Version</th><th>Changes</th></tr> 2152<tr><td>v14.0.0</td> 2153<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 2154<tr><td>v8.5.0</td> 2155<td><p><span>Added in: v8.5.0</span></p></td></tr> 2156</tbody></table> 2157</details> 2158</div> 2159<ul> 2160<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> 2161<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> 2162<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> 2163<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 2164</ul> 2165<p>Asynchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 2166already exists. No arguments other than a possible exception are given to the 2167callback function. Node.js makes no guarantees about the atomicity of the copy 2168operation. If an error occurs after the destination file has been opened for 2169writing, Node.js will attempt to remove the destination.</p> 2170<p><code>mode</code> is an optional integer that specifies the behavior 2171of the copy operation. It is possible to create a mask consisting of the bitwise 2172OR of two or more values (e.g. 2173<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p> 2174<ul> 2175<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already 2176exists.</li> 2177<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a 2178copy-on-write reflink. If the platform does not support copy-on-write, then a 2179fallback copy mechanism is used.</li> 2180<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 2181create a copy-on-write reflink. If the platform does not support 2182copy-on-write, then the operation will fail.</li> 2183</ul> 2184<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>; 2185 2186<span class="hljs-keyword">function</span> <span class="hljs-title function_">callback</span>(<span class="hljs-params">err</span>) { 2187 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2188 <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>); 2189} 2190 2191<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span> 2192<span class="hljs-title function_">copyFile</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>, callback); 2193 2194<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 2195<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> 2196<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> 2197<div class="api_metadata"> 2198<details class="changelog"><summary>History</summary> 2199<table> 2200<tbody><tr><th>Version</th><th>Changes</th></tr> 2201<tr><td>v14.0.0</td> 2202<td><p>Change <code>emitClose</code> default to <code>true</code>.</p></td></tr> 2203<tr><td>v13.6.0, v12.17.0</td> 2204<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr> 2205<tr><td>v12.10.0</td> 2206<td><p>Enable <code>emitClose</code> option.</p></td></tr> 2207<tr><td>v11.0.0</td> 2208<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> 2209<tr><td>v7.6.0</td> 2210<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2211<tr><td>v7.0.0</td> 2212<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 2213<tr><td>v2.3.0</td> 2214<td><p>The passed <code>options</code> object can be a string now.</p></td></tr> 2215<tr><td>v0.1.31</td> 2216<td><p><span>Added in: v0.1.31</span></p></td></tr> 2217</tbody></table> 2218</details> 2219</div> 2220<ul> 2221<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> 2222<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> 2223<ul> 2224<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> 2225<code>'r'</code>.</li> 2226<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> 2227<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> 2228<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> 2229<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> 2230<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> 2231<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2232<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> 2233<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> 2234<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> 2235</ul> 2236</li> 2237<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> 2238</ul> 2239<p>Unlike the 16 kb default <code>highWaterMark</code> for a readable stream, the stream 2240returned by this method has a default <code>highWaterMark</code> of 64 kb.</p> 2241<p><code>options</code> can include <code>start</code> and <code>end</code> values to read a range of bytes from 2242the file instead of the entire file. Both <code>start</code> and <code>end</code> are inclusive and 2243start counting at 0, allowed values are in the 2244[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 2245omitted or <code>undefined</code>, <code>fs.createReadStream()</code> reads sequentially from the 2246current file position. The <code>encoding</code> can be any one of those accepted by 2247<a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 2248<p>If <code>fd</code> is specified, <code>ReadStream</code> will ignore the <code>path</code> argument and will use 2249the specified file descriptor. This means that no <code>'open'</code> event will be 2250emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s should be passed to 2251<a href="net.html#net_class_net_socket" class="type"><net.Socket></a>.</p> 2252<p>If <code>fd</code> points to a character device that only supports blocking reads 2253(such as keyboard or sound card), read operations do not finish until data is 2254available. This can prevent the process from exiting and the stream from 2255closing naturally.</p> 2256<p>By default, the stream will emit a <code>'close'</code> event after it has been 2257destroyed, like most <code>Readable</code> streams. Set the <code>emitClose</code> option to 2258<code>false</code> to change this behavior.</p> 2259<p>By providing the <code>fs</code> option, it is possible to override the corresponding <code>fs</code> 2260implementations for <code>open</code>, <code>read</code>, and <code>close</code>. When providing the <code>fs</code> option, 2261overrides for <code>open</code>, <code>read</code>, and <code>close</code> are required.</p> 2262<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>; 2263 2264<span class="hljs-comment">// Create a stream from some character device.</span> 2265<span class="hljs-keyword">const</span> stream = <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'/dev/input/event0'</span>); 2266<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> { 2267 stream.<span class="hljs-title function_">close</span>(); <span class="hljs-comment">// This may not close the stream.</span> 2268 <span class="hljs-comment">// Artificially marking end-of-stream, as if the underlying resource had</span> 2269 <span class="hljs-comment">// indicated end-of-file by itself, allows the stream to close.</span> 2270 <span class="hljs-comment">// This does not cancel pending read operations, and if there is such an</span> 2271 <span class="hljs-comment">// operation, the process may still not be able to exit successfully</span> 2272 <span class="hljs-comment">// until it finishes.</span> 2273 stream.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 2274 stream.<span class="hljs-title function_">read</span>(<span class="hljs-number">0</span>); 2275}, <span class="hljs-number">100</span>);</code></pre> 2276<p>If <code>autoClose</code> is false, then the file descriptor won't be closed, even if 2277there's an error. It is the application's responsibility to close it and make 2278sure there's no file descriptor leak. If <code>autoClose</code> is set to true (default 2279behavior), on <code>'error'</code> or <code>'end'</code> the file descriptor will be closed 2280automatically.</p> 2281<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the 2282file was created.</p> 2283<p>An example to read the last 10 bytes of a file which is 100 bytes long:</p> 2284<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>; 2285 2286<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> 2287<p>If <code>options</code> is a string, then it specifies the encoding.</p> 2288<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> 2289<div class="api_metadata"> 2290<details class="changelog"><summary>History</summary> 2291<table> 2292<tbody><tr><th>Version</th><th>Changes</th></tr> 2293<tr><td>v14.0.0</td> 2294<td><p>Change <code>emitClose</code> default to <code>true</code>.</p></td></tr> 2295<tr><td>v13.6.0, v12.17.0</td> 2296<td><p>The <code>fs</code> options allow overriding the used <code>fs</code> implementation.</p></td></tr> 2297<tr><td>v12.10.0</td> 2298<td><p>Enable <code>emitClose</code> option.</p></td></tr> 2299<tr><td>v7.6.0</td> 2300<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2301<tr><td>v7.0.0</td> 2302<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 2303<tr><td>v5.5.0</td> 2304<td><p>The <code>autoClose</code> option is supported now.</p></td></tr> 2305<tr><td>v2.3.0</td> 2306<td><p>The passed <code>options</code> object can be a string now.</p></td></tr> 2307<tr><td>v0.1.31</td> 2308<td><p><span>Added in: v0.1.31</span></p></td></tr> 2309</tbody></table> 2310</details> 2311</div> 2312<ul> 2313<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> 2314<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> 2315<ul> 2316<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> 2317<code>'w'</code>.</li> 2318<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> 2319<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> 2320<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> 2321<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> 2322<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> 2323<li><code>start</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2324<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> 2325</ul> 2326</li> 2327<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> 2328</ul> 2329<p><code>options</code> may also include a <code>start</code> option to allow writing data at some 2330position past the beginning of the file, allowed values are in the 2331[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 2332it may require the <code>flags</code> option to be set to <code>r+</code> rather than the default <code>w</code>. 2333The <code>encoding</code> can be any one of those accepted by <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 2334<p>If <code>autoClose</code> is set to true (default behavior) on <code>'error'</code> or <code>'finish'</code> 2335the file descriptor will be closed automatically. If <code>autoClose</code> is false, 2336then the file descriptor won't be closed, even if there's an error. 2337It is the application's responsibility to close it and make sure there's no 2338file descriptor leak.</p> 2339<p>By default, the stream will emit a <code>'close'</code> event after it has been 2340destroyed, like most <code>Writable</code> streams. Set the <code>emitClose</code> option to 2341<code>false</code> to change this behavior.</p> 2342<p>By providing the <code>fs</code> option it is possible to override the corresponding <code>fs</code> 2343implementations for <code>open</code>, <code>write</code>, <code>writev</code> and <code>close</code>. Overriding <code>write()</code> 2344without <code>writev()</code> can reduce performance as some optimizations (<code>_writev()</code>) 2345will be disabled. When providing the <code>fs</code> option, overrides for <code>open</code>, 2346<code>close</code>, and at least one of <code>write</code> and <code>writev</code> are required.</p> 2347<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 2348<code>path</code> argument and will use the specified file descriptor. This means that no 2349<code>'open'</code> event will be emitted. <code>fd</code> should be blocking; non-blocking <code>fd</code>s 2350should be passed to <a href="net.html#net_class_net_socket" class="type"><net.Socket></a>.</p> 2351<p>If <code>options</code> is a string, then it specifies the encoding.</p> 2352<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> 2353<div class="api_metadata"> 2354<details class="changelog"><summary>History</summary> 2355<table> 2356<tbody><tr><th>Version</th><th>Changes</th></tr> 2357<tr><td>v7.6.0</td> 2358<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2359<tr><td>v1.0.0</td> 2360<td><p><span>Deprecated since: v1.0.0</span></p></td></tr> 2361<tr><td>v0.0.2</td> 2362<td><p><span>Added in: v0.0.2</span></p></td></tr> 2363</tbody></table> 2364</details> 2365</div> 2366<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> 2367<ul> 2368<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> 2369<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2370<ul> 2371<li><code>exists</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 2372</ul> 2373</li> 2374</ul> 2375<p>Test whether or not the given path exists by checking with the file system. 2376Then call the <code>callback</code> argument with either true or false:</p> 2377<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>; 2378 2379<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> { 2380 <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>); 2381});</code></pre> 2382<p><strong>The parameters for this callback are not consistent with other Node.js 2383callbacks.</strong> Normally, the first parameter to a Node.js callback is an <code>err</code> 2384parameter, optionally followed by other parameters. The <code>fs.exists()</code> callback 2385has only one boolean parameter. This is one reason <code>fs.access()</code> is recommended 2386instead of <code>fs.exists()</code>.</p> 2387<p>Using <code>fs.exists()</code> to check for the existence of a file before calling 2388<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended. Doing 2389so introduces a race condition, since other processes may change the file's 2390state between the two calls. Instead, user code should open/read/write the 2391file directly and handle the error raised if the file does not exist.</p> 2392<p><strong>write (NOT RECOMMENDED)</strong></p> 2393<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>; 2394 2395<span class="hljs-title function_">exists</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> { 2396 <span class="hljs-keyword">if</span> (e) { 2397 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 2398 } <span class="hljs-keyword">else</span> { 2399 <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> { 2400 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2401 2402 <span class="hljs-keyword">try</span> { 2403 <span class="hljs-title function_">writeMyData</span>(fd); 2404 } <span class="hljs-keyword">finally</span> { 2405 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2406 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2407 }); 2408 } 2409 }); 2410 } 2411});</code></pre> 2412<p><strong>write (RECOMMENDED)</strong></p> 2413<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>; 2414<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> { 2415 <span class="hljs-keyword">if</span> (err) { 2416 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'EEXIST'</span>) { 2417 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile already exists'</span>); 2418 <span class="hljs-keyword">return</span>; 2419 } 2420 2421 <span class="hljs-keyword">throw</span> err; 2422 } 2423 2424 <span class="hljs-keyword">try</span> { 2425 <span class="hljs-title function_">writeMyData</span>(fd); 2426 } <span class="hljs-keyword">finally</span> { 2427 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2428 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2429 }); 2430 } 2431});</code></pre> 2432<p><strong>read (NOT RECOMMENDED)</strong></p> 2433<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>; 2434 2435<span class="hljs-title function_">exists</span>(<span class="hljs-string">'myfile'</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =></span> { 2436 <span class="hljs-keyword">if</span> (e) { 2437 <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> { 2438 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2439 2440 <span class="hljs-keyword">try</span> { 2441 <span class="hljs-title function_">readMyData</span>(fd); 2442 } <span class="hljs-keyword">finally</span> { 2443 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2444 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2445 }); 2446 } 2447 }); 2448 } <span class="hljs-keyword">else</span> { 2449 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 2450 } 2451});</code></pre> 2452<p><strong>read (RECOMMENDED)</strong></p> 2453<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>; 2454 2455<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> { 2456 <span class="hljs-keyword">if</span> (err) { 2457 <span class="hljs-keyword">if</span> (err.<span class="hljs-property">code</span> === <span class="hljs-string">'ENOENT'</span>) { 2458 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'myfile does not exist'</span>); 2459 <span class="hljs-keyword">return</span>; 2460 } 2461 2462 <span class="hljs-keyword">throw</span> err; 2463 } 2464 2465 <span class="hljs-keyword">try</span> { 2466 <span class="hljs-title function_">readMyData</span>(fd); 2467 } <span class="hljs-keyword">finally</span> { 2468 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2469 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2470 }); 2471 } 2472});</code></pre> 2473<p>The "not recommended" examples above check for existence and then use the 2474file; the "recommended" examples are better because they use the file directly 2475and handle the error, if any.</p> 2476<p>In general, check for the existence of a file only if the file won’t be 2477used directly, for example when its existence is a signal from another 2478process.</p> 2479<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> 2480<div class="api_metadata"> 2481<details class="changelog"><summary>History</summary> 2482<table> 2483<tbody><tr><th>Version</th><th>Changes</th></tr> 2484<tr><td>v10.0.0</td> 2485<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> 2486<tr><td>v7.0.0</td> 2487<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> 2488<tr><td>v0.4.7</td> 2489<td><p><span>Added in: v0.4.7</span></p></td></tr> 2490</tbody></table> 2491</details> 2492</div> 2493<ul> 2494<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2495<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> 2496<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2497<ul> 2498<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2499</ul> 2500</li> 2501</ul> 2502<p>Sets the permissions on the file. No arguments other than a possible exception 2503are given to the completion callback.</p> 2504<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> 2505<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> 2506<div class="api_metadata"> 2507<details class="changelog"><summary>History</summary> 2508<table> 2509<tbody><tr><th>Version</th><th>Changes</th></tr> 2510<tr><td>v10.0.0</td> 2511<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> 2512<tr><td>v7.0.0</td> 2513<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> 2514<tr><td>v0.4.7</td> 2515<td><p><span>Added in: v0.4.7</span></p></td></tr> 2516</tbody></table> 2517</details> 2518</div> 2519<ul> 2520<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2521<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2522<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2523<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2524<ul> 2525<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2526</ul> 2527</li> 2528</ul> 2529<p>Sets the owner of the file. No arguments other than a possible exception are 2530given to the completion callback.</p> 2531<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> 2532<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> 2533<div class="api_metadata"> 2534<details class="changelog"><summary>History</summary> 2535<table> 2536<tbody><tr><th>Version</th><th>Changes</th></tr> 2537<tr><td>v10.0.0</td> 2538<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> 2539<tr><td>v7.0.0</td> 2540<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> 2541<tr><td>v0.1.96</td> 2542<td><p><span>Added in: v0.1.96</span></p></td></tr> 2543</tbody></table> 2544</details> 2545</div> 2546<ul> 2547<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2548<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2549<ul> 2550<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2551</ul> 2552</li> 2553</ul> 2554<p>Forces all currently queued I/O operations associated with the file to the 2555operating system's synchronized I/O completion state. Refer to the POSIX 2556<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 2557exception are given to the completion callback.</p> 2558<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> 2559<div class="api_metadata"> 2560<details class="changelog"><summary>History</summary> 2561<table> 2562<tbody><tr><th>Version</th><th>Changes</th></tr> 2563<tr><td>v10.5.0</td> 2564<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 2565<tr><td>v10.0.0</td> 2566<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> 2567<tr><td>v7.0.0</td> 2568<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> 2569<tr><td>v0.1.95</td> 2570<td><p><span>Added in: v0.1.95</span></p></td></tr> 2571</tbody></table> 2572</details> 2573</div> 2574<ul> 2575<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2576<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 2577<ul> 2578<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 2579<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> 2580</ul> 2581</li> 2582<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2583<ul> 2584<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2585<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 2586</ul> 2587</li> 2588</ul> 2589<p>Invokes the callback with the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file descriptor.</p> 2590<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> 2591<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> 2592<div class="api_metadata"> 2593<details class="changelog"><summary>History</summary> 2594<table> 2595<tbody><tr><th>Version</th><th>Changes</th></tr> 2596<tr><td>v10.0.0</td> 2597<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> 2598<tr><td>v7.0.0</td> 2599<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> 2600<tr><td>v0.1.96</td> 2601<td><p><span>Added in: v0.1.96</span></p></td></tr> 2602</tbody></table> 2603</details> 2604</div> 2605<ul> 2606<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2607<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2608<ul> 2609<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2610</ul> 2611</li> 2612</ul> 2613<p>Request that all data for the open file descriptor is flushed to the storage 2614device. The specific implementation is operating system and device specific. 2615Refer 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 2616than a possible exception are given to the completion callback.</p> 2617<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> 2618<div class="api_metadata"> 2619<details class="changelog"><summary>History</summary> 2620<table> 2621<tbody><tr><th>Version</th><th>Changes</th></tr> 2622<tr><td>v10.0.0</td> 2623<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> 2624<tr><td>v7.0.0</td> 2625<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> 2626<tr><td>v0.8.6</td> 2627<td><p><span>Added in: v0.8.6</span></p></td></tr> 2628</tbody></table> 2629</details> 2630</div> 2631<ul> 2632<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2633<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> 2634<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2635<ul> 2636<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2637</ul> 2638</li> 2639</ul> 2640<p>Truncates the file descriptor. No arguments other than a possible exception are 2641given to the completion callback.</p> 2642<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> 2643<p>If the file referred to by the file descriptor was larger than <code>len</code> bytes, only 2644the first <code>len</code> bytes will be retained in the file.</p> 2645<p>For example, the following program retains only the first four bytes of the 2646file:</p> 2647<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>; 2648 2649<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 2650 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 2651 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2652 }); 2653} 2654 2655<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> { 2656 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2657 2658 <span class="hljs-keyword">try</span> { 2659 <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> { 2660 <span class="hljs-title function_">closeFd</span>(fd); 2661 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2662 }); 2663 } <span class="hljs-keyword">catch</span> (err) { 2664 <span class="hljs-title function_">closeFd</span>(fd); 2665 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2666 } 2667});</code></pre> 2668<p>If the file previously was shorter than <code>len</code> bytes, it is extended, and the 2669extended part is filled with null bytes (<code>'\0'</code>):</p> 2670<p>If <code>len</code> is negative then <code>0</code> will be used.</p> 2671<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> 2672<div class="api_metadata"> 2673<details class="changelog"><summary>History</summary> 2674<table> 2675<tbody><tr><th>Version</th><th>Changes</th></tr> 2676<tr><td>v10.0.0</td> 2677<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> 2678<tr><td>v7.0.0</td> 2679<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> 2680<tr><td>v4.1.0</td> 2681<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 2682<tr><td>v0.4.2</td> 2683<td><p><span>Added in: v0.4.2</span></p></td></tr> 2684</tbody></table> 2685</details> 2686</div> 2687<ul> 2688<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2689<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> 2690<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> 2691<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2692<ul> 2693<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2694</ul> 2695</li> 2696</ul> 2697<p>Change the file system timestamps of the object referenced by the supplied file 2698descriptor. See <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p> 2699<p>This function does not work on AIX versions before 7.1, it will return the 2700error <code>UV_ENOSYS</code>.</p> 2701<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> 2702<div class="api_metadata"> 2703<details class="changelog"><summary>History</summary> 2704<table> 2705<tbody><tr><th>Version</th><th>Changes</th></tr> 2706<tr><td>v10.0.0</td> 2707<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> 2708<tr><td>v7.0.0</td> 2709<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> 2710<tr><td>v0.4.7</td> 2711<td><p><span>Deprecated since: v0.4.7</span></p></td></tr> 2712</tbody></table> 2713</details> 2714</div> 2715<ul> 2716<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> 2717<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2718<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2719<ul> 2720<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2721</ul> 2722</li> 2723</ul> 2724<p>Changes the permissions on a symbolic link. No arguments other than a possible 2725exception are given to the completion callback.</p> 2726<p>This method is only implemented on macOS.</p> 2727<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> 2728<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> 2729<div class="api_metadata"> 2730<details class="changelog"><summary>History</summary> 2731<table> 2732<tbody><tr><th>Version</th><th>Changes</th></tr> 2733<tr><td>v10.6.0</td> 2734<td><p>This API is no longer deprecated.</p></td></tr> 2735<tr><td>v10.0.0</td> 2736<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> 2737<tr><td>v7.0.0</td> 2738<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> 2739<tr><td>v0.4.7</td> 2740<td><p>Documentation-only deprecation.</p></td></tr> 2741</tbody></table> 2742</details> 2743</div> 2744<ul> 2745<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> 2746<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2747<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 2748<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2749<ul> 2750<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2751</ul> 2752</li> 2753</ul> 2754<p>Set the owner of the symbolic link. No arguments other than a possible 2755exception are given to the completion callback.</p> 2756<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> 2757<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> 2758<div class="api_metadata"> 2759<span>Added in: v14.5.0, v12.19.0</span> 2760</div> 2761<ul> 2762<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> 2763<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> 2764<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> 2765<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2766<ul> 2767<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2768</ul> 2769</li> 2770</ul> 2771<p>Changes the access and modification times of a file in the same way as 2772<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 2773link, then the link is not dereferenced: instead, the timestamps of the 2774symbolic link itself are changed.</p> 2775<p>No arguments other than a possible exception are given to the completion 2776callback.</p> 2777<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> 2778<div class="api_metadata"> 2779<details class="changelog"><summary>History</summary> 2780<table> 2781<tbody><tr><th>Version</th><th>Changes</th></tr> 2782<tr><td>v10.0.0</td> 2783<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> 2784<tr><td>v7.6.0</td> 2785<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> 2786<tr><td>v7.0.0</td> 2787<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> 2788<tr><td>v0.1.31</td> 2789<td><p><span>Added in: v0.1.31</span></p></td></tr> 2790</tbody></table> 2791</details> 2792</div> 2793<ul> 2794<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> 2795<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> 2796<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2797<ul> 2798<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2799</ul> 2800</li> 2801</ul> 2802<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 2803<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 2804exception are given to the completion callback.</p> 2805<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> 2806<div class="api_metadata"> 2807<details class="changelog"><summary>History</summary> 2808<table> 2809<tbody><tr><th>Version</th><th>Changes</th></tr> 2810<tr><td>v10.5.0</td> 2811<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 2812<tr><td>v10.0.0</td> 2813<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> 2814<tr><td>v7.6.0</td> 2815<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2816<tr><td>v7.0.0</td> 2817<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> 2818<tr><td>v0.1.30</td> 2819<td><p><span>Added in: v0.1.30</span></p></td></tr> 2820</tbody></table> 2821</details> 2822</div> 2823<ul> 2824<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> 2825<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 2826<ul> 2827<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 2828<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> 2829</ul> 2830</li> 2831<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2832<ul> 2833<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2834<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 2835</ul> 2836</li> 2837</ul> 2838<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. 2839The 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> 2840object. <code>lstat()</code> is identical to <code>stat()</code>, except that if <code>path</code> is a symbolic 2841link, then the link itself is stat-ed, not the file that it refers to.</p> 2842<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> 2843<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> 2844<div class="api_metadata"> 2845<details class="changelog"><summary>History</summary> 2846<table> 2847<tbody><tr><th>Version</th><th>Changes</th></tr> 2848<tr><td>v13.11.0, v12.17.0</td> 2849<td><p>In <code>recursive</code> mode, the callback now receives the first created path as an argument.</p></td></tr> 2850<tr><td>v10.12.0</td> 2851<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> 2852<tr><td>v10.0.0</td> 2853<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> 2854<tr><td>v7.6.0</td> 2855<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2856<tr><td>v7.0.0</td> 2857<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> 2858<tr><td>v0.1.8</td> 2859<td><p><span>Added in: v0.1.8</span></p></td></tr> 2860</tbody></table> 2861</details> 2862</div> 2863<ul> 2864<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> 2865<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> 2866<ul> 2867<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> 2868<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> 2869</ul> 2870</li> 2871<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2872<ul> 2873<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2874</ul> 2875</li> 2876</ul> 2877<p>Asynchronously creates a directory.</p> 2878<p>The callback is given a possible exception and, if <code>recursive</code> is <code>true</code>, the 2879first directory path created, <code>(err, [path])</code>. 2880<code>path</code> can still be <code>undefined</code> when <code>recursive</code> is <code>true</code>, if no directory was 2881created.</p> 2882<p>The optional <code>options</code> argument can be an integer specifying <code>mode</code> (permission 2883and sticky bits), or an object with a <code>mode</code> property and a <code>recursive</code> 2884property indicating whether parent directories should be created. Calling 2885<code>fs.mkdir()</code> when <code>path</code> is a directory that exists results in an error only 2886when <code>recursive</code> is false.</p> 2887<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>; 2888 2889<span class="hljs-comment">// Creates /tmp/a/apple, regardless of whether `/tmp` and /tmp/a exist.</span> 2890<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> { 2891 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2892});</code></pre> 2893<p>On Windows, using <code>fs.mkdir()</code> on the root directory even with recursion will 2894result in an error:</p> 2895<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>; 2896 2897<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> { 2898 <span class="hljs-comment">// => [Error: EPERM: operation not permitted, mkdir 'C:\']</span> 2899});</code></pre> 2900<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> 2901<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> 2902<div class="api_metadata"> 2903<details class="changelog"><summary>History</summary> 2904<table> 2905<tbody><tr><th>Version</th><th>Changes</th></tr> 2906<tr><td>v14.18.0</td> 2907<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 2908<tr><td>v10.0.0</td> 2909<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> 2910<tr><td>v7.0.0</td> 2911<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> 2912<tr><td>v6.2.1</td> 2913<td><p>The <code>callback</code> parameter is optional now.</p></td></tr> 2914<tr><td>v5.10.0</td> 2915<td><p><span>Added in: v5.10.0</span></p></td></tr> 2916</tbody></table> 2917</details> 2918</div> 2919<ul> 2920<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 2921<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> 2922<ul> 2923<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> 2924</ul> 2925</li> 2926<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 2927<ul> 2928<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 2929<li><code>directory</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 2930</ul> 2931</li> 2932</ul> 2933<p>Creates a unique temporary directory.</p> 2934<p>Generates six random characters to be appended behind a required 2935<code>prefix</code> to create a unique temporary directory. Due to platform 2936inconsistencies, avoid trailing <code>X</code> characters in <code>prefix</code>. Some platforms, 2937notably the BSDs, can return more than six random characters, and replace 2938trailing <code>X</code> characters in <code>prefix</code> with random characters.</p> 2939<p>The created directory path is passed as a string to the callback's second 2940parameter.</p> 2941<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 2942object with an <code>encoding</code> property specifying the character encoding to use.</p> 2943<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>; 2944 2945<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> { 2946 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2947 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2948 <span class="hljs-comment">// Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2</span> 2949});</code></pre> 2950<p>The <code>fs.mkdtemp()</code> method will append the six randomly selected characters 2951directly to the <code>prefix</code> string. For instance, given a directory <code>/tmp</code>, if the 2952intention is to create a temporary directory <em>within</em> <code>/tmp</code>, the <code>prefix</code> 2953must end with a trailing platform-specific path separator 2954(<code>require('path').sep</code>).</p> 2955<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>; 2956<span class="hljs-keyword">import</span> { mkdtemp } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs'</span>; 2957 2958<span class="hljs-comment">// The parent directory for the new temporary directory</span> 2959<span class="hljs-keyword">const</span> tmpDir = <span class="hljs-title function_">tmpdir</span>(); 2960 2961<span class="hljs-comment">// This method is *INCORRECT*:</span> 2962<span class="hljs-title function_">mkdtemp</span>(tmpDir, <span class="hljs-function">(<span class="hljs-params">err, directory</span>) =></span> { 2963 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2964 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2965 <span class="hljs-comment">// Will print something similar to `/tmpabc123`.</span> 2966 <span class="hljs-comment">// A new temporary directory is created at the file system root</span> 2967 <span class="hljs-comment">// rather than *within* the /tmp directory.</span> 2968}); 2969 2970<span class="hljs-comment">// This method is *CORRECT*:</span> 2971<span class="hljs-keyword">import</span> { sep } <span class="hljs-keyword">from</span> <span class="hljs-string">'path'</span>; 2972<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> { 2973 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 2974 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(directory); 2975 <span class="hljs-comment">// Will print something similar to `/tmp/abc123`.</span> 2976 <span class="hljs-comment">// A new temporary directory is created within</span> 2977 <span class="hljs-comment">// the /tmp directory.</span> 2978});</code></pre> 2979<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> 2980<div class="api_metadata"> 2981<details class="changelog"><summary>History</summary> 2982<table> 2983<tbody><tr><th>Version</th><th>Changes</th></tr> 2984<tr><td>v11.1.0</td> 2985<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 2986<tr><td>v9.9.0</td> 2987<td><p>The <code>as</code> and <code>as+</code> flags are supported now.</p></td></tr> 2988<tr><td>v7.6.0</td> 2989<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 2990<tr><td>v0.0.2</td> 2991<td><p><span>Added in: v0.0.2</span></p></td></tr> 2992</tbody></table> 2993</details> 2994</div> 2995<ul> 2996<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> 2997<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>. 2998<strong>Default:</strong> <code>'r'</code>.</li> 2999<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> 3000<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3001<ul> 3002<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3003<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3004</ul> 3005</li> 3006</ul> 3007<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> 3008<p><code>mode</code> sets the file mode (permission and sticky bits), but only if the file was 3009created. On Windows, only the write permission can be manipulated; see 3010<a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p> 3011<p>The callback gets two arguments <code>(err, fd)</code>.</p> 3012<p>Some characters (<code>< > : " / \ | ? *</code>) are reserved under Windows as documented 3013by <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 3014a colon, Node.js will open a file system stream, as described by 3015<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/using-streams">this MSDN page</a>.</p> 3016<p>Functions based on <code>fs.open()</code> exhibit this behavior as well: 3017<code>fs.writeFile()</code>, <code>fs.readFile()</code>, etc.</p> 3018<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> 3019<div class="api_metadata"> 3020<details class="changelog"><summary>History</summary> 3021<table> 3022<tbody><tr><th>Version</th><th>Changes</th></tr> 3023<tr><td>v13.1.0, v12.16.0</td> 3024<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 3025<tr><td>v12.12.0</td> 3026<td><p><span>Added in: v12.12.0</span></p></td></tr> 3027</tbody></table> 3028</details> 3029</div> 3030<ul> 3031<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> 3032<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3033<ul> 3034<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> 3035<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 3036internally when reading from the directory. Higher values lead to better 3037performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 3038</ul> 3039</li> 3040<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3041<ul> 3042<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3043<li><code>dir</code> <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li> 3044</ul> 3045</li> 3046</ul> 3047<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 3048more details.</p> 3049<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 3050and cleaning up the directory.</p> 3051<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 3052directory and subsequent read operations.</p> 3053<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> 3054<div class="api_metadata"> 3055<details class="changelog"><summary>History</summary> 3056<table> 3057<tbody><tr><th>Version</th><th>Changes</th></tr> 3058<tr><td>v10.10.0</td> 3059<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code>, or a <code>DataView</code>.</p></td></tr> 3060<tr><td>v7.4.0</td> 3061<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 3062<tr><td>v6.0.0</td> 3063<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr> 3064<tr><td>v0.0.2</td> 3065<td><p><span>Added in: v0.0.2</span></p></td></tr> 3066</tbody></table> 3067</details> 3068</div> 3069<ul> 3070<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3071<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 3072written to. <strong>Default:</strong> <code>Buffer.alloc(16384)</code></li> 3073<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> 3074<code>0</code></li> 3075<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> 3076<code>buffer.byteLength</code></li> 3077<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 3078file. If <code>position</code> is <code>null</code> or <code>-1 </code>, data will be read from the current 3079file position, and the file position will be updated. If <code>position</code> is an 3080integer, the file position will be unchanged.</li> 3081<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3082<ul> 3083<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3084<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3085<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li> 3086</ul> 3087</li> 3088</ul> 3089<p>Read data from the file specified by <code>fd</code>.</p> 3090<p>The callback is given the three arguments, <code>(err, bytesRead, buffer)</code>.</p> 3091<p>If the file is not modified concurrently, the end-of-file is reached when the 3092number of bytes read is zero.</p> 3093<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 3094a promise for an <code>Object</code> with <code>bytesRead</code> and <code>buffer</code> properties.</p> 3095<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> 3096<div class="api_metadata"> 3097<details class="changelog"><summary>History</summary> 3098<table> 3099<tbody><tr><th>Version</th><th>Changes</th></tr> 3100<tr><td>v13.11.0, v12.17.0</td> 3101<td><p><span>Added in: v13.11.0, v12.17.0</span></p></td></tr> 3102<tr><td>v13.11.0, v12.17.0</td> 3103<td><p>Options object can be passed in to make Buffer, offset, length and position optional.</p></td></tr> 3104</tbody></table> 3105</details> 3106</div> 3107<ul> 3108<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3109<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3110<ul> 3111<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> 3112<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> 3113<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> 3114<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> 3115</ul> 3116</li> 3117<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3118<ul> 3119<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3120<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3121<li><code>buffer</code> <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a></li> 3122</ul> 3123</li> 3124</ul> 3125<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 3126<code>options</code> object. If no <code>options</code> object is specified, it will default with the 3127above values.</p> 3128<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> 3129<div class="api_metadata"> 3130<details class="changelog"><summary>History</summary> 3131<table> 3132<tbody><tr><th>Version</th><th>Changes</th></tr> 3133<tr><td>v10.10.0</td> 3134<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 3135<tr><td>v10.0.0</td> 3136<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> 3137<tr><td>v7.6.0</td> 3138<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3139<tr><td>v7.0.0</td> 3140<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> 3141<tr><td>v6.0.0</td> 3142<td><p>The <code>options</code> parameter was added.</p></td></tr> 3143<tr><td>v0.1.8</td> 3144<td><p><span>Added in: v0.1.8</span></p></td></tr> 3145</tbody></table> 3146</details> 3147</div> 3148<ul> 3149<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> 3150<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> 3151<ul> 3152<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> 3153<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> 3154</ul> 3155</li> 3156<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3157<ul> 3158<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3159<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> 3160</ul> 3161</li> 3162</ul> 3163<p>Reads the contents of a directory. The callback gets two arguments <code>(err, files)</code> 3164where <code>files</code> is an array of the names of the files in the directory excluding 3165<code>'.'</code> and <code>'..'</code>.</p> 3166<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> 3167<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3168object with an <code>encoding</code> property specifying the character encoding to use for 3169the filenames passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3170the filenames returned will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 3171<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the <code>files</code> array will contain 3172<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 3173<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> 3174<div class="api_metadata"> 3175<details class="changelog"><summary>History</summary> 3176<table> 3177<tbody><tr><th>Version</th><th>Changes</th></tr> 3178<tr><td>v14.17.0</td> 3179<td><p>The options argument may include an AbortSignal to abort an ongoing readFile request.</p></td></tr> 3180<tr><td>v10.0.0</td> 3181<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> 3182<tr><td>v7.6.0</td> 3183<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3184<tr><td>v7.0.0</td> 3185<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> 3186<tr><td>v5.1.0</td> 3187<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> 3188<tr><td>v5.0.0</td> 3189<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr> 3190<tr><td>v0.1.29</td> 3191<td><p><span>Added in: v0.1.29</span></p></td></tr> 3192</tbody></table> 3193</details> 3194</div> 3195<ul> 3196<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> 3197<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> 3198<ul> 3199<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> 3200<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> 3201<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress readFile</li> 3202</ul> 3203</li> 3204<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3205<ul> 3206<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3207<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> 3208</ul> 3209</li> 3210</ul> 3211<p>Asynchronously reads the entire contents of a file.</p> 3212<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>; 3213 3214<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> { 3215 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3216 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(data); 3217});</code></pre> 3218<p>The callback is passed two arguments <code>(err, data)</code>, where <code>data</code> is the 3219contents of the file.</p> 3220<p>If no encoding is specified, then the raw buffer is returned.</p> 3221<p>If <code>options</code> is a string, then it specifies the encoding:</p> 3222<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>; 3223 3224<span class="hljs-title function_">readFile</span>(<span class="hljs-string">'/etc/passwd'</span>, <span class="hljs-string">'utf8'</span>, callback);</code></pre> 3225<p>When the path is a directory, the behavior of <code>fs.readFile()</code> and 3226<a href="#fs_fs_readfilesync_path_options"><code>fs.readFileSync()</code></a> is platform-specific. On macOS, Linux, and Windows, an 3227error will be returned. On FreeBSD, a representation of the directory's contents 3228will be returned.</p> 3229<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>; 3230 3231<span class="hljs-comment">// macOS, Linux, and Windows</span> 3232<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> { 3233 <span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span> 3234}); 3235 3236<span class="hljs-comment">// FreeBSD</span> 3237<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> { 3238 <span class="hljs-comment">// => null, <data></span> 3239});</code></pre> 3240<p>It is possible to abort an ongoing request using an <code>AbortSignal</code>. If a 3241request is aborted the callback is called with an <code>AbortError</code>:</p> 3242<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>; 3243 3244<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 3245<span class="hljs-keyword">const</span> signal = controller.<span class="hljs-property">signal</span>; 3246<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> { 3247 <span class="hljs-comment">// ...</span> 3248}); 3249<span class="hljs-comment">// When you want to abort the request</span> 3250controller.<span class="hljs-title function_">abort</span>();</code></pre> 3251<p>The <code>fs.readFile()</code> function buffers the entire file. To minimize memory costs, 3252when possible prefer streaming via <code>fs.createReadStream()</code>.</p> 3253<p>Aborting an ongoing request does not abort individual operating 3254system requests but rather the internal buffering <code>fs.readFile</code> performs.</p> 3255<h5>File descriptors<span><a class="mark" href="#fs_file_descriptors" id="fs_file_descriptors">#</a></span></h5> 3256<ol> 3257<li>Any specified file descriptor has to support reading.</li> 3258<li>If a file descriptor is specified as the <code>path</code>, it will not be closed 3259automatically.</li> 3260<li>The reading will begin at the current position. For example, if the file 3261already had <code>'Hello World</code>' and six bytes are read with the file descriptor, 3262the call to <code>fs.readFile()</code> with the same file descriptor, would give 3263<code>'World'</code>, rather than <code>'Hello World'</code>.</li> 3264</ol> 3265<h5>Performance Considerations<span><a class="mark" href="#fs_performance_considerations" id="fs_performance_considerations">#</a></span></h5> 3266<p>The <code>fs.readFile()</code> method asynchronously reads the contents of a file into 3267memory one chunk at a time, allowing the event loop to turn between each chunk. 3268This allows the read operation to have less impact on other activity that may 3269be using the underlying libuv thread pool but means that it will take longer 3270to read a complete file into memory.</p> 3271<p>The additional read overhead can vary broadly on different systems and depends 3272on the type of file being read. If the file type is not a regular file (a pipe 3273for instance) and Node.js is unable to determine an actual file size, each read 3274operation will load on 64kb of data. For regular files, each read will process 3275512kb of data.</p> 3276<p>For applications that require as-fast-as-possible reading of file contents, it 3277is better to use <code>fs.read()</code> directly and for application code to manage 3278reading the full contents of the file itself.</p> 3279<p>The Node.js GitHub issue <a href="https://github.com/nodejs/node/issues/25741">#25741</a> provides more information and a detailed 3280analysis on the performance of <code>fs.readFile()</code> for multiple file sizes in 3281different Node.js versions.</p> 3282<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> 3283<div class="api_metadata"> 3284<details class="changelog"><summary>History</summary> 3285<table> 3286<tbody><tr><th>Version</th><th>Changes</th></tr> 3287<tr><td>v10.0.0</td> 3288<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> 3289<tr><td>v7.6.0</td> 3290<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3291<tr><td>v7.0.0</td> 3292<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> 3293<tr><td>v0.1.31</td> 3294<td><p><span>Added in: v0.1.31</span></p></td></tr> 3295</tbody></table> 3296</details> 3297</div> 3298<ul> 3299<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> 3300<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> 3301<ul> 3302<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> 3303</ul> 3304</li> 3305<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3306<ul> 3307<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3308<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> 3309</ul> 3310</li> 3311</ul> 3312<p>Reads the contents of the symbolic link referred to by <code>path</code>. The callback gets 3313two arguments <code>(err, linkString)</code>.</p> 3314<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> 3315<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3316object with an <code>encoding</code> property specifying the character encoding to use for 3317the link path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3318the link path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3319<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> 3320<div class="api_metadata"> 3321<span>Added in: v13.13.0, v12.17.0</span> 3322</div> 3323<ul> 3324<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3325<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 3326<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3327<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3328<ul> 3329<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3330<li><code>bytesRead</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 3331<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 3332</ul> 3333</li> 3334</ul> 3335<p>Read from a file specified by <code>fd</code> and write to an array of <code>ArrayBufferView</code>s 3336using <code>readv()</code>.</p> 3337<p><code>position</code> is the offset from the beginning of the file from where data 3338should be read. If <code>typeof position !== 'number'</code>, the data will be read 3339from the current position.</p> 3340<p>The callback will be given three arguments: <code>err</code>, <code>bytesRead</code>, and 3341<code>buffers</code>. <code>bytesRead</code> is how many bytes were read from the file.</p> 3342<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 3343a promise for an <code>Object</code> with <code>bytesRead</code> and <code>buffers</code> properties.</p> 3344<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> 3345<div class="api_metadata"> 3346<details class="changelog"><summary>History</summary> 3347<table> 3348<tbody><tr><th>Version</th><th>Changes</th></tr> 3349<tr><td>v10.0.0</td> 3350<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> 3351<tr><td>v8.0.0</td> 3352<td><p>Pipe/Socket resolve support was added.</p></td></tr> 3353<tr><td>v7.6.0</td> 3354<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3355<tr><td>v7.0.0</td> 3356<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> 3357<tr><td>v6.4.0</td> 3358<td><p>Calling <code>realpath</code> now works again for various edge cases on Windows.</p></td></tr> 3359<tr><td>v6.0.0</td> 3360<td><p>The <code>cache</code> parameter was removed.</p></td></tr> 3361<tr><td>v0.1.31</td> 3362<td><p><span>Added in: v0.1.31</span></p></td></tr> 3363</tbody></table> 3364</details> 3365</div> 3366<ul> 3367<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> 3368<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> 3369<ul> 3370<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> 3371</ul> 3372</li> 3373<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3374<ul> 3375<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3376<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> 3377</ul> 3378</li> 3379</ul> 3380<p>Asynchronously computes the canonical pathname by resolving <code>.</code>, <code>..</code> and 3381symbolic links.</p> 3382<p>A canonical pathname is not necessarily unique. Hard links and bind mounts can 3383expose a file system entity through many pathnames.</p> 3384<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> 3385<ol> 3386<li> 3387<p>No case conversion is performed on case-insensitive file systems.</p> 3388</li> 3389<li> 3390<p>The maximum number of symbolic links is platform-independent and generally 3391(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> 3392</li> 3393</ol> 3394<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>. May use <code>process.cwd</code> 3395to resolve relative paths.</p> 3396<p>Only paths that can be converted to UTF8 strings are supported.</p> 3397<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3398object with an <code>encoding</code> property specifying the character encoding to use for 3399the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3400the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3401<p>If <code>path</code> resolves to a socket or a pipe, the function will return a system 3402dependent name for that object.</p> 3403<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> 3404<div class="api_metadata"> 3405<span>Added in: v9.2.0</span> 3406</div> 3407<ul> 3408<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> 3409<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> 3410<ul> 3411<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> 3412</ul> 3413</li> 3414<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3415<ul> 3416<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3417<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> 3418</ul> 3419</li> 3420</ul> 3421<p>Asynchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p> 3422<p>The <code>callback</code> gets two arguments <code>(err, resolvedPath)</code>.</p> 3423<p>Only paths that can be converted to UTF8 strings are supported.</p> 3424<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 3425object with an <code>encoding</code> property specifying the character encoding to use for 3426the path passed to the callback. If the <code>encoding</code> is set to <code>'buffer'</code>, 3427the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 3428<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 3429be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 3430this restriction.</p> 3431<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> 3432<div class="api_metadata"> 3433<details class="changelog"><summary>History</summary> 3434<table> 3435<tbody><tr><th>Version</th><th>Changes</th></tr> 3436<tr><td>v10.0.0</td> 3437<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> 3438<tr><td>v7.6.0</td> 3439<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> 3440<tr><td>v7.0.0</td> 3441<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> 3442<tr><td>v0.0.2</td> 3443<td><p><span>Added in: v0.0.2</span></p></td></tr> 3444</tbody></table> 3445</details> 3446</div> 3447<ul> 3448<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> 3449<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> 3450<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3451<ul> 3452<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3453</ul> 3454</li> 3455</ul> 3456<p>Asynchronously rename file at <code>oldPath</code> to the pathname provided 3457as <code>newPath</code>. In the case that <code>newPath</code> already exists, it will 3458be overwritten. If there is a directory at <code>newPath</code>, an error will 3459be raised instead. No arguments other than a possible exception are 3460given to the completion callback.</p> 3461<p>See also: <a href="http://man7.org/linux/man-pages/man2/rename.2.html"><code>rename(2)</code></a>.</p> 3462<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>; 3463 3464<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> { 3465 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3466 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Rename complete!'</span>); 3467});</code></pre> 3468<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> 3469<div class="api_metadata"> 3470<details class="changelog"><summary>History</summary> 3471<table> 3472<tbody><tr><th>Version</th><th>Changes</th></tr> 3473<tr><td>v14.14.0</td> 3474<td><p>The <code>recursive</code> option is deprecated, use <code>fs.rm</code> instead.</p></td></tr> 3475<tr><td>v13.3.0, v12.16.0</td> 3476<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> 3477<tr><td>v12.10.0</td> 3478<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 3479<tr><td>v10.0.0</td> 3480<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> 3481<tr><td>v7.6.0</td> 3482<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3483<tr><td>v7.0.0</td> 3484<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> 3485<tr><td>v0.0.2</td> 3486<td><p><span>Added in: v0.0.2</span></p></td></tr> 3487</tbody></table> 3488</details> 3489</div> 3490<ul> 3491<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> 3492<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3493<ul> 3494<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 3495<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 3496backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 3497represents the number of retries. This option is ignored if the <code>recursive</code> 3498option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 3499<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 3500recursive mode, errors are not reported if <code>path</code> does not exist, and 3501operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 3502<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 3503retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 3504<strong>Default:</strong> <code>100</code>.</li> 3505</ul> 3506</li> 3507<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3508<ul> 3509<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3510</ul> 3511</li> 3512</ul> 3513<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 3514to the completion callback.</p> 3515<p>Using <code>fs.rmdir()</code> on a file (not a directory) results in an <code>ENOENT</code> error on 3516Windows and an <code>ENOTDIR</code> error on POSIX.</p> 3517<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 3518<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 3519that represent files will be deleted. The permissive behavior of the 3520<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 3521the future.</p> 3522<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> 3523<div class="api_metadata"> 3524<span>Added in: v14.14.0</span> 3525</div> 3526<ul> 3527<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> 3528<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3529<ul> 3530<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 3531not exist. <strong>Default:</strong> <code>false</code>.</li> 3532<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 3533<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 3534backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 3535represents the number of retries. This option is ignored if the <code>recursive</code> 3536option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 3537<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 3538recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 3539<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 3540retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 3541<strong>Default:</strong> <code>100</code>.</li> 3542</ul> 3543</li> 3544<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3545<ul> 3546<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3547</ul> 3548</li> 3549</ul> 3550<p>Asynchronously removes files and directories (modeled on the standard POSIX <code>rm</code> 3551utility). No arguments other than a possible exception are given to the 3552completion callback.</p> 3553<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> 3554<div class="api_metadata"> 3555<details class="changelog"><summary>History</summary> 3556<table> 3557<tbody><tr><th>Version</th><th>Changes</th></tr> 3558<tr><td>v10.5.0</td> 3559<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 3560<tr><td>v10.0.0</td> 3561<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> 3562<tr><td>v7.6.0</td> 3563<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3564<tr><td>v7.0.0</td> 3565<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> 3566<tr><td>v0.0.2</td> 3567<td><p><span>Added in: v0.0.2</span></p></td></tr> 3568</tbody></table> 3569</details> 3570</div> 3571<ul> 3572<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> 3573<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3574<ul> 3575<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 3576<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> 3577</ul> 3578</li> 3579<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3580<ul> 3581<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3582<li><code>stats</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3583</ul> 3584</li> 3585</ul> 3586<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 3587<code>stats</code> is an <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object.</p> 3588<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> 3589<p>Using <code>fs.stat()</code> to check for the existence of a file before calling 3590<code>fs.open()</code>, <code>fs.readFile()</code> or <code>fs.writeFile()</code> is not recommended. 3591Instead, user code should open/read/write the file directly and handle the 3592error raised if the file is not available.</p> 3593<p>To check if a file exists without manipulating it afterwards, <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a> 3594is recommended.</p> 3595<p>For example, given the following directory structure:</p> 3596<pre><code class="language-text">- txtDir 3597-- file.txt 3598- app.js</code></pre> 3599<p>The next program will check for the stats of the given paths:</p> 3600<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>; 3601 3602<span class="hljs-keyword">const</span> pathsToCheck = [<span class="hljs-string">'./txtDir'</span>, <span class="hljs-string">'./txtDir/file.txt'</span>]; 3603 3604<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++) { 3605 <span class="hljs-title function_">stat</span>(pathsToCheck[i], <span class="hljs-function">(<span class="hljs-params">err, stats</span>) =></span> { 3606 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(stats.<span class="hljs-title function_">isDirectory</span>()); 3607 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(stats); 3608 }); 3609}</code></pre> 3610<p>The resulting output will resemble:</p> 3611<pre><code class="language-console">true 3612Stats { 3613 dev: 16777220, 3614 mode: 16877, 3615 nlink: 3, 3616 uid: 501, 3617 gid: 20, 3618 rdev: 0, 3619 blksize: 4096, 3620 ino: 14214262, 3621 size: 96, 3622 blocks: 0, 3623 atimeMs: 1561174653071.963, 3624 mtimeMs: 1561174614583.3518, 3625 ctimeMs: 1561174626623.5366, 3626 birthtimeMs: 1561174126937.2893, 3627 atime: 2019-06-22T03:37:33.072Z, 3628 mtime: 2019-06-22T03:36:54.583Z, 3629 ctime: 2019-06-22T03:37:06.624Z, 3630 birthtime: 2019-06-22T03:28:46.937Z 3631} 3632false 3633Stats { 3634 dev: 16777220, 3635 mode: 33188, 3636 nlink: 1, 3637 uid: 501, 3638 gid: 20, 3639 rdev: 0, 3640 blksize: 4096, 3641 ino: 14214074, 3642 size: 8, 3643 blocks: 8, 3644 atimeMs: 1561174616618.8555, 3645 mtimeMs: 1561174614584, 3646 ctimeMs: 1561174614583.8145, 3647 birthtimeMs: 1561174007710.7478, 3648 atime: 2019-06-22T03:36:56.619Z, 3649 mtime: 2019-06-22T03:36:54.584Z, 3650 ctime: 2019-06-22T03:36:54.584Z, 3651 birthtime: 2019-06-22T03:26:47.711Z 3652}</code></pre> 3653<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> 3654<div class="api_metadata"> 3655<details class="changelog"><summary>History</summary> 3656<table> 3657<tbody><tr><th>Version</th><th>Changes</th></tr> 3658<tr><td>v12.0.0</td> 3659<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> 3660<tr><td>v7.6.0</td> 3661<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> 3662<tr><td>v0.1.31</td> 3663<td><p><span>Added in: v0.1.31</span></p></td></tr> 3664</tbody></table> 3665</details> 3666</div> 3667<ul> 3668<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> 3669<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> 3670<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 3671<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3672<ul> 3673<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3674</ul> 3675</li> 3676</ul> 3677<p>Creates the link called <code>path</code> pointing to <code>target</code>. No arguments other than a 3678possible exception are given to the completion callback.</p> 3679<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> 3680<p>The <code>type</code> argument is only available on Windows and ignored on other platforms. 3681It can be set to <code>'dir'</code>, <code>'file'</code>, or <code>'junction'</code>. If the <code>type</code> argument is 3682not set, Node.js will autodetect <code>target</code> type and use <code>'file'</code> or <code>'dir'</code>. If 3683the <code>target</code> does not exist, <code>'file'</code> will be used. Windows junction points 3684require the destination path to be absolute. When using <code>'junction'</code>, the 3685<code>target</code> argument will automatically be normalized to absolute path.</p> 3686<p>Relative targets are relative to the link’s parent directory.</p> 3687<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>; 3688 3689<span class="hljs-title function_">symlink</span>(<span class="hljs-string">'./mew'</span>, <span class="hljs-string">'./example/mewtwo'</span>, callback);</code></pre> 3690<p>The above example creates a symbolic link <code>mewtwo</code> in the <code>example</code> which points 3691to <code>mew</code> in the same directory:</p> 3692<pre><code class="language-bash">$ tree example/ 3693example/ 3694├── mew 3695└── mewtwo -> ./mew</code></pre> 3696<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> 3697<div class="api_metadata"> 3698<details class="changelog"><summary>History</summary> 3699<table> 3700<tbody><tr><th>Version</th><th>Changes</th></tr> 3701<tr><td>v10.0.0</td> 3702<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> 3703<tr><td>v7.0.0</td> 3704<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> 3705<tr><td>v0.8.6</td> 3706<td><p><span>Added in: v0.8.6</span></p></td></tr> 3707</tbody></table> 3708</details> 3709</div> 3710<ul> 3711<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> 3712<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> 3713<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3714<ul> 3715<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3716</ul> 3717</li> 3718</ul> 3719<p>Truncates the file. No arguments other than a possible exception are 3720given to the completion callback. A file descriptor can also be passed as the 3721first argument. In this case, <code>fs.ftruncate()</code> is called.</p> 3722 3723<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>; 3724<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3725<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> { 3726 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3727 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was truncated'</span>); 3728});</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>); 3729<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3730<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> { 3731 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3732 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was truncated'</span>); 3733});</code></pre> 3734<p>Passing a file descriptor is deprecated and may result in an error being thrown 3735in the future.</p> 3736<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> 3737<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> 3738<div class="api_metadata"> 3739<details class="changelog"><summary>History</summary> 3740<table> 3741<tbody><tr><th>Version</th><th>Changes</th></tr> 3742<tr><td>v10.0.0</td> 3743<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> 3744<tr><td>v7.6.0</td> 3745<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3746<tr><td>v7.0.0</td> 3747<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> 3748<tr><td>v0.0.2</td> 3749<td><p><span>Added in: v0.0.2</span></p></td></tr> 3750</tbody></table> 3751</details> 3752</div> 3753<ul> 3754<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> 3755<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3756<ul> 3757<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3758</ul> 3759</li> 3760</ul> 3761<p>Asynchronously removes a file or symbolic link. No arguments other than a 3762possible exception are given to the completion callback.</p> 3763<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>; 3764<span class="hljs-comment">// Assuming that 'path/file.txt' is a regular file.</span> 3765<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> { 3766 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 3767 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'path/file.txt was deleted'</span>); 3768});</code></pre> 3769<p><code>fs.unlink()</code> will not work on a directory, empty or otherwise. To remove a 3770directory, use <a href="#fs_fs_rmdir_path_options_callback"><code>fs.rmdir()</code></a>.</p> 3771<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> 3772<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> 3773<div class="api_metadata"> 3774<span>Added in: v0.1.31</span> 3775</div> 3776<ul> 3777<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> 3778<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 3779<code>fs.watchFile()</code></li> 3780</ul> 3781<p>Stop watching for changes on <code>filename</code>. If <code>listener</code> is specified, only that 3782particular listener is removed. Otherwise, <em>all</em> listeners are removed, 3783effectively stopping watching of <code>filename</code>.</p> 3784<p>Calling <code>fs.unwatchFile()</code> with a filename that is not being watched is a 3785no-op, not an error.</p> 3786<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile()</code> and 3787<code>fs.unwatchFile()</code>. <code>fs.watch()</code> should be used instead of <code>fs.watchFile()</code> 3788and <code>fs.unwatchFile()</code> when possible.</p> 3789<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> 3790<div class="api_metadata"> 3791<details class="changelog"><summary>History</summary> 3792<table> 3793<tbody><tr><th>Version</th><th>Changes</th></tr> 3794<tr><td>v10.0.0</td> 3795<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> 3796<tr><td>v8.0.0</td> 3797<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr> 3798<tr><td>v7.6.0</td> 3799<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3800<tr><td>v7.0.0</td> 3801<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> 3802<tr><td>v4.1.0</td> 3803<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 3804<tr><td>v0.4.2</td> 3805<td><p><span>Added in: v0.4.2</span></p></td></tr> 3806</tbody></table> 3807</details> 3808</div> 3809<ul> 3810<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> 3811<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> 3812<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> 3813<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3814<ul> 3815<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 3816</ul> 3817</li> 3818</ul> 3819<p>Change the file system timestamps of the object referenced by <code>path</code>.</p> 3820<p>The <code>atime</code> and <code>mtime</code> arguments follow these rules:</p> 3821<ul> 3822<li>Values can be either numbers representing Unix epoch time in seconds, 3823<code>Date</code>s, or a numeric string like <code>'123456789.0'</code>.</li> 3824<li>If the value can not be converted to a number, or is <code>NaN</code>, <code>Infinity</code> or 3825<code>-Infinity</code>, an <code>Error</code> will be thrown.</li> 3826</ul> 3827<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> 3828<div class="api_metadata"> 3829<details class="changelog"><summary>History</summary> 3830<table> 3831<tbody><tr><th>Version</th><th>Changes</th></tr> 3832<tr><td>v14.17.0</td> 3833<td><p>Added support for closing the watcher with an AbortSignal.</p></td></tr> 3834<tr><td>v7.6.0</td> 3835<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3836<tr><td>v7.0.0</td> 3837<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 3838<tr><td>v0.5.10</td> 3839<td><p><span>Added in: v0.5.10</span></p></td></tr> 3840</tbody></table> 3841</details> 3842</div> 3843<ul> 3844<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> 3845<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> 3846<ul> 3847<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 3848as long as files are being watched. <strong>Default:</strong> <code>true</code>.</li> 3849<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 3850watched, or only the current directory. This applies when a directory is 3851specified, and only on supported platforms (See <a href="#fs_caveats">caveats</a>). <strong>Default:</strong> 3852<code>false</code>.</li> 3853<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 3854filename passed to the listener. <strong>Default:</strong> <code>'utf8'</code>.</li> 3855<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows closing the watcher with an AbortSignal.</li> 3856</ul> 3857</li> 3858<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> 3859<ul> 3860<li><code>eventType</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 3861<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> 3862</ul> 3863</li> 3864<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 3865</ul> 3866<p>Watch for changes on <code>filename</code>, where <code>filename</code> is either a file or a 3867directory.</p> 3868<p>The second argument is optional. If <code>options</code> is provided as a string, it 3869specifies the <code>encoding</code>. Otherwise <code>options</code> should be passed as an object.</p> 3870<p>The listener callback gets two arguments <code>(eventType, filename)</code>. <code>eventType</code> 3871is either <code>'rename'</code> or <code>'change'</code>, and <code>filename</code> is the name of the file 3872which triggered the event.</p> 3873<p>On most platforms, <code>'rename'</code> is emitted whenever a filename appears or 3874disappears in the directory.</p> 3875<p>The listener callback is attached to the <code>'change'</code> event fired by 3876<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 3877<code>eventType</code>.</p> 3878<p>If a <code>signal</code> is passed, aborting the corresponding AbortController will close 3879the returned <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>.</p> 3880<h5>Caveats<span><a class="mark" href="#fs_caveats" id="fs_caveats">#</a></span></h5> 3881 3882<p>The <code>fs.watch</code> API is not 100% consistent across platforms, and is 3883unavailable in some situations.</p> 3884<p>The recursive option is only supported on macOS and Windows. 3885An <code>ERR_FEATURE_UNAVAILABLE_ON_PLATFORM</code> exception will be thrown 3886when the option is used on a platform that does not support it.</p> 3887<p>On Windows, no events will be emitted if the watched directory is moved or 3888renamed. An <code>EPERM</code> error is reported when the watched directory is deleted.</p> 3889<h6>Availability<span><a class="mark" href="#fs_availability" id="fs_availability">#</a></span></h6> 3890 3891<p>This feature depends on the underlying operating system providing a way 3892to be notified of filesystem changes.</p> 3893<ul> 3894<li>On Linux systems, this uses <a href="https://man7.org/linux/man-pages/man7/inotify.7.html"><code>inotify(7)</code></a>.</li> 3895<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> 3896<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 3897directories.</li> 3898<li>On SunOS systems (including Solaris and SmartOS), this uses <a href="https://illumos.org/man/port_create"><code>event ports</code></a>.</li> 3899<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> 3900<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> 3901<li>On IBM i systems, this feature is not supported.</li> 3902</ul> 3903<p>If the underlying functionality is not available for some reason, then 3904<code>fs.watch()</code> will not be able to function and may throw an exception. 3905For example, watching files or directories can be unreliable, and in some 3906cases impossible, on network file systems (NFS, SMB, etc) or host file systems 3907when using virtualization software such as Vagrant or Docker.</p> 3908<p>It is still possible to use <code>fs.watchFile()</code>, which uses stat polling, but 3909this method is slower and less reliable.</p> 3910<h6>Inodes<span><a class="mark" href="#fs_inodes" id="fs_inodes">#</a></span></h6> 3911 3912<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 3913watches the inode. If the watched path is deleted and recreated, it is assigned 3914a new inode. The watch will emit an event for the delete but will continue 3915watching the <em>original</em> inode. Events for the new inode will not be emitted. 3916This is expected behavior.</p> 3917<p>AIX files retain the same inode for the lifetime of a file. Saving and closing a 3918watched file on AIX will result in two notifications (one for adding new 3919content, and one for truncation).</p> 3920<h6>Filename argument<span><a class="mark" href="#fs_filename_argument" id="fs_filename_argument">#</a></span></h6> 3921 3922<p>Providing <code>filename</code> argument in the callback is only supported on Linux, 3923macOS, Windows, and AIX. Even on supported platforms, <code>filename</code> is not always 3924guaranteed to be provided. Therefore, don't assume that <code>filename</code> argument is 3925always provided in the callback, and have some fallback logic if it is <code>null</code>.</p> 3926<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>; 3927<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> { 3928 <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>); 3929 <span class="hljs-keyword">if</span> (filename) { 3930 <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>); 3931 } <span class="hljs-keyword">else</span> { 3932 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'filename not provided'</span>); 3933 } 3934});</code></pre> 3935<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> 3936<div class="api_metadata"> 3937<details class="changelog"><summary>History</summary> 3938<table> 3939<tbody><tr><th>Version</th><th>Changes</th></tr> 3940<tr><td>v10.5.0</td> 3941<td><p>The <code>bigint</code> option is now supported.</p></td></tr> 3942<tr><td>v7.6.0</td> 3943<td><p>The <code>filename</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 3944<tr><td>v0.1.31</td> 3945<td><p><span>Added in: v0.1.31</span></p></td></tr> 3946</tbody></table> 3947</details> 3948</div> 3949<ul> 3950<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> 3951<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 3952<ul> 3953<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> 3954<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> 3955<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> 3956</ul> 3957</li> 3958<li><code>listener</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 3959<ul> 3960<li><code>current</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3961<li><code>previous</code> <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 3962</ul> 3963</li> 3964<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 3965</ul> 3966<p>Watch for changes on <code>filename</code>. The callback <code>listener</code> will be called each 3967time the file is accessed.</p> 3968<p>The <code>options</code> argument may be omitted. If provided, it should be an object. The 3969<code>options</code> object may contain a boolean named <code>persistent</code> that indicates 3970whether the process should continue to run as long as files are being watched. 3971The <code>options</code> object may specify an <code>interval</code> property indicating how often the 3972target should be polled in milliseconds.</p> 3973<p>The <code>listener</code> gets two arguments the current stat object and the previous 3974stat object:</p> 3975<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>; 3976 3977<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> { 3978 <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>); 3979 <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>); 3980});</code></pre> 3981<p>These stat objects are instances of <code>fs.Stat</code>. If the <code>bigint</code> option is <code>true</code>, 3982the numeric values in these objects are specified as <code>BigInt</code>s.</p> 3983<p>To be notified when the file was modified, not just accessed, it is necessary 3984to compare <code>curr.mtime</code> and <code>prev.mtime</code>.</p> 3985<p>When an <code>fs.watchFile</code> operation results in an <code>ENOENT</code> error, it 3986will invoke the listener once, with all the fields zeroed (or, for dates, the 3987Unix Epoch). If the file is created later on, the listener will be called 3988again, with the latest stat objects. This is a change in functionality since 3989v0.10.</p> 3990<p>Using <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a> is more efficient than <code>fs.watchFile</code> and 3991<code>fs.unwatchFile</code>. <code>fs.watch</code> should be used instead of <code>fs.watchFile</code> and 3992<code>fs.unwatchFile</code> when possible.</p> 3993<p>When a file being watched by <code>fs.watchFile()</code> disappears and reappears, 3994then the contents of <code>previous</code> in the second callback event (the file's 3995reappearance) will be the same as the contents of <code>previous</code> in the first 3996callback event (its disappearance).</p> 3997<p>This happens when:</p> 3998<ul> 3999<li>the file is deleted, followed by a restore</li> 4000<li>the file is renamed and then renamed a second time back to its original name</li> 4001</ul> 4002<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> 4003<div class="api_metadata"> 4004<details class="changelog"><summary>History</summary> 4005<table> 4006<tbody><tr><th>Version</th><th>Changes</th></tr> 4007<tr><td>v14.0.0</td> 4008<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4009<tr><td>v10.10.0</td> 4010<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4011<tr><td>v10.0.0</td> 4012<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> 4013<tr><td>v7.4.0</td> 4014<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4015<tr><td>v7.2.0</td> 4016<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 4017<tr><td>v7.0.0</td> 4018<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> 4019<tr><td>v0.0.2</td> 4020<td><p><span>Added in: v0.0.2</span></p></td></tr> 4021</tbody></table> 4022</details> 4023</div> 4024<ul> 4025<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4026<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> 4027<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4028<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4029<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4030<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4031<ul> 4032<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4033<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4034<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> 4035</ul> 4036</li> 4037</ul> 4038<p>Write <code>buffer</code> to the file specified by <code>fd</code>.</p> 4039<p><code>offset</code> determines the part of the buffer to be written, and <code>length</code> is 4040an integer specifying the number of bytes to write.</p> 4041<p><code>position</code> refers to the offset from the beginning of the file where this data 4042should be written. If <code>typeof position !== 'number'</code>, the data will be written 4043at the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4044<p>The callback will be given three arguments <code>(err, bytesWritten, buffer)</code> where 4045<code>bytesWritten</code> specifies how many <em>bytes</em> were written from <code>buffer</code>.</p> 4046<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 4047a promise for an <code>Object</code> with <code>bytesWritten</code> and <code>buffer</code> properties.</p> 4048<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4049for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4050recommended.</p> 4051<p>On Linux, positional writes don't work when the file is opened in append mode. 4052The kernel ignores the position argument and always appends the data to 4053the end of the file.</p> 4054<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> 4055<div class="api_metadata"> 4056<details class="changelog"><summary>History</summary> 4057<table> 4058<tbody><tr><th>Version</th><th>Changes</th></tr> 4059<tr><td>v14.12.0</td> 4060<td><p>The <code>string</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4061<tr><td>v14.0.0</td> 4062<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4063<tr><td>v10.0.0</td> 4064<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> 4065<tr><td>v7.2.0</td> 4066<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 4067<tr><td>v7.0.0</td> 4068<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> 4069<tr><td>v0.11.5</td> 4070<td><p><span>Added in: v0.11.5</span></p></td></tr> 4071</tbody></table> 4072</details> 4073</div> 4074<ul> 4075<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4076<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> 4077<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4078<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> 4079<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4080<ul> 4081<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4082<li><code>written</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4083<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4084</ul> 4085</li> 4086</ul> 4087<p>Write <code>string</code> to the file specified by <code>fd</code>. If <code>string</code> is not a string, or an 4088object with an own <code>toString</code> function property, then an exception is thrown.</p> 4089<p><code>position</code> refers to the offset from the beginning of the file where this data 4090should be written. If <code>typeof position !== 'number'</code> the data will be written at 4091the current position. See <a href="http://man7.org/linux/man-pages/man2/pwrite.2.html"><code>pwrite(2)</code></a>.</p> 4092<p><code>encoding</code> is the expected string encoding.</p> 4093<p>The callback will receive the arguments <code>(err, written, string)</code> where <code>written</code> 4094specifies how many <em>bytes</em> the passed string required to be written. Bytes 4095written is not necessarily the same as string characters written. See 4096<a href="buffer.html#buffer_static_method_buffer_bytelength_string_encoding"><code>Buffer.byteLength</code></a>.</p> 4097<p>It is unsafe to use <code>fs.write()</code> multiple times on the same file without waiting 4098for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4099recommended.</p> 4100<p>On Linux, positional writes don't work when the file is opened in append mode. 4101The kernel ignores the position argument and always appends the data to 4102the end of the file.</p> 4103<p>On Windows, if the file descriptor is connected to the console (e.g. <code>fd == 1</code> 4104or <code>stdout</code>) a string containing non-ASCII characters will not be rendered 4105properly by default, regardless of the encoding used. 4106It is possible to configure the console to render UTF-8 properly by changing the 4107active codepage with the <code>chcp 65001</code> command. See the <a href="https://ss64.com/nt/chcp.html">chcp</a> docs for more 4108details.</p> 4109<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> 4110<div class="api_metadata"> 4111<details class="changelog"><summary>History</summary> 4112<table> 4113<tbody><tr><th>Version</th><th>Changes</th></tr> 4114<tr><td>v14.17.0</td> 4115<td><p>The options argument may include an AbortSignal to abort an ongoing writeFile request.</p></td></tr> 4116<tr><td>v14.12.0</td> 4117<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 4118<tr><td>v14.0.0</td> 4119<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 4120<tr><td>v10.10.0</td> 4121<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4122<tr><td>v10.0.0</td> 4123<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> 4124<tr><td>v7.4.0</td> 4125<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 4126<tr><td>v7.0.0</td> 4127<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> 4128<tr><td>v5.0.0</td> 4129<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4130<tr><td>v0.1.29</td> 4131<td><p><span>Added in: v0.1.29</span></p></td></tr> 4132</tbody></table> 4133</details> 4134</div> 4135<ul> 4136<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> 4137<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> 4138<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> 4139<ul> 4140<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> 4141<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> 4142<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> 4143<li><code>signal</code> <a href="globals.html#globals_class_abortsignal" class="type"><AbortSignal></a> allows aborting an in-progress writeFile</li> 4144</ul> 4145</li> 4146<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4147<ul> 4148<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4149</ul> 4150</li> 4151</ul> 4152<p>When <code>file</code> is a filename, asynchronously writes data to the file, replacing the 4153file if it already exists. <code>data</code> can be a string or a buffer.</p> 4154<p>When <code>file</code> is a file descriptor, the behavior is similar to calling 4155<code>fs.write()</code> directly (which is recommended). See the notes below on using 4156a file descriptor.</p> 4157<p>The <code>encoding</code> option is ignored if <code>data</code> is a buffer.</p> 4158<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> 4159for more details.</p> 4160<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 4161function property.</p> 4162<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>; 4163 4164<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>)); 4165<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> { 4166 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 4167 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The file has been saved!'</span>); 4168});</code></pre> 4169<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4170<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>; 4171 4172<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> 4173<p>It is unsafe to use <code>fs.writeFile()</code> multiple times on the same file without 4174waiting for the callback. For this scenario, <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> is 4175recommended.</p> 4176<p>Similarly to <code>fs.readFile</code> - <code>fs.writeFile</code> is a convenience method that 4177performs multiple <code>write</code> calls internally to write the buffer passed to it. 4178For performance sensitive code consider using <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4179<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>. 4180Cancelation is "best effort", and some amount of data is likely still 4181to be written.</p> 4182<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>; 4183 4184<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 4185<span class="hljs-keyword">const</span> { signal } = controller; 4186<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>)); 4187<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> { 4188 <span class="hljs-comment">// When a request is aborted - the callback is called with an AbortError</span> 4189}); 4190<span class="hljs-comment">// When the request should be aborted</span> 4191controller.<span class="hljs-title function_">abort</span>();</code></pre> 4192<p>Aborting an ongoing request does not abort individual operating 4193system requests but rather the internal buffering <code>fs.writeFile</code> performs.</p> 4194<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> 4195<p>When <code>file</code> is a file descriptor, the behavior is almost identical to directly 4196calling <code>fs.write()</code> like:</p> 4197<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>; 4198 4199<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> 4200<p>The difference from directly calling <code>fs.write()</code> is that under some unusual 4201conditions, <code>fs.write()</code> might write only part of the buffer and need to be 4202retried to write the remaining data, whereas <code>fs.writeFile()</code> retries until 4203the data is entirely written (or an error occurs).</p> 4204<p>The implications of this are a common source of confusion. In 4205the file descriptor case, the file is not replaced! The data is not necessarily 4206written to the beginning of the file, and the file's original data may remain 4207before and/or after the newly written data.</p> 4208<p>For example, if <code>fs.writeFile()</code> is called twice in a row, first to write the 4209string <code>'Hello'</code>, then to write the string <code>', World'</code>, the file would contain 4210<code>'Hello, World'</code>, and might contain some of the file's original data (depending 4211on the size of the original file, and the position of the file descriptor). If 4212a file name had been used instead of a descriptor, the file would be guaranteed 4213to contain only <code>', World'</code>.</p> 4214<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> 4215<div class="api_metadata"> 4216<span>Added in: v12.9.0</span> 4217</div> 4218<ul> 4219<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4220<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4221<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4222<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 4223<ul> 4224<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 4225<li><code>bytesWritten</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4226<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4227</ul> 4228</li> 4229</ul> 4230<p>Write an array of <code>ArrayBufferView</code>s to the file specified by <code>fd</code> using 4231<code>writev()</code>.</p> 4232<p><code>position</code> is the offset from the beginning of the file where this data 4233should be written. If <code>typeof position !== 'number'</code>, the data will be written 4234at the current position.</p> 4235<p>The callback will be given three arguments: <code>err</code>, <code>bytesWritten</code>, and 4236<code>buffers</code>. <code>bytesWritten</code> is how many bytes were written from <code>buffers</code>.</p> 4237<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 4238<code>Object</code> with <code>bytesWritten</code> and <code>buffers</code> properties.</p> 4239<p>It is unsafe to use <code>fs.writev()</code> multiple times on the same file without 4240waiting for the callback. For this scenario, use <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>.</p> 4241<p>On Linux, positional writes don't work when the file is opened in append mode. 4242The kernel ignores the position argument and always appends the data to 4243the end of the file.</p> 4244</section><section><h3>Synchronous API<span><a class="mark" href="#fs_synchronous_api" id="fs_synchronous_api">#</a></span></h3> 4245<p>The synchronous APIs perform all operations synchronously, blocking the 4246event loop until the operation completes or fails.</p> 4247<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> 4248<div class="api_metadata"> 4249<details class="changelog"><summary>History</summary> 4250<table> 4251<tbody><tr><th>Version</th><th>Changes</th></tr> 4252<tr><td>v7.6.0</td> 4253<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4254<tr><td>v0.11.15</td> 4255<td><p><span>Added in: v0.11.15</span></p></td></tr> 4256</tbody></table> 4257</details> 4258</div> 4259<ul> 4260<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> 4261<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> 4262</ul> 4263<p>Synchronously tests a user's permissions for the file or directory specified 4264by <code>path</code>. The <code>mode</code> argument is an optional integer that specifies the 4265accessibility checks to be performed. Check <a href="#fs_file_access_constants">File access constants</a> for 4266possible values of <code>mode</code>. It is possible to create a mask consisting of 4267the bitwise OR of two or more values 4268(e.g. <code>fs.constants.W_OK | fs.constants.R_OK</code>).</p> 4269<p>If any of the accessibility checks fail, an <code>Error</code> will be thrown. Otherwise, 4270the method will return <code>undefined</code>.</p> 4271<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>; 4272 4273<span class="hljs-keyword">try</span> { 4274 <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>); 4275 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'can read/write'</span>); 4276} <span class="hljs-keyword">catch</span> (err) { 4277 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'no access!'</span>); 4278}</code></pre> 4279<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> 4280<div class="api_metadata"> 4281<details class="changelog"><summary>History</summary> 4282<table> 4283<tbody><tr><th>Version</th><th>Changes</th></tr> 4284<tr><td>v7.0.0</td> 4285<td><p>The passed <code>options</code> object will never be modified.</p></td></tr> 4286<tr><td>v5.0.0</td> 4287<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 4288<tr><td>v0.6.7</td> 4289<td><p><span>Added in: v0.6.7</span></p></td></tr> 4290</tbody></table> 4291</details> 4292</div> 4293<ul> 4294<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> 4295<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> 4296<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> 4297<ul> 4298<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> 4299<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> 4300<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> 4301</ul> 4302</li> 4303</ul> 4304<p>Synchronously append data to a file, creating the file if it does not yet 4305exist. <code>data</code> can be a string or a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 4306<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> 4307for more details.</p> 4308<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>; 4309 4310<span class="hljs-keyword">try</span> { 4311 <span class="hljs-title function_">appendFileSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'data to append'</span>); 4312 <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>); 4313} <span class="hljs-keyword">catch</span> (err) { 4314 <span class="hljs-comment">/* Handle the error */</span> 4315}</code></pre> 4316<p>If <code>options</code> is a string, then it specifies the encoding:</p> 4317<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>; 4318 4319<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> 4320<p>The <code>path</code> may be specified as a numeric file descriptor that has been opened 4321for appending (using <code>fs.open()</code> or <code>fs.openSync()</code>). The file descriptor will 4322not be closed automatically.</p> 4323<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>; 4324 4325<span class="hljs-keyword">let</span> fd; 4326 4327<span class="hljs-keyword">try</span> { 4328 fd = <span class="hljs-title function_">openSync</span>(<span class="hljs-string">'message.txt'</span>, <span class="hljs-string">'a'</span>); 4329 <span class="hljs-title function_">appendFileSync</span>(fd, <span class="hljs-string">'data to append'</span>, <span class="hljs-string">'utf8'</span>); 4330} <span class="hljs-keyword">catch</span> (err) { 4331 <span class="hljs-comment">/* Handle the error */</span> 4332} <span class="hljs-keyword">finally</span> { 4333 <span class="hljs-keyword">if</span> (fd !== <span class="hljs-literal">undefined</span>) 4334 <span class="hljs-title function_">closeSync</span>(fd); 4335}</code></pre> 4336<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> 4337<div class="api_metadata"> 4338<details class="changelog"><summary>History</summary> 4339<table> 4340<tbody><tr><th>Version</th><th>Changes</th></tr> 4341<tr><td>v7.6.0</td> 4342<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4343<tr><td>v0.6.7</td> 4344<td><p><span>Added in: v0.6.7</span></p></td></tr> 4345</tbody></table> 4346</details> 4347</div> 4348<ul> 4349<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> 4350<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> 4351</ul> 4352<p>For detailed information, see the documentation of the asynchronous version of 4353this API: <a href="#fs_fs_chmod_path_mode_callback"><code>fs.chmod()</code></a>.</p> 4354<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> 4355<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> 4356<div class="api_metadata"> 4357<details class="changelog"><summary>History</summary> 4358<table> 4359<tbody><tr><th>Version</th><th>Changes</th></tr> 4360<tr><td>v7.6.0</td> 4361<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4362<tr><td>v0.1.97</td> 4363<td><p><span>Added in: v0.1.97</span></p></td></tr> 4364</tbody></table> 4365</details> 4366</div> 4367<ul> 4368<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> 4369<li><code>uid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4370<li><code>gid</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4371</ul> 4372<p>Synchronously changes owner and group of a file. Returns <code>undefined</code>. 4373This is the synchronous version of <a href="#fs_fs_chown_path_uid_gid_callback"><code>fs.chown()</code></a>.</p> 4374<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> 4375<h4><code>fs.closeSync(fd)</code><span><a class="mark" href="#fs_fs_closesync_fd" id="fs_fs_closesync_fd">#</a></span></h4> 4376<div class="api_metadata"> 4377<span>Added in: v0.1.21</span> 4378</div> 4379<ul> 4380<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4381</ul> 4382<p>Closes the file descriptor. Returns <code>undefined</code>.</p> 4383<p>Calling <code>fs.closeSync()</code> on any file descriptor (<code>fd</code>) that is currently in use 4384through any other <code>fs</code> operation may lead to undefined behavior.</p> 4385<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> 4386<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> 4387<div class="api_metadata"> 4388<details class="changelog"><summary>History</summary> 4389<table> 4390<tbody><tr><th>Version</th><th>Changes</th></tr> 4391<tr><td>v14.0.0</td> 4392<td><p>Changed 'flags' argument to 'mode' and imposed stricter type validation.</p></td></tr> 4393<tr><td>v8.5.0</td> 4394<td><p><span>Added in: v8.5.0</span></p></td></tr> 4395</tbody></table> 4396</details> 4397</div> 4398<ul> 4399<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> 4400<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> 4401<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> 4402</ul> 4403<p>Synchronously copies <code>src</code> to <code>dest</code>. By default, <code>dest</code> is overwritten if it 4404already exists. Returns <code>undefined</code>. Node.js makes no guarantees about the 4405atomicity of the copy operation. If an error occurs after the destination file 4406has been opened for writing, Node.js will attempt to remove the destination.</p> 4407<p><code>mode</code> is an optional integer that specifies the behavior 4408of the copy operation. It is possible to create a mask consisting of the bitwise 4409OR of two or more values (e.g. 4410<code>fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE</code>).</p> 4411<ul> 4412<li><code>fs.constants.COPYFILE_EXCL</code>: The copy operation will fail if <code>dest</code> already 4413exists.</li> 4414<li><code>fs.constants.COPYFILE_FICLONE</code>: The copy operation will attempt to create a 4415copy-on-write reflink. If the platform does not support copy-on-write, then a 4416fallback copy mechanism is used.</li> 4417<li><code>fs.constants.COPYFILE_FICLONE_FORCE</code>: The copy operation will attempt to 4418create a copy-on-write reflink. If the platform does not support 4419copy-on-write, then the operation will fail.</li> 4420</ul> 4421<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>; 4422 4423<span class="hljs-comment">// destination.txt will be created or overwritten by default.</span> 4424<span class="hljs-title function_">copyFileSync</span>(<span class="hljs-string">'source.txt'</span>, <span class="hljs-string">'destination.txt'</span>); 4425<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>); 4426 4427<span class="hljs-comment">// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.</span> 4428<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> 4429<h4><code>fs.existsSync(path)</code><span><a class="mark" href="#fs_fs_existssync_path" id="fs_fs_existssync_path">#</a></span></h4> 4430<div class="api_metadata"> 4431<details class="changelog"><summary>History</summary> 4432<table> 4433<tbody><tr><th>Version</th><th>Changes</th></tr> 4434<tr><td>v7.6.0</td> 4435<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4436<tr><td>v0.1.21</td> 4437<td><p><span>Added in: v0.1.21</span></p></td></tr> 4438</tbody></table> 4439</details> 4440</div> 4441<ul> 4442<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> 4443<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 4444</ul> 4445<p>Returns <code>true</code> if the path exists, <code>false</code> otherwise.</p> 4446<p>For detailed information, see the documentation of the asynchronous version of 4447this API: <a href="#fs_fs_exists_path_callback"><code>fs.exists()</code></a>.</p> 4448<p><code>fs.exists()</code> is deprecated, but <code>fs.existsSync()</code> is not. The <code>callback</code> 4449parameter to <code>fs.exists()</code> accepts parameters that are inconsistent with other 4450Node.js callbacks. <code>fs.existsSync()</code> does not use a callback.</p> 4451<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>; 4452 4453<span class="hljs-keyword">if</span> (<span class="hljs-title function_">existsSync</span>(<span class="hljs-string">'/etc/passwd'</span>)) 4454 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'The path exists.'</span>);</code></pre> 4455<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> 4456<div class="api_metadata"> 4457<span>Added in: v0.4.7</span> 4458</div> 4459<ul> 4460<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4461<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> 4462</ul> 4463<p>Sets the permissions on the file. Returns <code>undefined</code>.</p> 4464<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> 4465<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> 4466<div class="api_metadata"> 4467<span>Added in: v0.4.7</span> 4468</div> 4469<ul> 4470<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4471<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> 4472<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> 4473</ul> 4474<p>Sets the owner of the file. Returns <code>undefined</code>.</p> 4475<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> 4476<h4><code>fs.fdatasyncSync(fd)</code><span><a class="mark" href="#fs_fs_fdatasyncsync_fd" id="fs_fs_fdatasyncsync_fd">#</a></span></h4> 4477<div class="api_metadata"> 4478<span>Added in: v0.1.96</span> 4479</div> 4480<ul> 4481<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4482</ul> 4483<p>Forces all currently queued I/O operations associated with the file to the 4484operating system's synchronized I/O completion state. Refer to the POSIX 4485<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> 4486<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> 4487<div class="api_metadata"> 4488<details class="changelog"><summary>History</summary> 4489<table> 4490<tbody><tr><th>Version</th><th>Changes</th></tr> 4491<tr><td>v10.5.0</td> 4492<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4493<tr><td>v0.1.95</td> 4494<td><p><span>Added in: v0.1.95</span></p></td></tr> 4495</tbody></table> 4496</details> 4497</div> 4498<ul> 4499<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4500<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4501<ul> 4502<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 4503<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> 4504</ul> 4505</li> 4506<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4507</ul> 4508<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the file descriptor.</p> 4509<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> 4510<h4><code>fs.fsyncSync(fd)</code><span><a class="mark" href="#fs_fs_fsyncsync_fd" id="fs_fs_fsyncsync_fd">#</a></span></h4> 4511<div class="api_metadata"> 4512<span>Added in: v0.1.96</span> 4513</div> 4514<ul> 4515<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4516</ul> 4517<p>Request that all data for the open file descriptor is flushed to the storage 4518device. The specific implementation is operating system and device specific. 4519Refer 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> 4520<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> 4521<div class="api_metadata"> 4522<span>Added in: v0.8.6</span> 4523</div> 4524<ul> 4525<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4526<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> 4527</ul> 4528<p>Truncates the file descriptor. Returns <code>undefined</code>.</p> 4529<p>For detailed information, see the documentation of the asynchronous version of 4530this API: <a href="#fs_fs_ftruncate_fd_len_callback"><code>fs.ftruncate()</code></a>.</p> 4531<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> 4532<div class="api_metadata"> 4533<details class="changelog"><summary>History</summary> 4534<table> 4535<tbody><tr><th>Version</th><th>Changes</th></tr> 4536<tr><td>v4.1.0</td> 4537<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 4538<tr><td>v0.4.2</td> 4539<td><p><span>Added in: v0.4.2</span></p></td></tr> 4540</tbody></table> 4541</details> 4542</div> 4543<ul> 4544<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4545<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> 4546<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> 4547</ul> 4548<p>Synchronous version of <a href="#fs_fs_futimes_fd_atime_mtime_callback"><code>fs.futimes()</code></a>. Returns <code>undefined</code>.</p> 4549<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> 4550<div class="api_metadata"> 4551<span>Deprecated since: v0.4.7</span> 4552</div> 4553<ul> 4554<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> 4555<li><code>mode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4556</ul> 4557<p>Changes the permissions on a symbolic link. Returns <code>undefined</code>.</p> 4558<p>This method is only implemented on macOS.</p> 4559<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> 4560<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> 4561<div class="api_metadata"> 4562<details class="changelog"><summary>History</summary> 4563<table> 4564<tbody><tr><th>Version</th><th>Changes</th></tr> 4565<tr><td>v10.6.0</td> 4566<td><p>This API is no longer deprecated.</p></td></tr> 4567<tr><td>v0.4.7</td> 4568<td><p>Documentation-only deprecation.</p></td></tr> 4569</tbody></table> 4570</details> 4571</div> 4572<ul> 4573<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> 4574<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> 4575<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> 4576</ul> 4577<p>Set the owner for the path. Returns <code>undefined</code>.</p> 4578<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> 4579<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> 4580<div class="api_metadata"> 4581<span>Added in: v14.5.0, v12.19.0</span> 4582</div> 4583<ul> 4584<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> 4585<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> 4586<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> 4587</ul> 4588<p>Change the file system timestamps of the symbolic link referenced by <code>path</code>. 4589Returns <code>undefined</code>, or throws an exception when parameters are incorrect or 4590the operation fails. This is the synchronous version of <a href="#fs_fs_lutimes_path_atime_mtime_callback"><code>fs.lutimes()</code></a>.</p> 4591<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> 4592<div class="api_metadata"> 4593<details class="changelog"><summary>History</summary> 4594<table> 4595<tbody><tr><th>Version</th><th>Changes</th></tr> 4596<tr><td>v7.6.0</td> 4597<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> 4598<tr><td>v0.1.31</td> 4599<td><p><span>Added in: v0.1.31</span></p></td></tr> 4600</tbody></table> 4601</details> 4602</div> 4603<ul> 4604<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> 4605<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> 4606</ul> 4607<p>Creates a new link from the <code>existingPath</code> to the <code>newPath</code>. See the POSIX 4608<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> 4609<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> 4610<div class="api_metadata"> 4611<details class="changelog"><summary>History</summary> 4612<table> 4613<tbody><tr><th>Version</th><th>Changes</th></tr> 4614<tr><td>v14.17.0</td> 4615<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> 4616<tr><td>v10.5.0</td> 4617<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 4618<tr><td>v7.6.0</td> 4619<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4620<tr><td>v0.1.30</td> 4621<td><p><span>Added in: v0.1.30</span></p></td></tr> 4622</tbody></table> 4623</details> 4624</div> 4625<ul> 4626<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> 4627<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4628<ul> 4629<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 4630<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> 4631<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 4632if no file system entry exists, rather than returning <code>undefined</code>. 4633<strong>Default:</strong> <code>true</code>.</li> 4634</ul> 4635</li> 4636<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 4637</ul> 4638<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> 4639<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> 4640<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> 4641<div class="api_metadata"> 4642<details class="changelog"><summary>History</summary> 4643<table> 4644<tbody><tr><th>Version</th><th>Changes</th></tr> 4645<tr><td>v13.11.0, v12.17.0</td> 4646<td><p>In <code>recursive</code> mode, the first created path is returned now.</p></td></tr> 4647<tr><td>v10.12.0</td> 4648<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> 4649<tr><td>v7.6.0</td> 4650<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4651<tr><td>v0.1.21</td> 4652<td><p><span>Added in: v0.1.21</span></p></td></tr> 4653</tbody></table> 4654</details> 4655</div> 4656<ul> 4657<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> 4658<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> 4659<ul> 4660<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> 4661<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> 4662</ul> 4663</li> 4664<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> 4665</ul> 4666<p>Synchronously creates a directory. Returns <code>undefined</code>, or if <code>recursive</code> is 4667<code>true</code>, the first directory path created. 4668This is the synchronous version of <a href="#fs_fs_mkdir_path_options_callback"><code>fs.mkdir()</code></a>.</p> 4669<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> 4670<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> 4671<div class="api_metadata"> 4672<details class="changelog"><summary>History</summary> 4673<table> 4674<tbody><tr><th>Version</th><th>Changes</th></tr> 4675<tr><td>v14.18.0</td> 4676<td><p>The <code>prefix</code> parameter now accepts an empty string.</p></td></tr> 4677<tr><td>v5.10.0</td> 4678<td><p><span>Added in: v5.10.0</span></p></td></tr> 4679</tbody></table> 4680</details> 4681</div> 4682<ul> 4683<li><code>prefix</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4684<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> 4685<ul> 4686<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> 4687</ul> 4688</li> 4689<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 4690</ul> 4691<p>Returns the created directory path.</p> 4692<p>For detailed information, see the documentation of the asynchronous version of 4693this API: <a href="#fs_fs_mkdtemp_prefix_options_callback"><code>fs.mkdtemp()</code></a>.</p> 4694<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4695object with an <code>encoding</code> property specifying the character encoding to use.</p> 4696<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> 4697<div class="api_metadata"> 4698<details class="changelog"><summary>History</summary> 4699<table> 4700<tbody><tr><th>Version</th><th>Changes</th></tr> 4701<tr><td>v13.1.0, v12.16.0</td> 4702<td><p>The <code>bufferSize</code> option was introduced.</p></td></tr> 4703<tr><td>v12.12.0</td> 4704<td><p><span>Added in: v12.12.0</span></p></td></tr> 4705</tbody></table> 4706</details> 4707</div> 4708<ul> 4709<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> 4710<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4711<ul> 4712<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> 4713<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 4714internally when reading from the directory. Higher values lead to better 4715performance but higher memory usage. <strong>Default:</strong> <code>32</code></li> 4716</ul> 4717</li> 4718<li>Returns: <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a></li> 4719</ul> 4720<p>Synchronously open a directory. See <a href="http://man7.org/linux/man-pages/man3/opendir.3.html"><code>opendir(3)</code></a>.</p> 4721<p>Creates an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>, which contains all further functions for reading from 4722and cleaning up the directory.</p> 4723<p>The <code>encoding</code> option sets the encoding for the <code>path</code> while opening the 4724directory and subsequent read operations.</p> 4725<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> 4726<div class="api_metadata"> 4727<details class="changelog"><summary>History</summary> 4728<table> 4729<tbody><tr><th>Version</th><th>Changes</th></tr> 4730<tr><td>v11.1.0</td> 4731<td><p>The <code>flags</code> argument is now optional and defaults to <code>'r'</code>.</p></td></tr> 4732<tr><td>v9.9.0</td> 4733<td><p>The <code>as</code> and <code>as+</code> flags are supported now.</p></td></tr> 4734<tr><td>v7.6.0</td> 4735<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4736<tr><td>v0.1.21</td> 4737<td><p><span>Added in: v0.1.21</span></p></td></tr> 4738</tbody></table> 4739</details> 4740</div> 4741<ul> 4742<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> 4743<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>. 4744See <a href="#fs_file_system_flags">support of file system <code>flags</code></a>.</li> 4745<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> 4746<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4747</ul> 4748<p>Returns an integer representing the file descriptor.</p> 4749<p>For detailed information, see the documentation of the asynchronous version of 4750this API: <a href="#fs_fs_open_path_flags_mode_callback"><code>fs.open()</code></a>.</p> 4751<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> 4752<div class="api_metadata"> 4753<details class="changelog"><summary>History</summary> 4754<table> 4755<tbody><tr><th>Version</th><th>Changes</th></tr> 4756<tr><td>v10.10.0</td> 4757<td><p>New option <code>withFileTypes</code> was added.</p></td></tr> 4758<tr><td>v7.6.0</td> 4759<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4760<tr><td>v0.1.21</td> 4761<td><p><span>Added in: v0.1.21</span></p></td></tr> 4762</tbody></table> 4763</details> 4764</div> 4765<ul> 4766<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> 4767<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> 4768<ul> 4769<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> 4770<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> 4771</ul> 4772</li> 4773<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> 4774</ul> 4775<p>Reads the contents of the directory.</p> 4776<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> 4777<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4778object with an <code>encoding</code> property specifying the character encoding to use for 4779the filenames returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4780the filenames returned will be passed as <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> objects.</p> 4781<p>If <code>options.withFileTypes</code> is set to <code>true</code>, the result will contain 4782<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a> objects.</p> 4783<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> 4784<div class="api_metadata"> 4785<details class="changelog"><summary>History</summary> 4786<table> 4787<tbody><tr><th>Version</th><th>Changes</th></tr> 4788<tr><td>v7.6.0</td> 4789<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4790<tr><td>v5.0.0</td> 4791<td><p>The <code>path</code> parameter can be a file descriptor now.</p></td></tr> 4792<tr><td>v0.1.8</td> 4793<td><p><span>Added in: v0.1.8</span></p></td></tr> 4794</tbody></table> 4795</details> 4796</div> 4797<ul> 4798<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> 4799<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> 4800<ul> 4801<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> 4802<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> 4803</ul> 4804</li> 4805<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> 4806</ul> 4807<p>Returns the contents of the <code>path</code>.</p> 4808<p>For detailed information, see the documentation of the asynchronous version of 4809this API: <a href="#fs_fs_readfile_path_options_callback"><code>fs.readFile()</code></a>.</p> 4810<p>If the <code>encoding</code> option is specified then this function returns a 4811string. Otherwise it returns a buffer.</p> 4812<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 4813<code>fs.readFileSync()</code> is platform-specific.</p> 4814<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>; 4815 4816<span class="hljs-comment">// macOS, Linux, and Windows</span> 4817<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); 4818<span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, read <directory>]</span> 4819 4820<span class="hljs-comment">// FreeBSD</span> 4821<span class="hljs-title function_">readFileSync</span>(<span class="hljs-string">'<directory>'</span>); <span class="hljs-comment">// => <data></span></code></pre> 4822<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> 4823<div class="api_metadata"> 4824<details class="changelog"><summary>History</summary> 4825<table> 4826<tbody><tr><th>Version</th><th>Changes</th></tr> 4827<tr><td>v7.6.0</td> 4828<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4829<tr><td>v0.1.31</td> 4830<td><p><span>Added in: v0.1.31</span></p></td></tr> 4831</tbody></table> 4832</details> 4833</div> 4834<ul> 4835<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> 4836<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> 4837<ul> 4838<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> 4839</ul> 4840</li> 4841<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> 4842</ul> 4843<p>Returns the symbolic link's string value.</p> 4844<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> 4845<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4846object with an <code>encoding</code> property specifying the character encoding to use for 4847the link path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4848the link path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4849<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> 4850<div class="api_metadata"> 4851<details class="changelog"><summary>History</summary> 4852<table> 4853<tbody><tr><th>Version</th><th>Changes</th></tr> 4854<tr><td>v10.10.0</td> 4855<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 4856<tr><td>v6.0.0</td> 4857<td><p>The <code>length</code> parameter can now be <code>0</code>.</p></td></tr> 4858<tr><td>v0.1.21</td> 4859<td><p><span>Added in: v0.1.21</span></p></td></tr> 4860</tbody></table> 4861</details> 4862</div> 4863<ul> 4864<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4865<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> 4866<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4867<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4868<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> 4869<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4870</ul> 4871<p>Returns the number of <code>bytesRead</code>.</p> 4872<p>For detailed information, see the documentation of the asynchronous version of 4873this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4874<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> 4875<div class="api_metadata"> 4876<details class="changelog"><summary>History</summary> 4877<table> 4878<tbody><tr><th>Version</th><th>Changes</th></tr> 4879<tr><td>v13.13.0, v12.17.0</td> 4880<td><p><span>Added in: v13.13.0, v12.17.0</span></p></td></tr> 4881<tr><td>v13.13.0, v12.17.0</td> 4882<td><p>Options object can be passed in to make offset, length and position optional.</p></td></tr> 4883</tbody></table> 4884</details> 4885</div> 4886<ul> 4887<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4888<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> 4889<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 4890<ul> 4891<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> 4892<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> 4893<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> 4894</ul> 4895</li> 4896<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 4897</ul> 4898<p>Returns the number of <code>bytesRead</code>.</p> 4899<p>Similar to the above <code>fs.readSync</code> function, this version takes an optional <code>options</code> object. 4900If no <code>options</code> object is specified, it will default with the above values.</p> 4901<p>For detailed information, see the documentation of the asynchronous version of 4902this API: <a href="#fs_fs_read_fd_buffer_offset_length_position_callback"><code>fs.read()</code></a>.</p> 4903<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> 4904<div class="api_metadata"> 4905<span>Added in: v13.13.0, v12.17.0</span> 4906</div> 4907<ul> 4908<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4909<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 4910<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 4911<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> 4912</ul> 4913<p>For detailed information, see the documentation of the asynchronous version of 4914this API: <a href="#fs_fs_readv_fd_buffers_position_callback"><code>fs.readv()</code></a>.</p> 4915<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> 4916<div class="api_metadata"> 4917<details class="changelog"><summary>History</summary> 4918<table> 4919<tbody><tr><th>Version</th><th>Changes</th></tr> 4920<tr><td>v8.0.0</td> 4921<td><p>Pipe/Socket resolve support was added.</p></td></tr> 4922<tr><td>v7.6.0</td> 4923<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4924<tr><td>v6.4.0</td> 4925<td><p>Calling <code>realpathSync</code> now works again for various edge cases on Windows.</p></td></tr> 4926<tr><td>v6.0.0</td> 4927<td><p>The <code>cache</code> parameter was removed.</p></td></tr> 4928<tr><td>v0.1.31</td> 4929<td><p><span>Added in: v0.1.31</span></p></td></tr> 4930</tbody></table> 4931</details> 4932</div> 4933<ul> 4934<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> 4935<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> 4936<ul> 4937<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> 4938</ul> 4939</li> 4940<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> 4941</ul> 4942<p>Returns the resolved pathname.</p> 4943<p>For detailed information, see the documentation of the asynchronous version of 4944this API: <a href="#fs_fs_realpath_path_options_callback"><code>fs.realpath()</code></a>.</p> 4945<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> 4946<div class="api_metadata"> 4947<span>Added in: v9.2.0</span> 4948</div> 4949<ul> 4950<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> 4951<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> 4952<ul> 4953<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> 4954</ul> 4955</li> 4956<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> 4957</ul> 4958<p>Synchronous <a href="http://man7.org/linux/man-pages/man3/realpath.3.html"><code>realpath(3)</code></a>.</p> 4959<p>Only paths that can be converted to UTF8 strings are supported.</p> 4960<p>The optional <code>options</code> argument can be a string specifying an encoding, or an 4961object with an <code>encoding</code> property specifying the character encoding to use for 4962the path returned. If the <code>encoding</code> is set to <code>'buffer'</code>, 4963the path returned will be passed as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> object.</p> 4964<p>On Linux, when Node.js is linked against musl libc, the procfs file system must 4965be mounted on <code>/proc</code> in order for this function to work. Glibc does not have 4966this restriction.</p> 4967<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> 4968<div class="api_metadata"> 4969<details class="changelog"><summary>History</summary> 4970<table> 4971<tbody><tr><th>Version</th><th>Changes</th></tr> 4972<tr><td>v7.6.0</td> 4973<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> 4974<tr><td>v0.1.21</td> 4975<td><p><span>Added in: v0.1.21</span></p></td></tr> 4976</tbody></table> 4977</details> 4978</div> 4979<ul> 4980<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> 4981<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> 4982</ul> 4983<p>Renames the file from <code>oldPath</code> to <code>newPath</code>. Returns <code>undefined</code>.</p> 4984<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> 4985<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> 4986<div class="api_metadata"> 4987<details class="changelog"><summary>History</summary> 4988<table> 4989<tbody><tr><th>Version</th><th>Changes</th></tr> 4990<tr><td>v14.14.0</td> 4991<td><p>The <code>recursive</code> option is deprecated, use <code>fs.rmSync</code> instead.</p></td></tr> 4992<tr><td>v13.3.0, v12.16.0</td> 4993<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> 4994<tr><td>v12.10.0</td> 4995<td><p>The <code>recursive</code>, <code>maxBusyTries</code>, and <code>emfileWait</code> options are now supported.</p></td></tr> 4996<tr><td>v7.6.0</td> 4997<td><p>The <code>path</code> parameters can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 4998<tr><td>v0.1.21</td> 4999<td><p><span>Added in: v0.1.21</span></p></td></tr> 5000</tbody></table> 5001</details> 5002</div> 5003<ul> 5004<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> 5005<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5006<ul> 5007<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 5008<code>EPERM</code> error is encountered, Node.js retries the operation with a linear 5009backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5010represents the number of retries. This option is ignored if the <code>recursive</code> 5011option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5012<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 5013recursive mode, errors are not reported if <code>path</code> does not exist, and 5014operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5015<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 5016retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5017<strong>Default:</strong> <code>100</code>.</li> 5018</ul> 5019</li> 5020</ul> 5021<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"><code>rmdir(2)</code></a>. Returns <code>undefined</code>.</p> 5022<p>Using <code>fs.rmdirSync()</code> on a file (not a directory) results in an <code>ENOENT</code> error 5023on Windows and an <code>ENOTDIR</code> error on POSIX.</p> 5024<p>Setting <code>recursive</code> to <code>true</code> results in behavior similar to the Unix command 5025<code>rm -rf</code>: an error will not be raised for paths that do not exist, and paths 5026that represent files will be deleted. The permissive behavior of the 5027<code>recursive</code> option is deprecated, <code>ENOTDIR</code> and <code>ENOENT</code> will be thrown in 5028the future.</p> 5029<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> 5030<div class="api_metadata"> 5031<span>Added in: v14.14.0</span> 5032</div> 5033<ul> 5034<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> 5035<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5036<ul> 5037<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 5038not exist. <strong>Default:</strong> <code>false</code>.</li> 5039<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 5040<code>EPERM</code> error is encountered, Node.js will retry the operation with a linear 5041backoff wait of <code>retryDelay</code> milliseconds longer on each try. This option 5042represents the number of retries. This option is ignored if the <code>recursive</code> 5043option is not <code>true</code>. <strong>Default:</strong> <code>0</code>.</li> 5044<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 5045recursive mode operations are retried on failure. <strong>Default:</strong> <code>false</code>.</li> 5046<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 5047retries. This option is ignored if the <code>recursive</code> option is not <code>true</code>. 5048<strong>Default:</strong> <code>100</code>.</li> 5049</ul> 5050</li> 5051</ul> 5052<p>Synchronously removes files and directories (modeled on the standard POSIX <code>rm</code> 5053utility). Returns <code>undefined</code>.</p> 5054<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> 5055<div class="api_metadata"> 5056<details class="changelog"><summary>History</summary> 5057<table> 5058<tbody><tr><th>Version</th><th>Changes</th></tr> 5059<tr><td>v14.17.0</td> 5060<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> 5061<tr><td>v10.5.0</td> 5062<td><p>Accepts an additional <code>options</code> object to specify whether the numeric values returned should be bigint.</p></td></tr> 5063<tr><td>v7.6.0</td> 5064<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5065<tr><td>v0.1.21</td> 5066<td><p><span>Added in: v0.1.21</span></p></td></tr> 5067</tbody></table> 5068</details> 5069</div> 5070<ul> 5071<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> 5072<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 5073<ul> 5074<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 5075<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> 5076<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 5077if no file system entry exists, rather than returning <code>undefined</code>. 5078<strong>Default:</strong> <code>true</code>.</li> 5079</ul> 5080</li> 5081<li>Returns: <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a></li> 5082</ul> 5083<p>Retrieves the <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> for the path.</p> 5084<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> 5085<div class="api_metadata"> 5086<details class="changelog"><summary>History</summary> 5087<table> 5088<tbody><tr><th>Version</th><th>Changes</th></tr> 5089<tr><td>v12.0.0</td> 5090<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> 5091<tr><td>v7.6.0</td> 5092<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> 5093<tr><td>v0.1.31</td> 5094<td><p><span>Added in: v0.1.31</span></p></td></tr> 5095</tbody></table> 5096</details> 5097</div> 5098<ul> 5099<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> 5100<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> 5101<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5102</ul> 5103<p>Returns <code>undefined</code>.</p> 5104<p>For detailed information, see the documentation of the asynchronous version of 5105this API: <a href="#fs_fs_symlink_target_path_type_callback"><code>fs.symlink()</code></a>.</p> 5106<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> 5107<div class="api_metadata"> 5108<span>Added in: v0.8.6</span> 5109</div> 5110<ul> 5111<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> 5112<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> 5113</ul> 5114<p>Truncates the file. Returns <code>undefined</code>. A file descriptor can also be 5115passed as the first argument. In this case, <code>fs.ftruncateSync()</code> is called.</p> 5116<p>Passing a file descriptor is deprecated and may result in an error being thrown 5117in the future.</p> 5118<h4><code>fs.unlinkSync(path)</code><span><a class="mark" href="#fs_fs_unlinksync_path" id="fs_fs_unlinksync_path">#</a></span></h4> 5119<div class="api_metadata"> 5120<details class="changelog"><summary>History</summary> 5121<table> 5122<tbody><tr><th>Version</th><th>Changes</th></tr> 5123<tr><td>v7.6.0</td> 5124<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5125<tr><td>v0.1.21</td> 5126<td><p><span>Added in: v0.1.21</span></p></td></tr> 5127</tbody></table> 5128</details> 5129</div> 5130<ul> 5131<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> 5132</ul> 5133<p>Synchronous <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"><code>unlink(2)</code></a>. Returns <code>undefined</code>.</p> 5134<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> 5135<div class="api_metadata"> 5136<details class="changelog"><summary>History</summary> 5137<table> 5138<tbody><tr><th>Version</th><th>Changes</th></tr> 5139<tr><td>v8.0.0</td> 5140<td><p><code>NaN</code>, <code>Infinity</code>, and <code>-Infinity</code> are no longer valid time specifiers.</p></td></tr> 5141<tr><td>v7.6.0</td> 5142<td><p>The <code>path</code> parameter can be a WHATWG <code>URL</code> object using <code>file:</code> protocol.</p></td></tr> 5143<tr><td>v4.1.0</td> 5144<td><p>Numeric strings, <code>NaN</code> and <code>Infinity</code> are now allowed time specifiers.</p></td></tr> 5145<tr><td>v0.4.2</td> 5146<td><p><span>Added in: v0.4.2</span></p></td></tr> 5147</tbody></table> 5148</details> 5149</div> 5150<ul> 5151<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> 5152<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> 5153<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> 5154</ul> 5155<p>Returns <code>undefined</code>.</p> 5156<p>For detailed information, see the documentation of the asynchronous version of 5157this API: <a href="#fs_fs_utimes_path_atime_mtime_callback"><code>fs.utimes()</code></a>.</p> 5158<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> 5159<div class="api_metadata"> 5160<details class="changelog"><summary>History</summary> 5161<table> 5162<tbody><tr><th>Version</th><th>Changes</th></tr> 5163<tr><td>v14.12.0</td> 5164<td><p>The <code>data</code> parameter will stringify an object with an explicit <code>toString</code> function.</p></td></tr> 5165<tr><td>v14.0.0</td> 5166<td><p>The <code>data</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5167<tr><td>v10.10.0</td> 5168<td><p>The <code>data</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5169<tr><td>v7.4.0</td> 5170<td><p>The <code>data</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5171<tr><td>v5.0.0</td> 5172<td><p>The <code>file</code> parameter can be a file descriptor now.</p></td></tr> 5173<tr><td>v0.1.29</td> 5174<td><p><span>Added in: v0.1.29</span></p></td></tr> 5175</tbody></table> 5176</details> 5177</div> 5178<ul> 5179<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> 5180<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> 5181<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> 5182<ul> 5183<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> 5184<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> 5185<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> 5186</ul> 5187</li> 5188</ul> 5189<p>Returns <code>undefined</code>.</p> 5190<p>If <code>data</code> is a plain object, it must have an own (not inherited) <code>toString</code> 5191function property.</p> 5192<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> 5193for more details.</p> 5194<p>For detailed information, see the documentation of the asynchronous version of 5195this API: <a href="#fs_fs_writefile_file_data_options_callback"><code>fs.writeFile()</code></a>.</p> 5196<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> 5197<div class="api_metadata"> 5198<details class="changelog"><summary>History</summary> 5199<table> 5200<tbody><tr><th>Version</th><th>Changes</th></tr> 5201<tr><td>v14.0.0</td> 5202<td><p>The <code>buffer</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5203<tr><td>v10.10.0</td> 5204<td><p>The <code>buffer</code> parameter can now be any <code>TypedArray</code> or a <code>DataView</code>.</p></td></tr> 5205<tr><td>v7.4.0</td> 5206<td><p>The <code>buffer</code> parameter can now be a <code>Uint8Array</code>.</p></td></tr> 5207<tr><td>v7.2.0</td> 5208<td><p>The <code>offset</code> and <code>length</code> parameters are optional now.</p></td></tr> 5209<tr><td>v0.1.21</td> 5210<td><p><span>Added in: v0.1.21</span></p></td></tr> 5211</tbody></table> 5212</details> 5213</div> 5214<ul> 5215<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5216<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> 5217<li><code>offset</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5218<li><code>length</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5219<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5220<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> 5221</ul> 5222<p>For detailed information, see the documentation of the asynchronous version of 5223this API: <a href="#fs_fs_write_fd_buffer_offset_length_position_callback"><code>fs.write(fd, buffer...)</code></a>.</p> 5224<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> 5225<div class="api_metadata"> 5226<details class="changelog"><summary>History</summary> 5227<table> 5228<tbody><tr><th>Version</th><th>Changes</th></tr> 5229<tr><td>v14.0.0</td> 5230<td><p>The <code>string</code> parameter won't coerce unsupported input to strings anymore.</p></td></tr> 5231<tr><td>v7.2.0</td> 5232<td><p>The <code>position</code> parameter is optional now.</p></td></tr> 5233<tr><td>v0.11.5</td> 5234<td><p><span>Added in: v0.11.5</span></p></td></tr> 5235</tbody></table> 5236</details> 5237</div> 5238<ul> 5239<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5240<li><code>string</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5241<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5242<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5243<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> 5244</ul> 5245<p>For detailed information, see the documentation of the asynchronous version of 5246this API: <a href="#fs_fs_write_fd_string_position_encoding_callback"><code>fs.write(fd, string...)</code></a>.</p> 5247<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> 5248<div class="api_metadata"> 5249<span>Added in: v12.9.0</span> 5250</div> 5251<ul> 5252<li><code>fd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5253<li><code>buffers</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView" class="type"><ArrayBufferView[]></a></li> 5254<li><code>position</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 5255<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> 5256</ul> 5257<p>For detailed information, see the documentation of the asynchronous version of 5258this API: <a href="#fs_fs_writev_fd_buffers_position_callback"><code>fs.writev()</code></a>.</p> 5259</section><section><h3>Common Objects<span><a class="mark" href="#fs_common_objects" id="fs_common_objects">#</a></span></h3> 5260<p>The common objects are shared by all of the file system API variants 5261(promise, callback, and synchronous).</p> 5262<h4>Class: <code>fs.Dir</code><span><a class="mark" href="#fs_class_fs_dir" id="fs_class_fs_dir">#</a></span></h4> 5263<div class="api_metadata"> 5264<span>Added in: v12.12.0</span> 5265</div> 5266<p>A class representing a directory stream.</p> 5267<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 5268<a href="#fs_fspromises_opendir_path_options"><code>fsPromises.opendir()</code></a>.</p> 5269<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>; 5270 5271<span class="hljs-keyword">try</span> { 5272 <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>); 5273 <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) 5274 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(dirent.<span class="hljs-property">name</span>); 5275} <span class="hljs-keyword">catch</span> (err) { 5276 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 5277}</code></pre> 5278<p>When using the async iterator, the <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> object will be automatically 5279closed after the iterator exits.</p> 5280<h5><code>dir.close()</code><span><a class="mark" href="#fs_dir_close" id="fs_dir_close">#</a></span></h5> 5281<div class="api_metadata"> 5282<span>Added in: v12.12.0</span> 5283</div> 5284<ul> 5285<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 5286</ul> 5287<p>Asynchronously close the directory's underlying resource handle. 5288Subsequent reads will result in errors.</p> 5289<p>A promise is returned that will be resolved after the resource has been 5290closed.</p> 5291<h5><code>dir.close(callback)</code><span><a class="mark" href="#fs_dir_close_callback" id="fs_dir_close_callback">#</a></span></h5> 5292<div class="api_metadata"> 5293<span>Added in: v12.12.0</span> 5294</div> 5295<ul> 5296<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5297<ul> 5298<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5299</ul> 5300</li> 5301</ul> 5302<p>Asynchronously close the directory's underlying resource handle. 5303Subsequent reads will result in errors.</p> 5304<p>The <code>callback</code> will be called after the resource handle has been closed.</p> 5305<h5><code>dir.closeSync()</code><span><a class="mark" href="#fs_dir_closesync" id="fs_dir_closesync">#</a></span></h5> 5306<div class="api_metadata"> 5307<span>Added in: v12.12.0</span> 5308</div> 5309<p>Synchronously close the directory's underlying resource handle. 5310Subsequent reads will result in errors.</p> 5311<h5><code>dir.path</code><span><a class="mark" href="#fs_dir_path" id="fs_dir_path">#</a></span></h5> 5312<div class="api_metadata"> 5313<span>Added in: v12.12.0</span> 5314</div> 5315<ul> 5316<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 5317</ul> 5318<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>, 5319<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> 5320<h5><code>dir.read()</code><span><a class="mark" href="#fs_dir_read" id="fs_dir_read">#</a></span></h5> 5321<div class="api_metadata"> 5322<span>Added in: v12.12.0</span> 5323</div> 5324<ul> 5325<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> 5326</ul> 5327<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 5328<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5329<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> 5330if there are no more directory entries to read.</p> 5331<p>Directory entries returned by this function are in no particular order as 5332provided by the operating system's underlying directory mechanisms. 5333Entries added or removed while iterating over the directory might not be 5334included in the iteration results.</p> 5335<h5><code>dir.read(callback)</code><span><a class="mark" href="#fs_dir_read_callback" id="fs_dir_read_callback">#</a></span></h5> 5336<div class="api_metadata"> 5337<span>Added in: v12.12.0</span> 5338</div> 5339<ul> 5340<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5341<ul> 5342<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5343<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> 5344</ul> 5345</li> 5346</ul> 5347<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 5348<a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>.</p> 5349<p>After the read is completed, the <code>callback</code> will be called with an 5350<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> 5351<p>Directory entries returned by this function are in no particular order as 5352provided by the operating system's underlying directory mechanisms. 5353Entries added or removed while iterating over the directory might not be 5354included in the iteration results.</p> 5355<h5><code>dir.readSync()</code><span><a class="mark" href="#fs_dir_readsync" id="fs_dir_readsync">#</a></span></h5> 5356<div class="api_metadata"> 5357<span>Added in: v12.12.0</span> 5358</div> 5359<ul> 5360<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> 5361</ul> 5362<p>Synchronously read the next directory entry as an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. See the 5363POSIX <a href="http://man7.org/linux/man-pages/man3/readdir.3.html"><code>readdir(3)</code></a> documentation for more detail.</p> 5364<p>If there are no more directory entries to read, <code>null</code> will be returned.</p> 5365<p>Directory entries returned by this function are in no particular order as 5366provided by the operating system's underlying directory mechanisms. 5367Entries added or removed while iterating over the directory might not be 5368included in the iteration results.</p> 5369<h5><code>dir[Symbol.asyncIterator]()</code><span><a class="mark" href="#fs_dir_symbol_asynciterator" id="fs_dir_symbol_asynciterator">#</a></span></h5> 5370<div class="api_metadata"> 5371<span>Added in: v12.12.0</span> 5372</div> 5373<ul> 5374<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> 5375</ul> 5376<p>Asynchronously iterates over the directory until all entries have 5377been 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> 5378<p>Entries returned by the async iterator are always an <a href="fs.html#fs_class_fs_dirent" class="type"><fs.Dirent></a>. 5379The <code>null</code> case from <code>dir.read()</code> is handled internally.</p> 5380<p>See <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a> for an example.</p> 5381<p>Directory entries returned by this iterator are in no particular order as 5382provided by the operating system's underlying directory mechanisms. 5383Entries added or removed while iterating over the directory might not be 5384included in the iteration results.</p> 5385<h4>Class: <code>fs.Dirent</code><span><a class="mark" href="#fs_class_fs_dirent" id="fs_class_fs_dirent">#</a></span></h4> 5386<div class="api_metadata"> 5387<span>Added in: v10.10.0</span> 5388</div> 5389<p>A representation of a directory entry, which can be a file or a subdirectory 5390within the directory, as returned by reading from an <a href="fs.html#fs_class_fs_dir" class="type"><fs.Dir></a>. The 5391directory entry is a combination of the file name and file type pairs.</p> 5392<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 5393the <code>withFileTypes</code> option set to <code>true</code>, the resulting array is filled with 5394<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> 5395<h5><code>dirent.isBlockDevice()</code><span><a class="mark" href="#fs_dirent_isblockdevice" id="fs_dirent_isblockdevice">#</a></span></h5> 5396<div class="api_metadata"> 5397<span>Added in: v10.10.0</span> 5398</div> 5399<ul> 5400<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5401</ul> 5402<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> 5403<h5><code>dirent.isCharacterDevice()</code><span><a class="mark" href="#fs_dirent_ischaracterdevice" id="fs_dirent_ischaracterdevice">#</a></span></h5> 5404<div class="api_metadata"> 5405<span>Added in: v10.10.0</span> 5406</div> 5407<ul> 5408<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5409</ul> 5410<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> 5411<h5><code>dirent.isDirectory()</code><span><a class="mark" href="#fs_dirent_isdirectory" id="fs_dirent_isdirectory">#</a></span></h5> 5412<div class="api_metadata"> 5413<span>Added in: v10.10.0</span> 5414</div> 5415<ul> 5416<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5417</ul> 5418<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 5419directory.</p> 5420<h5><code>dirent.isFIFO()</code><span><a class="mark" href="#fs_dirent_isfifo" id="fs_dirent_isfifo">#</a></span></h5> 5421<div class="api_metadata"> 5422<span>Added in: v10.10.0</span> 5423</div> 5424<ul> 5425<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5426</ul> 5427<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 5428(FIFO) pipe.</p> 5429<h5><code>dirent.isFile()</code><span><a class="mark" href="#fs_dirent_isfile" id="fs_dirent_isfile">#</a></span></h5> 5430<div class="api_metadata"> 5431<span>Added in: v10.10.0</span> 5432</div> 5433<ul> 5434<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5435</ul> 5436<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> 5437<h5><code>dirent.isSocket()</code><span><a class="mark" href="#fs_dirent_issocket" id="fs_dirent_issocket">#</a></span></h5> 5438<div class="api_metadata"> 5439<span>Added in: v10.10.0</span> 5440</div> 5441<ul> 5442<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5443</ul> 5444<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> 5445<h5><code>dirent.isSymbolicLink()</code><span><a class="mark" href="#fs_dirent_issymboliclink" id="fs_dirent_issymboliclink">#</a></span></h5> 5446<div class="api_metadata"> 5447<span>Added in: v10.10.0</span> 5448</div> 5449<ul> 5450<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5451</ul> 5452<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> 5453<h5><code>dirent.name</code><span><a class="mark" href="#fs_dirent_name" id="fs_dirent_name">#</a></span></h5> 5454<div class="api_metadata"> 5455<span>Added in: v10.10.0</span> 5456</div> 5457<ul> 5458<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> 5459</ul> 5460<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 5461value is determined by the <code>options.encoding</code> passed to <a href="#fs_fs_readdir_path_options_callback"><code>fs.readdir()</code></a> or 5462<a href="#fs_fs_readdirsync_path_options"><code>fs.readdirSync()</code></a>.</p> 5463<h4>Class: <code>fs.FSWatcher</code><span><a class="mark" href="#fs_class_fs_fswatcher" id="fs_class_fs_fswatcher">#</a></span></h4> 5464<div class="api_metadata"> 5465<span>Added in: v0.5.8</span> 5466</div> 5467<ul> 5468<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5469</ul> 5470<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> 5471object.</p> 5472<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 5473file is modified.</p> 5474<h5>Event: <code>'change'</code><span><a class="mark" href="#fs_event_change" id="fs_event_change">#</a></span></h5> 5475<div class="api_metadata"> 5476<span>Added in: v0.5.8</span> 5477</div> 5478<ul> 5479<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> 5480<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> 5481</ul> 5482<p>Emitted when something changes in a watched directory or file. 5483See more details in <a href="#fs_fs_watch_filename_options_listener"><code>fs.watch()</code></a>.</p> 5484<p>The <code>filename</code> argument may not be provided depending on operating system 5485support. If <code>filename</code> is provided, it will be provided as a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> if 5486<code>fs.watch()</code> is called with its <code>encoding</code> option set to <code>'buffer'</code>, otherwise 5487<code>filename</code> will be a UTF-8 string.</p> 5488<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>; 5489<span class="hljs-comment">// Example when handled through fs.watch() listener</span> 5490<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> { 5491 <span class="hljs-keyword">if</span> (filename) { 5492 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(filename); 5493 <span class="hljs-comment">// Prints: <Buffer ...></span> 5494 } 5495});</code></pre> 5496<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close" id="fs_event_close">#</a></span></h5> 5497<div class="api_metadata"> 5498<span>Added in: v10.0.0</span> 5499</div> 5500<p>Emitted when the watcher stops watching for changes. The closed 5501<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5502<h5>Event: <code>'error'</code><span><a class="mark" href="#fs_event_error" id="fs_event_error">#</a></span></h5> 5503<div class="api_metadata"> 5504<span>Added in: v0.5.8</span> 5505</div> 5506<ul> 5507<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5508</ul> 5509<p>Emitted when an error occurs while watching the file. The errored 5510<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable in the event handler.</p> 5511<h5><code>watcher.close()</code><span><a class="mark" href="#fs_watcher_close" id="fs_watcher_close">#</a></span></h5> 5512<div class="api_metadata"> 5513<span>Added in: v0.5.8</span> 5514</div> 5515<p>Stop watching for changes on the given <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a>. Once stopped, the 5516<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object is no longer usable.</p> 5517<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref" id="fs_watcher_ref">#</a></span></h5> 5518<div class="api_metadata"> 5519<span>Added in: v14.3.0, v12.20.0</span> 5520</div> 5521<ul> 5522<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5523</ul> 5524<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5525<a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5526no effect.</p> 5527<p>By default, all <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> objects are "ref'ed", making it normally 5528unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5529called previously.</p> 5530<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref" id="fs_watcher_unref">#</a></span></h5> 5531<div class="api_metadata"> 5532<span>Added in: v14.3.0, v12.20.0</span> 5533</div> 5534<ul> 5535<li>Returns: <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a></li> 5536</ul> 5537<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 5538event loop to remain active. If there is no other activity keeping the 5539event loop running, the process may exit before the <a href="fs.html#fs_class_fs_fswatcher" class="type"><fs.FSWatcher></a> object's 5540callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5541no effect.</p> 5542<h4>Class: <code>fs.StatWatcher</code><span><a class="mark" href="#fs_class_fs_statwatcher" id="fs_class_fs_statwatcher">#</a></span></h4> 5543<div class="api_metadata"> 5544<span>Added in: v14.3.0, v12.20.0</span> 5545</div> 5546<ul> 5547<li>Extends <a href="events.html#events_class_eventemitter" class="type"><EventEmitter></a></li> 5548</ul> 5549<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> 5550object.</p> 5551<h5><code>watcher.ref()</code><span><a class="mark" href="#fs_watcher_ref_1" id="fs_watcher_ref_1">#</a></span></h5> 5552<div class="api_metadata"> 5553<span>Added in: v14.3.0, v12.20.0</span> 5554</div> 5555<ul> 5556<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5557</ul> 5558<p>When called, requests that the Node.js event loop <em>not</em> exit so long as the 5559<a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> is active. Calling <code>watcher.ref()</code> multiple times will have 5560no effect.</p> 5561<p>By default, all <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> objects are "ref'ed", making it normally 5562unnecessary to call <code>watcher.ref()</code> unless <code>watcher.unref()</code> had been 5563called previously.</p> 5564<h5><code>watcher.unref()</code><span><a class="mark" href="#fs_watcher_unref_1" id="fs_watcher_unref_1">#</a></span></h5> 5565<div class="api_metadata"> 5566<span>Added in: v14.3.0, v12.20.0</span> 5567</div> 5568<ul> 5569<li>Returns: <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a></li> 5570</ul> 5571<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 5572event loop to remain active. If there is no other activity keeping the 5573event loop running, the process may exit before the <a href="fs.html#fs_class_fs_statwatcher" class="type"><fs.StatWatcher></a> object's 5574callback is invoked. Calling <code>watcher.unref()</code> multiple times will have 5575no effect.</p> 5576<h4>Class: <code>fs.ReadStream</code><span><a class="mark" href="#fs_class_fs_readstream" id="fs_class_fs_readstream">#</a></span></h4> 5577<div class="api_metadata"> 5578<span>Added in: v0.1.93</span> 5579</div> 5580<ul> 5581<li>Extends: <a href="stream.html#stream_class_stream_readable" class="type"><stream.Readable></a></li> 5582</ul> 5583<p>Instances of <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> are created and returned using the 5584<a href="#fs_fs_createreadstream_path_options"><code>fs.createReadStream()</code></a> function.</p> 5585<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_1" id="fs_event_close_1">#</a></span></h5> 5586<div class="api_metadata"> 5587<span>Added in: v0.1.93</span> 5588</div> 5589<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> 5590<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open" id="fs_event_open">#</a></span></h5> 5591<div class="api_metadata"> 5592<span>Added in: v0.1.93</span> 5593</div> 5594<ul> 5595<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> 5596</ul> 5597<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a>'s file descriptor has been opened.</p> 5598<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready" id="fs_event_ready">#</a></span></h5> 5599<div class="api_metadata"> 5600<span>Added in: v9.11.0</span> 5601</div> 5602<p>Emitted when the <a href="fs.html#fs_class_fs_readstream" class="type"><fs.ReadStream></a> is ready to be used.</p> 5603<p>Fires immediately after <code>'open'</code>.</p> 5604<h5><code>readStream.bytesRead</code><span><a class="mark" href="#fs_readstream_bytesread" id="fs_readstream_bytesread">#</a></span></h5> 5605<div class="api_metadata"> 5606<span>Added in: v6.4.0</span> 5607</div> 5608<ul> 5609<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 5610</ul> 5611<p>The number of bytes that have been read so far.</p> 5612<h5><code>readStream.path</code><span><a class="mark" href="#fs_readstream_path" id="fs_readstream_path">#</a></span></h5> 5613<div class="api_metadata"> 5614<span>Added in: v0.1.93</span> 5615</div> 5616<ul> 5617<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> 5618</ul> 5619<p>The path to the file the stream is reading from as specified in the first 5620argument to <code>fs.createReadStream()</code>. If <code>path</code> is passed as a string, then 5621<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 5622<code>readStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 5623<h5><code>readStream.pending</code><span><a class="mark" href="#fs_readstream_pending" id="fs_readstream_pending">#</a></span></h5> 5624<div class="api_metadata"> 5625<span>Added in: v11.2.0, v10.16.0</span> 5626</div> 5627<ul> 5628<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5629</ul> 5630<p>This property is <code>true</code> if the underlying file has not been opened yet, 5631i.e. before the <code>'ready'</code> event is emitted.</p> 5632<h4>Class: <code>fs.Stats</code><span><a class="mark" href="#fs_class_fs_stats" id="fs_class_fs_stats">#</a></span></h4> 5633<div class="api_metadata"> 5634<details class="changelog"><summary>History</summary> 5635<table> 5636<tbody><tr><th>Version</th><th>Changes</th></tr> 5637<tr><td>v8.1.0</td> 5638<td><p>Added times as numbers.</p></td></tr> 5639<tr><td>v0.1.21</td> 5640<td><p><span>Added in: v0.1.21</span></p></td></tr> 5641</tbody></table> 5642</details> 5643</div> 5644<p>A <a href="fs.html#fs_class_fs_stats" class="type"><fs.Stats></a> object provides information about a file.</p> 5645<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 5646their synchronous counterparts are of this type. 5647If <code>bigint</code> in the <code>options</code> passed to those methods is true, the numeric values 5648will be <code>bigint</code> instead of <code>number</code>, and the object will contain additional 5649nanosecond-precision properties suffixed with <code>Ns</code>.</p> 5650<pre><code class="language-console">Stats { 5651 dev: 2114, 5652 ino: 48064969, 5653 mode: 33188, 5654 nlink: 1, 5655 uid: 85, 5656 gid: 100, 5657 rdev: 0, 5658 size: 527, 5659 blksize: 4096, 5660 blocks: 8, 5661 atimeMs: 1318289051000.1, 5662 mtimeMs: 1318289051000.1, 5663 ctimeMs: 1318289051000.1, 5664 birthtimeMs: 1318289051000.1, 5665 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5666 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5667 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5668 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5669<p><code>bigint</code> version:</p> 5670<pre><code class="language-console">BigIntStats { 5671 dev: 2114n, 5672 ino: 48064969n, 5673 mode: 33188n, 5674 nlink: 1n, 5675 uid: 85n, 5676 gid: 100n, 5677 rdev: 0n, 5678 size: 527n, 5679 blksize: 4096n, 5680 blocks: 8n, 5681 atimeMs: 1318289051000n, 5682 mtimeMs: 1318289051000n, 5683 ctimeMs: 1318289051000n, 5684 birthtimeMs: 1318289051000n, 5685 atimeNs: 1318289051000000000n, 5686 mtimeNs: 1318289051000000000n, 5687 ctimeNs: 1318289051000000000n, 5688 birthtimeNs: 1318289051000000000n, 5689 atime: Mon, 10 Oct 2011 23:24:11 GMT, 5690 mtime: Mon, 10 Oct 2011 23:24:11 GMT, 5691 ctime: Mon, 10 Oct 2011 23:24:11 GMT, 5692 birthtime: Mon, 10 Oct 2011 23:24:11 GMT }</code></pre> 5693<h5><code>stats.isBlockDevice()</code><span><a class="mark" href="#fs_stats_isblockdevice" id="fs_stats_isblockdevice">#</a></span></h5> 5694<div class="api_metadata"> 5695<span>Added in: v0.1.10</span> 5696</div> 5697<ul> 5698<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5699</ul> 5700<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> 5701<h5><code>stats.isCharacterDevice()</code><span><a class="mark" href="#fs_stats_ischaracterdevice" id="fs_stats_ischaracterdevice">#</a></span></h5> 5702<div class="api_metadata"> 5703<span>Added in: v0.1.10</span> 5704</div> 5705<ul> 5706<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5707</ul> 5708<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> 5709<h5><code>stats.isDirectory()</code><span><a class="mark" href="#fs_stats_isdirectory" id="fs_stats_isdirectory">#</a></span></h5> 5710<div class="api_metadata"> 5711<span>Added in: v0.1.10</span> 5712</div> 5713<ul> 5714<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5715</ul> 5716<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> 5717<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 5718always return <code>false</code>. This is because <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a> returns information 5719about a symbolic link itself and not the path it resolves to.</p> 5720<h5><code>stats.isFIFO()</code><span><a class="mark" href="#fs_stats_isfifo" id="fs_stats_isfifo">#</a></span></h5> 5721<div class="api_metadata"> 5722<span>Added in: v0.1.10</span> 5723</div> 5724<ul> 5725<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5726</ul> 5727<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) 5728pipe.</p> 5729<h5><code>stats.isFile()</code><span><a class="mark" href="#fs_stats_isfile" id="fs_stats_isfile">#</a></span></h5> 5730<div class="api_metadata"> 5731<span>Added in: v0.1.10</span> 5732</div> 5733<ul> 5734<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5735</ul> 5736<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> 5737<h5><code>stats.isSocket()</code><span><a class="mark" href="#fs_stats_issocket" id="fs_stats_issocket">#</a></span></h5> 5738<div class="api_metadata"> 5739<span>Added in: v0.1.10</span> 5740</div> 5741<ul> 5742<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5743</ul> 5744<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> 5745<h5><code>stats.isSymbolicLink()</code><span><a class="mark" href="#fs_stats_issymboliclink" id="fs_stats_issymboliclink">#</a></span></h5> 5746<div class="api_metadata"> 5747<span>Added in: v0.1.10</span> 5748</div> 5749<ul> 5750<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 5751</ul> 5752<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> 5753<p>This method is only valid when using <a href="#fs_fs_lstat_path_options_callback"><code>fs.lstat()</code></a>.</p> 5754<h5><code>stats.dev</code><span><a class="mark" href="#fs_stats_dev" id="fs_stats_dev">#</a></span></h5> 5755<ul> 5756<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> 5757</ul> 5758<p>The numeric identifier of the device containing the file.</p> 5759<h5><code>stats.ino</code><span><a class="mark" href="#fs_stats_ino" id="fs_stats_ino">#</a></span></h5> 5760<ul> 5761<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> 5762</ul> 5763<p>The file system specific "Inode" number for the file.</p> 5764<h5><code>stats.mode</code><span><a class="mark" href="#fs_stats_mode" id="fs_stats_mode">#</a></span></h5> 5765<ul> 5766<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> 5767</ul> 5768<p>A bit-field describing the file type and mode.</p> 5769<h5><code>stats.nlink</code><span><a class="mark" href="#fs_stats_nlink" id="fs_stats_nlink">#</a></span></h5> 5770<ul> 5771<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> 5772</ul> 5773<p>The number of hard-links that exist for the file.</p> 5774<h5><code>stats.uid</code><span><a class="mark" href="#fs_stats_uid" id="fs_stats_uid">#</a></span></h5> 5775<ul> 5776<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> 5777</ul> 5778<p>The numeric user identifier of the user that owns the file (POSIX).</p> 5779<h5><code>stats.gid</code><span><a class="mark" href="#fs_stats_gid" id="fs_stats_gid">#</a></span></h5> 5780<ul> 5781<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> 5782</ul> 5783<p>The numeric group identifier of the group that owns the file (POSIX).</p> 5784<h5><code>stats.rdev</code><span><a class="mark" href="#fs_stats_rdev" id="fs_stats_rdev">#</a></span></h5> 5785<ul> 5786<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> 5787</ul> 5788<p>A numeric device identifier if the file represents a device.</p> 5789<h5><code>stats.size</code><span><a class="mark" href="#fs_stats_size" id="fs_stats_size">#</a></span></h5> 5790<ul> 5791<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> 5792</ul> 5793<p>The size of the file in bytes.</p> 5794<h5><code>stats.blksize</code><span><a class="mark" href="#fs_stats_blksize" id="fs_stats_blksize">#</a></span></h5> 5795<ul> 5796<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> 5797</ul> 5798<p>The file system block size for i/o operations.</p> 5799<h5><code>stats.blocks</code><span><a class="mark" href="#fs_stats_blocks" id="fs_stats_blocks">#</a></span></h5> 5800<ul> 5801<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> 5802</ul> 5803<p>The number of blocks allocated for this file.</p> 5804<h5><code>stats.atimeMs</code><span><a class="mark" href="#fs_stats_atimems" id="fs_stats_atimems">#</a></span></h5> 5805<div class="api_metadata"> 5806<span>Added in: v8.1.0</span> 5807</div> 5808<ul> 5809<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> 5810</ul> 5811<p>The timestamp indicating the last time this file was accessed expressed in 5812milliseconds since the POSIX Epoch.</p> 5813<h5><code>stats.mtimeMs</code><span><a class="mark" href="#fs_stats_mtimems" id="fs_stats_mtimems">#</a></span></h5> 5814<div class="api_metadata"> 5815<span>Added in: v8.1.0</span> 5816</div> 5817<ul> 5818<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> 5819</ul> 5820<p>The timestamp indicating the last time this file was modified expressed in 5821milliseconds since the POSIX Epoch.</p> 5822<h5><code>stats.ctimeMs</code><span><a class="mark" href="#fs_stats_ctimems" id="fs_stats_ctimems">#</a></span></h5> 5823<div class="api_metadata"> 5824<span>Added in: v8.1.0</span> 5825</div> 5826<ul> 5827<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> 5828</ul> 5829<p>The timestamp indicating the last time the file status was changed expressed 5830in milliseconds since the POSIX Epoch.</p> 5831<h5><code>stats.birthtimeMs</code><span><a class="mark" href="#fs_stats_birthtimems" id="fs_stats_birthtimems">#</a></span></h5> 5832<div class="api_metadata"> 5833<span>Added in: v8.1.0</span> 5834</div> 5835<ul> 5836<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> 5837</ul> 5838<p>The timestamp indicating the creation time of this file expressed in 5839milliseconds since the POSIX Epoch.</p> 5840<h5><code>stats.atimeNs</code><span><a class="mark" href="#fs_stats_atimens" id="fs_stats_atimens">#</a></span></h5> 5841<div class="api_metadata"> 5842<span>Added in: v12.10.0</span> 5843</div> 5844<ul> 5845<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5846</ul> 5847<p>Only present when <code>bigint: true</code> is passed into the method that generates 5848the object. 5849The timestamp indicating the last time this file was accessed expressed in 5850nanoseconds since the POSIX Epoch.</p> 5851<h5><code>stats.mtimeNs</code><span><a class="mark" href="#fs_stats_mtimens" id="fs_stats_mtimens">#</a></span></h5> 5852<div class="api_metadata"> 5853<span>Added in: v12.10.0</span> 5854</div> 5855<ul> 5856<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5857</ul> 5858<p>Only present when <code>bigint: true</code> is passed into the method that generates 5859the object. 5860The timestamp indicating the last time this file was modified expressed in 5861nanoseconds since the POSIX Epoch.</p> 5862<h5><code>stats.ctimeNs</code><span><a class="mark" href="#fs_stats_ctimens" id="fs_stats_ctimens">#</a></span></h5> 5863<div class="api_metadata"> 5864<span>Added in: v12.10.0</span> 5865</div> 5866<ul> 5867<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5868</ul> 5869<p>Only present when <code>bigint: true</code> is passed into the method that generates 5870the object. 5871The timestamp indicating the last time the file status was changed expressed 5872in nanoseconds since the POSIX Epoch.</p> 5873<h5><code>stats.birthtimeNs</code><span><a class="mark" href="#fs_stats_birthtimens" id="fs_stats_birthtimens">#</a></span></h5> 5874<div class="api_metadata"> 5875<span>Added in: v12.10.0</span> 5876</div> 5877<ul> 5878<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt" class="type"><bigint></a></li> 5879</ul> 5880<p>Only present when <code>bigint: true</code> is passed into the method that generates 5881the object. 5882The timestamp indicating the creation time of this file expressed in 5883nanoseconds since the POSIX Epoch.</p> 5884<h5><code>stats.atime</code><span><a class="mark" href="#fs_stats_atime" id="fs_stats_atime">#</a></span></h5> 5885<div class="api_metadata"> 5886<span>Added in: v0.11.13</span> 5887</div> 5888<ul> 5889<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5890</ul> 5891<p>The timestamp indicating the last time this file was accessed.</p> 5892<h5><code>stats.mtime</code><span><a class="mark" href="#fs_stats_mtime" id="fs_stats_mtime">#</a></span></h5> 5893<div class="api_metadata"> 5894<span>Added in: v0.11.13</span> 5895</div> 5896<ul> 5897<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5898</ul> 5899<p>The timestamp indicating the last time this file was modified.</p> 5900<h5><code>stats.ctime</code><span><a class="mark" href="#fs_stats_ctime" id="fs_stats_ctime">#</a></span></h5> 5901<div class="api_metadata"> 5902<span>Added in: v0.11.13</span> 5903</div> 5904<ul> 5905<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5906</ul> 5907<p>The timestamp indicating the last time the file status was changed.</p> 5908<h5><code>stats.birthtime</code><span><a class="mark" href="#fs_stats_birthtime" id="fs_stats_birthtime">#</a></span></h5> 5909<div class="api_metadata"> 5910<span>Added in: v0.11.13</span> 5911</div> 5912<ul> 5913<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date" class="type"><Date></a></li> 5914</ul> 5915<p>The timestamp indicating the creation time of this file.</p> 5916<h5>Stat time values<span><a class="mark" href="#fs_stat_time_values" id="fs_stat_time_values">#</a></span></h5> 5917<p>The <code>atimeMs</code>, <code>mtimeMs</code>, <code>ctimeMs</code>, <code>birthtimeMs</code> properties are 5918numeric values that hold the corresponding times in milliseconds. Their 5919precision is platform specific. When <code>bigint: true</code> is passed into the 5920method that generates the object, the properties will be <a href="https://tc39.github.io/proposal-bigint">bigints</a>, 5921otherwise they will be <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type">numbers</a>.</p> 5922<p>The <code>atimeNs</code>, <code>mtimeNs</code>, <code>ctimeNs</code>, <code>birthtimeNs</code> properties are 5923<a href="https://tc39.github.io/proposal-bigint">bigints</a> that hold the corresponding times in nanoseconds. They are 5924only present when <code>bigint: true</code> is passed into the method that generates 5925the object. Their precision is platform specific.</p> 5926<p><code>atime</code>, <code>mtime</code>, <code>ctime</code>, and <code>birthtime</code> are 5927<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 5928<code>Date</code> and number values are not connected. Assigning a new number value, or 5929mutating the <code>Date</code> value, will not be reflected in the corresponding alternate 5930representation.</p> 5931<p>The times in the stat object have the following semantics:</p> 5932<ul> 5933<li><code>atime</code> "Access Time": Time when file data last accessed. Changed 5934by 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> 5935<li><code>mtime</code> "Modified Time": Time when file data last modified. 5936Changed 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> 5937<li><code>ctime</code> "Change Time": Time when file status was last changed 5938(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>, 5939<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>, 5940<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> 5941<li><code>birthtime</code> "Birth Time": Time of file creation. Set once when the 5942file is created. On filesystems where birthtime is not available, 5943this field may instead hold either the <code>ctime</code> or 5944<code>1970-01-01T00:00Z</code> (ie, Unix epoch timestamp <code>0</code>). This value may be greater 5945than <code>atime</code> or <code>mtime</code> in this case. On Darwin and other FreeBSD variants, 5946also set if the <code>atime</code> is explicitly set to an earlier value than the current 5947<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> 5948</ul> 5949<p>Prior to Node.js 0.12, the <code>ctime</code> held the <code>birthtime</code> on Windows systems. As 5950of 0.12, <code>ctime</code> is not "creation time", and on Unix systems, it never was.</p> 5951<h4>Class: <code>fs.WriteStream</code><span><a class="mark" href="#fs_class_fs_writestream" id="fs_class_fs_writestream">#</a></span></h4> 5952<div class="api_metadata"> 5953<span>Added in: v0.1.93</span> 5954</div> 5955<ul> 5956<li>Extends <a href="stream.html#stream_class_stream_writable" class="type"><stream.Writable></a></li> 5957</ul> 5958<p>Instances of <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> are created and returned using the 5959<a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a> function.</p> 5960<h5>Event: <code>'close'</code><span><a class="mark" href="#fs_event_close_2" id="fs_event_close_2">#</a></span></h5> 5961<div class="api_metadata"> 5962<span>Added in: v0.1.93</span> 5963</div> 5964<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> 5965<h5>Event: <code>'open'</code><span><a class="mark" href="#fs_event_open_1" id="fs_event_open_1">#</a></span></h5> 5966<div class="api_metadata"> 5967<span>Added in: v0.1.93</span> 5968</div> 5969<ul> 5970<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> 5971</ul> 5972<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a>'s file is opened.</p> 5973<h5>Event: <code>'ready'</code><span><a class="mark" href="#fs_event_ready_1" id="fs_event_ready_1">#</a></span></h5> 5974<div class="api_metadata"> 5975<span>Added in: v9.11.0</span> 5976</div> 5977<p>Emitted when the <a href="fs.html#fs_class_fs_writestream" class="type"><fs.WriteStream></a> is ready to be used.</p> 5978<p>Fires immediately after <code>'open'</code>.</p> 5979<h5><code>writeStream.bytesWritten</code><span><a class="mark" href="#fs_writestream_byteswritten" id="fs_writestream_byteswritten">#</a></span></h5> 5980<div class="api_metadata"> 5981<span>Added in: v0.4.7</span> 5982</div> 5983<p>The number of bytes written so far. Does not include data that is still queued 5984for writing.</p> 5985<h5><code>writeStream.close([callback])</code><span><a class="mark" href="#fs_writestream_close_callback" id="fs_writestream_close_callback">#</a></span></h5> 5986<div class="api_metadata"> 5987<span>Added in: v0.9.4</span> 5988</div> 5989<ul> 5990<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 5991<ul> 5992<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 5993</ul> 5994</li> 5995</ul> 5996<p>Closes <code>writeStream</code>. Optionally accepts a 5997callback that will be executed once the <code>writeStream</code> 5998is closed.</p> 5999<h5><code>writeStream.path</code><span><a class="mark" href="#fs_writestream_path" id="fs_writestream_path">#</a></span></h5> 6000<div class="api_metadata"> 6001<span>Added in: v0.1.93</span> 6002</div> 6003<p>The path to the file the stream is writing to as specified in the first 6004argument to <a href="#fs_fs_createwritestream_path_options"><code>fs.createWriteStream()</code></a>. If <code>path</code> is passed as a string, then 6005<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 6006<code>writeStream.path</code> will be a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a>.</p> 6007<h5><code>writeStream.pending</code><span><a class="mark" href="#fs_writestream_pending" id="fs_writestream_pending">#</a></span></h5> 6008<div class="api_metadata"> 6009<span>Added in: v11.2.0</span> 6010</div> 6011<ul> 6012<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 6013</ul> 6014<p>This property is <code>true</code> if the underlying file has not been opened yet, 6015i.e. before the <code>'ready'</code> event is emitted.</p> 6016<h4><code>fs.constants</code><span><a class="mark" href="#fs_fs_constants" id="fs_fs_constants">#</a></span></h4> 6017<ul> 6018<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 6019</ul> 6020<p>Returns an object containing commonly used constants for file system 6021operations.</p> 6022<h5>FS constants<span><a class="mark" href="#fs_fs_constants_1" id="fs_fs_constants_1">#</a></span></h5> 6023<p>The following constants are exported by <code>fs.constants</code>.</p> 6024<p>Not every constant will be available on every operating system.</p> 6025<p>To use more than one constant, use the bitwise OR <code>|</code> operator.</p> 6026<p>Example:</p> 6027<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>; 6028 6029<span class="hljs-keyword">const</span> { 6030 <span class="hljs-variable constant_">O_RDWR</span>, 6031 <span class="hljs-variable constant_">O_CREAT</span>, 6032 <span class="hljs-variable constant_">O_EXCL</span> 6033} = constants; 6034 6035<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> { 6036 <span class="hljs-comment">// ...</span> 6037});</code></pre> 6038<h6>File access constants<span><a class="mark" href="#fs_file_access_constants" id="fs_file_access_constants">#</a></span></h6> 6039<p>The following constants are meant for use with <a href="#fs_fs_access_path_mode_callback"><code>fs.access()</code></a>.</p> 6040<table> 6041 <tbody><tr> 6042 <th>Constant</th> 6043 <th>Description</th> 6044 </tr> 6045 <tr> 6046 <td><code>F_OK</code></td> 6047 <td>Flag indicating that the file is visible to the calling process. 6048 This is useful for determining if a file exists, but says nothing 6049 about <code>rwx</code> permissions. Default if no mode is specified.</td> 6050 </tr> 6051 <tr> 6052 <td><code>R_OK</code></td> 6053 <td>Flag indicating that the file can be read by the calling process.</td> 6054 </tr> 6055 <tr> 6056 <td><code>W_OK</code></td> 6057 <td>Flag indicating that the file can be written by the calling 6058 process.</td> 6059 </tr> 6060 <tr> 6061 <td><code>X_OK</code></td> 6062 <td>Flag indicating that the file can be executed by the calling 6063 process. This has no effect on Windows 6064 (will behave like <code>fs.constants.F_OK</code>).</td> 6065 </tr> 6066</tbody></table> 6067<h6>File copy constants<span><a class="mark" href="#fs_file_copy_constants" id="fs_file_copy_constants">#</a></span></h6> 6068<p>The following constants are meant for use with <a href="#fs_fs_copyfile_src_dest_mode_callback"><code>fs.copyFile()</code></a>.</p> 6069<table> 6070 <tbody><tr> 6071 <th>Constant</th> 6072 <th>Description</th> 6073 </tr> 6074 <tr> 6075 <td><code>COPYFILE_EXCL</code></td> 6076 <td>If present, the copy operation will fail with an error if the 6077 destination path already exists.</td> 6078 </tr> 6079 <tr> 6080 <td><code>COPYFILE_FICLONE</code></td> 6081 <td>If present, the copy operation will attempt to create a 6082 copy-on-write reflink. If the underlying platform does not support 6083 copy-on-write, then a fallback copy mechanism is used.</td> 6084 </tr> 6085 <tr> 6086 <td><code>COPYFILE_FICLONE_FORCE</code></td> 6087 <td>If present, the copy operation will attempt to create a 6088 copy-on-write reflink. If the underlying platform does not support 6089 copy-on-write, then the operation will fail with an error.</td> 6090 </tr> 6091</tbody></table> 6092<h6>File open constants<span><a class="mark" href="#fs_file_open_constants" id="fs_file_open_constants">#</a></span></h6> 6093<p>The following constants are meant for use with <code>fs.open()</code>.</p> 6094<table> 6095 <tbody><tr> 6096 <th>Constant</th> 6097 <th>Description</th> 6098 </tr> 6099 <tr> 6100 <td><code>O_RDONLY</code></td> 6101 <td>Flag indicating to open a file for read-only access.</td> 6102 </tr> 6103 <tr> 6104 <td><code>O_WRONLY</code></td> 6105 <td>Flag indicating to open a file for write-only access.</td> 6106 </tr> 6107 <tr> 6108 <td><code>O_RDWR</code></td> 6109 <td>Flag indicating to open a file for read-write access.</td> 6110 </tr> 6111 <tr> 6112 <td><code>O_CREAT</code></td> 6113 <td>Flag indicating to create the file if it does not already exist.</td> 6114 </tr> 6115 <tr> 6116 <td><code>O_EXCL</code></td> 6117 <td>Flag indicating that opening a file should fail if the 6118 <code>O_CREAT</code> flag is set and the file already exists.</td> 6119 </tr> 6120 <tr> 6121 <td><code>O_NOCTTY</code></td> 6122 <td>Flag indicating that if path identifies a terminal device, opening the 6123 path shall not cause that terminal to become the controlling terminal for 6124 the process (if the process does not already have one).</td> 6125 </tr> 6126 <tr> 6127 <td><code>O_TRUNC</code></td> 6128 <td>Flag indicating that if the file exists and is a regular file, and the 6129 file is opened successfully for write access, its length shall be truncated 6130 to zero.</td> 6131 </tr> 6132 <tr> 6133 <td><code>O_APPEND</code></td> 6134 <td>Flag indicating that data will be appended to the end of the file.</td> 6135 </tr> 6136 <tr> 6137 <td><code>O_DIRECTORY</code></td> 6138 <td>Flag indicating that the open should fail if the path is not a 6139 directory.</td> 6140 </tr> 6141 <tr> 6142 <td><code>O_NOATIME</code></td> 6143 <td>Flag indicating reading accesses to the file system will no longer 6144 result in an update to the <code>atime</code> information associated with 6145 the file. This flag is available on Linux operating systems only.</td> 6146 </tr> 6147 <tr> 6148 <td><code>O_NOFOLLOW</code></td> 6149 <td>Flag indicating that the open should fail if the path is a symbolic 6150 link.</td> 6151 </tr> 6152 <tr> 6153 <td><code>O_SYNC</code></td> 6154 <td>Flag indicating that the file is opened for synchronized I/O with write 6155 operations waiting for file integrity.</td> 6156 </tr> 6157 <tr> 6158 <td><code>O_DSYNC</code></td> 6159 <td>Flag indicating that the file is opened for synchronized I/O with write 6160 operations waiting for data integrity.</td> 6161 </tr> 6162 <tr> 6163 <td><code>O_SYMLINK</code></td> 6164 <td>Flag indicating to open the symbolic link itself rather than the 6165 resource it is pointing to.</td> 6166 </tr> 6167 <tr> 6168 <td><code>O_DIRECT</code></td> 6169 <td>When set, an attempt will be made to minimize caching effects of file 6170 I/O.</td> 6171 </tr> 6172 <tr> 6173 <td><code>O_NONBLOCK</code></td> 6174 <td>Flag indicating to open the file in nonblocking mode when possible.</td> 6175 </tr> 6176 <tr> 6177 <td><code>UV_FS_O_FILEMAP</code></td> 6178 <td>When set, a memory file mapping is used to access the file. This flag 6179 is available on Windows operating systems only. On other operating systems, 6180 this flag is ignored.</td> 6181 </tr> 6182</tbody></table> 6183<h6>File type constants<span><a class="mark" href="#fs_file_type_constants" id="fs_file_type_constants">#</a></span></h6> 6184<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 6185<code>mode</code> property for determining a file's type.</p> 6186<table> 6187 <tbody><tr> 6188 <th>Constant</th> 6189 <th>Description</th> 6190 </tr> 6191 <tr> 6192 <td><code>S_IFMT</code></td> 6193 <td>Bit mask used to extract the file type code.</td> 6194 </tr> 6195 <tr> 6196 <td><code>S_IFREG</code></td> 6197 <td>File type constant for a regular file.</td> 6198 </tr> 6199 <tr> 6200 <td><code>S_IFDIR</code></td> 6201 <td>File type constant for a directory.</td> 6202 </tr> 6203 <tr> 6204 <td><code>S_IFCHR</code></td> 6205 <td>File type constant for a character-oriented device file.</td> 6206 </tr> 6207 <tr> 6208 <td><code>S_IFBLK</code></td> 6209 <td>File type constant for a block-oriented device file.</td> 6210 </tr> 6211 <tr> 6212 <td><code>S_IFIFO</code></td> 6213 <td>File type constant for a FIFO/pipe.</td> 6214 </tr> 6215 <tr> 6216 <td><code>S_IFLNK</code></td> 6217 <td>File type constant for a symbolic link.</td> 6218 </tr> 6219 <tr> 6220 <td><code>S_IFSOCK</code></td> 6221 <td>File type constant for a socket.</td> 6222 </tr> 6223</tbody></table> 6224<h6>File mode constants<span><a class="mark" href="#fs_file_mode_constants" id="fs_file_mode_constants">#</a></span></h6> 6225<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 6226<code>mode</code> property for determining the access permissions for a file.</p> 6227<table> 6228 <tbody><tr> 6229 <th>Constant</th> 6230 <th>Description</th> 6231 </tr> 6232 <tr> 6233 <td><code>S_IRWXU</code></td> 6234 <td>File mode indicating readable, writable, and executable by owner.</td> 6235 </tr> 6236 <tr> 6237 <td><code>S_IRUSR</code></td> 6238 <td>File mode indicating readable by owner.</td> 6239 </tr> 6240 <tr> 6241 <td><code>S_IWUSR</code></td> 6242 <td>File mode indicating writable by owner.</td> 6243 </tr> 6244 <tr> 6245 <td><code>S_IXUSR</code></td> 6246 <td>File mode indicating executable by owner.</td> 6247 </tr> 6248 <tr> 6249 <td><code>S_IRWXG</code></td> 6250 <td>File mode indicating readable, writable, and executable by group.</td> 6251 </tr> 6252 <tr> 6253 <td><code>S_IRGRP</code></td> 6254 <td>File mode indicating readable by group.</td> 6255 </tr> 6256 <tr> 6257 <td><code>S_IWGRP</code></td> 6258 <td>File mode indicating writable by group.</td> 6259 </tr> 6260 <tr> 6261 <td><code>S_IXGRP</code></td> 6262 <td>File mode indicating executable by group.</td> 6263 </tr> 6264 <tr> 6265 <td><code>S_IRWXO</code></td> 6266 <td>File mode indicating readable, writable, and executable by others.</td> 6267 </tr> 6268 <tr> 6269 <td><code>S_IROTH</code></td> 6270 <td>File mode indicating readable by others.</td> 6271 </tr> 6272 <tr> 6273 <td><code>S_IWOTH</code></td> 6274 <td>File mode indicating writable by others.</td> 6275 </tr> 6276 <tr> 6277 <td><code>S_IXOTH</code></td> 6278 <td>File mode indicating executable by others.</td> 6279 </tr> 6280</tbody></table> 6281</section><section><h3>Notes<span><a class="mark" href="#fs_notes" id="fs_notes">#</a></span></h3> 6282<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> 6283<p>Because they are executed asynchronously by the underlying thread pool, 6284there is no guaranteed ordering when using either the callback or 6285promise-based methods.</p> 6286<p>For example, the following is prone to error because the <code>fs.stat()</code> 6287operation might complete before the <code>fs.rename()</code> operation:</p> 6288<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> { 6289 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6290 <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'renamed complete'</span>); 6291}); 6292fs.<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> { 6293 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6294 <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>); 6295});</code></pre> 6296<p>It is important to correctly order the operations by awaiting the results 6297of one before invoking the other:</p> 6298 6299<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>; 6300 6301<span class="hljs-keyword">const</span> <span class="hljs-keyword">from</span> = <span class="hljs-string">'/tmp/hello'</span>; 6302<span class="hljs-keyword">const</span> to = <span class="hljs-string">'/tmp/world'</span>; 6303 6304<span class="hljs-keyword">try</span> { 6305 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6306 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6307 <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>); 6308} <span class="hljs-keyword">catch</span> (error) { 6309 <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>); 6310}</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>); 6311 6312(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params"><span class="hljs-keyword">from</span>, to</span>) { 6313 <span class="hljs-keyword">try</span> { 6314 <span class="hljs-keyword">await</span> <span class="hljs-title function_">rename</span>(<span class="hljs-keyword">from</span>, to); 6315 <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(to); 6316 <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>); 6317 } <span class="hljs-keyword">catch</span> (error) { 6318 <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>); 6319 } 6320})(<span class="hljs-string">'/tmp/hello'</span>, <span class="hljs-string">'/tmp/world'</span>);</code></pre> 6321<p>Or, when using the callback APIs, move the <code>fs.stat()</code> call into the callback 6322of the <code>fs.rename()</code> operation:</p> 6323 6324<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>; 6325 6326<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> { 6327 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6328 <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> { 6329 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6330 <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>); 6331 }); 6332});</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>); 6333 6334<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> { 6335 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6336 <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> { 6337 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6338 <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>); 6339 }); 6340});</code></pre> 6341<h4>File paths<span><a class="mark" href="#fs_file_paths" id="fs_file_paths">#</a></span></h4> 6342<p>Most <code>fs</code> operations accept file paths that may be specified in the form of 6343a 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> 6344<h5>String paths<span><a class="mark" href="#fs_string_paths" id="fs_string_paths">#</a></span></h5> 6345<p>String form paths are interpreted as UTF-8 character sequences identifying 6346the absolute or relative filename. Relative paths will be resolved relative 6347to the current working directory as determined by calling <code>process.cwd()</code>.</p> 6348<p>Example using an absolute path on POSIX:</p> 6349<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>; 6350 6351<span class="hljs-keyword">let</span> fd; 6352<span class="hljs-keyword">try</span> { 6353 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>); 6354 <span class="hljs-comment">// Do something with the file</span> 6355} <span class="hljs-keyword">finally</span> { 6356 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6357}</code></pre> 6358<p>Example using a relative path on POSIX (relative to <code>process.cwd()</code>):</p> 6359<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>; 6360 6361<span class="hljs-keyword">let</span> fd; 6362<span class="hljs-keyword">try</span> { 6363 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>); 6364 <span class="hljs-comment">// Do something with the file</span> 6365} <span class="hljs-keyword">finally</span> { 6366 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6367}</code></pre> 6368<h5>File URL paths<span><a class="mark" href="#fs_file_url_paths" id="fs_file_url_paths">#</a></span></h5> 6369<div class="api_metadata"> 6370<span>Added in: v7.6.0</span> 6371</div> 6372<p>For most <code>fs</code> module functions, the <code>path</code> or <code>filename</code> argument may be passed 6373as a <a href="url.html#url_the_whatwg_url_api" class="type"><URL></a> object using the <code>file:</code> protocol.</p> 6374<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>; 6375 6376<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> 6377<p><code>file:</code> URLs are always absolute paths.</p> 6378<h6>Platform-specific considerations<span><a class="mark" href="#fs_platform_specific_considerations" id="fs_platform_specific_considerations">#</a></span></h6> 6379<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> 6380<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 6381without a host name nor a drive letter will result in an error:</p> 6382<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>; 6383<span class="hljs-comment">// On Windows :</span> 6384 6385<span class="hljs-comment">// - WHATWG file URLs with hostname convert to UNC path</span> 6386<span class="hljs-comment">// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file</span> 6387<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>)); 6388 6389<span class="hljs-comment">// - WHATWG file URLs with drive letters convert to absolute path</span> 6390<span class="hljs-comment">// file:///C:/tmp/hello => C:\tmp\hello</span> 6391<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>)); 6392 6393<span class="hljs-comment">// - WHATWG file URLs without hostname must have a drive letters</span> 6394<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>)); 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:///c/p/a/t/h/file'</span>)); 6396<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute</span></code></pre> 6397<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 6398the drive letter. Using another separator will result in an error.</p> 6399<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 6400will result in an error:</p> 6401<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>; 6402<span class="hljs-comment">// On other platforms:</span> 6403 6404<span class="hljs-comment">// - WHATWG file URLs with hostname are unsupported</span> 6405<span class="hljs-comment">// file://hostname/p/a/t/h/file => throw!</span> 6406<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file://hostname/p/a/t/h/file'</span>)); 6407<span class="hljs-comment">// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute</span> 6408 6409<span class="hljs-comment">// - WHATWG file URLs convert to absolute path</span> 6410<span class="hljs-comment">// file:///tmp/hello => /tmp/hello</span> 6411<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> 6412<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 6413platforms:</p> 6414<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>; 6415 6416<span class="hljs-comment">// On Windows</span> 6417<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>)); 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-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6420\ or / characters */</span> 6421 6422<span class="hljs-comment">// On POSIX</span> 6423<span class="hljs-title function_">readFileSync</span>(<span class="hljs-keyword">new</span> <span class="hljs-title function_">URL</span>(<span class="hljs-string">'file:///p/a/t/h/%2F'</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-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6426/ characters */</span></code></pre> 6427<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> 6428<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>; 6429 6430<span class="hljs-comment">// On Windows</span> 6431<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>)); 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-comment">/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded 6434\ or / characters */</span></code></pre> 6435<h5>Buffer paths<span><a class="mark" href="#fs_buffer_paths" id="fs_buffer_paths">#</a></span></h5> 6436<p>Paths specified using a <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> are useful primarily on certain POSIX 6437operating systems that treat file paths as opaque byte sequences. On such 6438systems, it is possible for a single file path to contain sub-sequences that 6439use multiple character encodings. As with string paths, <a href="buffer.html#buffer_class_buffer" class="type"><Buffer></a> paths may 6440be relative or absolute:</p> 6441<p>Example using an absolute path on POSIX:</p> 6442<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>; 6443 6444<span class="hljs-keyword">let</span> fd; 6445<span class="hljs-keyword">try</span> { 6446 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>); 6447 <span class="hljs-comment">// Do something with the file</span> 6448} <span class="hljs-keyword">finally</span> { 6449 <span class="hljs-keyword">await</span> fd.<span class="hljs-title function_">close</span>(); 6450}</code></pre> 6451<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> 6452<p>On Windows, Node.js follows the concept of per-drive working directory. This 6453behavior can be observed when using a drive path without a backslash. For 6454example <code>fs.readdirSync('C:\\')</code> can potentially return a different result than 6455<code>fs.readdirSync('C:')</code>. For more information, see 6456<a href="https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths">this MSDN page</a>.</p> 6457<h4>File descriptors<span><a class="mark" href="#fs_file_descriptors_1" id="fs_file_descriptors_1">#</a></span></h4> 6458<p>On POSIX systems, for every process, the kernel maintains a table of currently 6459open files and resources. Each open file is assigned a simple numeric 6460identifier called a <em>file descriptor</em>. At the system-level, all file system 6461operations use these file descriptors to identify and track each specific 6462file. Windows systems use a different but conceptually similar mechanism for 6463tracking resources. To simplify things for users, Node.js abstracts away the 6464differences between operating systems and assigns all open files a numeric file 6465descriptor.</p> 6466<p>The callback-based <code>fs.open()</code>, and synchronous <code>fs.openSync()</code> methods open a 6467file and allocate a new file descriptor. Once allocated, the file descriptor may 6468be used to read data from, write data to, or request information about the file.</p> 6469<p>Operating systems limit the number of file descriptors that may be open 6470at any given time so it is critical to close the descriptor when operations 6471are completed. Failure to do so will result in a memory leak that will 6472eventually cause an application to crash.</p> 6473<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>; 6474 6475<span class="hljs-keyword">function</span> <span class="hljs-title function_">closeFd</span>(<span class="hljs-params">fd</span>) { 6476 <span class="hljs-title function_">close</span>(fd, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 6477 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6478 }); 6479} 6480 6481<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> { 6482 <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; 6483 <span class="hljs-keyword">try</span> { 6484 <span class="hljs-title function_">fstat</span>(fd, <span class="hljs-function">(<span class="hljs-params">err, stat</span>) =></span> { 6485 <span class="hljs-keyword">if</span> (err) { 6486 <span class="hljs-title function_">closeFd</span>(fd); 6487 <span class="hljs-keyword">throw</span> err; 6488 } 6489 6490 <span class="hljs-comment">// use stat</span> 6491 6492 <span class="hljs-title function_">closeFd</span>(fd); 6493 }); 6494 } <span class="hljs-keyword">catch</span> (err) { 6495 <span class="hljs-title function_">closeFd</span>(fd); 6496 <span class="hljs-keyword">throw</span> err; 6497 } 6498});</code></pre> 6499<p>The promise-based APIs use a <a href="fs.html#fs_class_filehandle" class="type"><FileHandle></a> object in place of the numeric 6500file descriptor. These objects are better managed by the system to ensure 6501that resources are not leaked. However, it is still required that they are 6502closed when operations are completed:</p> 6503<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>; 6504 6505<span class="hljs-keyword">let</span> file; 6506<span class="hljs-keyword">try</span> { 6507 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>); 6508 <span class="hljs-keyword">const</span> stat = <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">stat</span>(); 6509 <span class="hljs-comment">// use stat</span> 6510} <span class="hljs-keyword">finally</span> { 6511 <span class="hljs-keyword">await</span> file.<span class="hljs-title function_">close</span>(); 6512}</code></pre> 6513<h4>Threadpool usage<span><a class="mark" href="#fs_threadpool_usage" id="fs_threadpool_usage">#</a></span></h4> 6514<p>All callback and promise-based file system APIs ( with the exception of 6515<code>fs.FSWatcher()</code>) use libuv's threadpool. This can have surprising and negative 6516performance implications for some applications. See the 6517<a href="cli.html#cli_uv_threadpool_size_size"><code>UV_THREADPOOL_SIZE</code></a> documentation for more information.</p> 6518<h4>File system flags<span><a class="mark" href="#fs_file_system_flags" id="fs_file_system_flags">#</a></span></h4> 6519<p>The following flags are available wherever the <code>flag</code> option takes a 6520string.</p> 6521<ul> 6522<li> 6523<p><code>'a'</code>: Open file for appending. 6524The file is created if it does not exist.</p> 6525</li> 6526<li> 6527<p><code>'ax'</code>: Like <code>'a'</code> but fails if the path exists.</p> 6528</li> 6529<li> 6530<p><code>'a+'</code>: Open file for reading and appending. 6531The file is created if it does not exist.</p> 6532</li> 6533<li> 6534<p><code>'ax+'</code>: Like <code>'a+'</code> but fails if the path exists.</p> 6535</li> 6536<li> 6537<p><code>'as'</code>: Open file for appending in synchronous mode. 6538The file is created if it does not exist.</p> 6539</li> 6540<li> 6541<p><code>'as+'</code>: Open file for reading and appending in synchronous mode. 6542The file is created if it does not exist.</p> 6543</li> 6544<li> 6545<p><code>'r'</code>: Open file for reading. 6546An exception occurs if the file does not exist.</p> 6547</li> 6548<li> 6549<p><code>'r+'</code>: Open file for reading and writing. 6550An exception occurs if the file does not exist.</p> 6551</li> 6552<li> 6553<p><code>'rs+'</code>: Open file for reading and writing in synchronous mode. Instructs 6554the operating system to bypass the local file system cache.</p> 6555<p>This is primarily useful for opening files on NFS mounts as it allows 6556skipping the potentially stale local cache. It has a very real impact on 6557I/O performance so using this flag is not recommended unless it is needed.</p> 6558<p>This doesn't turn <code>fs.open()</code> or <code>fsPromises.open()</code> into a synchronous 6559blocking call. If synchronous operation is desired, something like 6560<code>fs.openSync()</code> should be used.</p> 6561</li> 6562<li> 6563<p><code>'w'</code>: Open file for writing. 6564The file is created (if it does not exist) or truncated (if it exists).</p> 6565</li> 6566<li> 6567<p><code>'wx'</code>: Like <code>'w'</code> but fails if the path exists.</p> 6568</li> 6569<li> 6570<p><code>'w+'</code>: Open file for reading and writing. 6571The file is created (if it does not exist) or truncated (if it exists).</p> 6572</li> 6573<li> 6574<p><code>'wx+'</code>: Like <code>'w+'</code> but fails if the path exists.</p> 6575</li> 6576</ul> 6577<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 6578are available from <code>fs.constants</code>. On Windows, flags are translated to 6579their equivalent ones where applicable, e.g. <code>O_WRONLY</code> to <code>FILE_GENERIC_WRITE</code>, 6580or <code>O_EXCL|O_CREAT</code> to <code>CREATE_NEW</code>, as accepted by <code>CreateFileW</code>.</p> 6581<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 6582return an error if the path already exists. On POSIX, if the path is a symbolic 6583link, using <code>O_EXCL</code> returns an error even if the link is to a path that does 6584not exist. The exclusive flag might not work with network file systems.</p> 6585<p>On Linux, positional writes don't work when the file is opened in append mode. 6586The kernel ignores the position argument and always appends the data to 6587the end of the file.</p> 6588<p>Modifying a file rather than replacing it may require the <code>flag</code> option to be 6589set to <code>'r+'</code> rather than the default <code>'w'</code>.</p> 6590<p>The behavior of some flags are platform-specific. As such, opening a directory 6591on macOS and Linux with the <code>'a+'</code> flag, as in the example below, will return an 6592error. In contrast, on Windows and FreeBSD, a file descriptor or a <code>FileHandle</code> 6593will be returned.</p> 6594<pre><code class="language-js"><span class="hljs-comment">// macOS and Linux</span> 6595fs.<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> { 6596 <span class="hljs-comment">// => [Error: EISDIR: illegal operation on a directory, open <directory>]</span> 6597}); 6598 6599<span class="hljs-comment">// Windows and FreeBSD</span> 6600fs.<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> { 6601 <span class="hljs-comment">// => null, <fd></span> 6602});</code></pre> 6603<p>On Windows, opening an existing hidden file using the <code>'w'</code> flag (either 6604through <code>fs.open()</code> or <code>fs.writeFile()</code> or <code>fsPromises.open()</code>) will fail with 6605<code>EPERM</code>. Existing hidden files can be opened for writing with the <code>'r+'</code> flag.</p> 6606<p>A call to <code>fs.ftruncate()</code> or <code>filehandle.truncate()</code> can be used to reset 6607the file contents.</p></section> 6608 <!-- API END --> 6609 </div> 6610 </div> 6611 </div> 6612 <script> 6613 'use strict'; 6614 { 6615 const kCustomPreference = 'customDarkTheme'; 6616 const userSettings = sessionStorage.getItem(kCustomPreference); 6617 const themeToggleButton = document.getElementById('theme-toggle-btn'); 6618 if (userSettings === null && window.matchMedia) { 6619 const mq = window.matchMedia('(prefers-color-scheme: dark)'); 6620 if ('onchange' in mq) { 6621 function mqChangeListener(e) { 6622 document.body.classList.toggle('dark-mode', e.matches); 6623 } 6624 mq.addEventListener('change', mqChangeListener); 6625 if (themeToggleButton) { 6626 themeToggleButton.addEventListener('click', function() { 6627 mq.removeEventListener('change', mqChangeListener); 6628 }, { once: true }); 6629 } 6630 } 6631 if (mq.matches) { 6632 document.body.classList.add('dark-mode'); 6633 } 6634 } else if (userSettings === 'true') { 6635 document.body.classList.add('dark-mode'); 6636 } 6637 if (themeToggleButton) { 6638 themeToggleButton.hidden = false; 6639 themeToggleButton.addEventListener('click', function() { 6640 sessionStorage.setItem( 6641 kCustomPreference, 6642 document.body.classList.toggle('dark-mode') 6643 ); 6644 }); 6645 } 6646 } 6647 </script> 6648</body> 6649</html> 6650