fs: add mkstemp functions

doc/api/fs.md

@@ -2677,6 +2677,70 @@ this API: [`fs.mkdtemp()`][].
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use.
 
+## `fs.mkstemp(prefix[, options], callback)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'`
+* `callback` {Function}
+  * `err` {Error}
+  * `file` {Object}
+    * `path` {string}
+    * `fd` {number}
+
+Creates and opens a unique temporary file.
+
+Generates six random characters to be appended behind a required `prefix` to
+create a unique temporary file. Due to platform inconsistencies, avoid trailing
+`X` characters in `prefix`. Some platforms, notably the BSDs, can return more
+than six random characters, and replace trailing `X` characters in `prefix`
+with random characters.
+
+The created file path and file descriptor are passed as an object to the
+callback's second parameter.
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use.
+
+```js
+fs.mkstemp(path.join(os.tmpdir(), 'foo-'), (err, result) => {
+  if (err) throw err;
+  console.log(result.path);
+  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
+  fs.close(result.fd, (err) => {
+    if (err) throw err;
+  });
+});
+```
+
+The `fs.mkstemp()` method will append the six randomly selected characters
+directly to the `prefix` string. For instance, given a directory `/tmp`, if the
+intention is to create a temporary file *within* `/tmp`, the `prefix` must end
+with a trailing platform-specific path separator (`require('path').sep`).
+
+## `fs.mkstempSync(prefix[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'`
+* Returns: {Object}
+  * `path` {string}
+  * `fd` {number}
+
+Returns an object with the created file path and file descriptor.
+
+For detailed information, see the documentation of the asynchronous version of
+this API: [`fs.mkstemp()`][].
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use.
+
 ## `fs.open(path[, flags[, mode]], callback)`
 <!-- YAML
 added: v0.0.2
@@ -5089,6 +5153,44 @@ characters directly to the `prefix` string. For instance, given a directory
 `prefix` must end with a trailing platform-specific path separator
 (`require('path').sep`).
 
+### `fsPromises.mkstemp(prefix[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `prefix` {string}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'`
+* Returns: {Promise}
+
+Creates and opens a unique empty temporary file, and fulfills the `Promise` with
+an object that contains the created file path and a `FileHandle` object. A
+unique file name is generated by appending six random characters to the end of
+the provided `prefix`. Due to platform inconsistencies, avoid trailing `X`
+characters in `prefix`. Some platforms, notably the BSDs, can return more than
+six random characters, and replace trailing `X` characters in `prefix` with
+random characters.
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use.
+
+```js
+async function createRandomFile() {
+  const result = await fsPromises.mkstemp(path.join(os.tmpdir(), 'foo-'));
+  console.log(result.path);
+  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
+  await result.handle.close();
+  // Closes the file descriptor but does not remove the file.
+}
+createRandomFile().catch(console.error);
+```
+
+The `fsPromises.mkstemp()` method will append the six randomly selected
+characters directly to the `prefix` string. For instance, given a directory
+`/tmp`, if the intention is to create a temporary file *within* `/tmp`, the
+`prefix` must end with a trailing platform-specific path separator
+(`require('path').sep`).
+
 ### `fsPromises.open(path, flags[, mode])`
 <!-- YAML
 added: v10.0.0
@@ -5828,6 +5930,7 @@ the file contents.
 [`fs.lstat()`]: #fs_fs_lstat_path_options_callback
 [`fs.mkdir()`]: #fs_fs_mkdir_path_options_callback
 [`fs.mkdtemp()`]: #fs_fs_mkdtemp_prefix_options_callback
+[`fs.mkstemp()`]: #fs_fs_mkstemp_prefix_options_callback
 [`fs.open()`]: #fs_fs_open_path_flags_mode_callback
 [`fs.opendir()`]: #fs_fs_opendir_path_options_callback
 [`fs.opendirSync()`]: #fs_fs_opendirsync_path_options

lib/fs.js

@@ -1879,6 +1879,46 @@ function mkdtempSync(prefix, options) {
 }
 
 
+function mkstemp(prefix, options, callback) {
+  callback = makeCallback(typeof options === 'function' ? options : callback);
+  options = getOptions(options, {});
+  if (!prefix || typeof prefix !== 'string') {
+    throw new ERR_INVALID_ARG_TYPE('prefix', 'string', prefix);
+  }
+  nullCheck(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+  const req = new FSReqCallback();
+  req.oncomplete = function oncomplete(err, result) {
+    if (err !== null)
+      return callback(err);
+    callback(null, {
+      path: result[0],
+      fd: result[1],
+    });
+  };
+  binding.mkstemp(`${prefix}XXXXXX`, options.encoding, req);
+}
+
+
+function mkstempSync(prefix, options) {
+  options = getOptions(options, {});
+  if (!prefix || typeof prefix !== 'string') {
+    throw new ERR_INVALID_ARG_TYPE('prefix', 'string', prefix);
+  }
+  nullCheck(prefix, 'prefix');
+  warnOnNonPortableTemplate(prefix);
+  const path = `${prefix}XXXXXX`;
+  const ctx = { path };
+  const result = binding.mkstemp(path, options.encoding,
+                                 undefined, ctx);
+  handleErrorFromBinding(ctx);
+  return {
+    path: result[0],
+    fd: result[1],
+  };
+}
+
+
 function copyFile(src, dest, mode, callback) {
   if (typeof mode === 'function') {
     callback = mode;
@@ -1972,6 +2012,8 @@ module.exports = fs = {
   mkdirSync,
   mkdtemp,
   mkdtempSync,
+  mkstemp,
+  mkstempSync,
   open,
   openSync,
   opendir,

lib/internal/fs/promises.js

@@ -502,6 +502,24 @@ async function mkdtemp(prefix, options) {
   return binding.mkdtemp(`${prefix}XXXXXX`, options.encoding, kUsePromises);
 }
 
+async function mkstemp(prefix, options) {
+  options = getOptions(options, {});
+  if (!prefix || typeof prefix !== 'string') {
+    throw new ERR_INVALID_ARG_TYPE('prefix', 'string', prefix);
+  }
+  nullCheck(prefix);
+  warnOnNonPortableTemplate(prefix);
+  const result = await binding.mkstempFileHandle(
+    `${prefix}XXXXXX`,
+    options.encoding,
+    kUsePromises,
+  );
+  return {
+    path: result[0],
+    handle: new FileHandle(result[1]),
+  };
+}
+
 async function writeFile(path, data, options) {
   options = getOptions(options, { encoding: 'utf8', mode: 0o666, flag: 'w' });
   const flag = options.flag || 'w';
@@ -560,6 +578,7 @@ module.exports = {
     utimes,
     realpath,
     mkdtemp,
+    mkstemp,
     writeFile,
     appendFile,
     readFile,

lib/internal/fs/utils.js

@@ -603,7 +603,8 @@ function warnOnNonPortableTemplate(template) {
   // Template strings passed to the mkdtemp() family of functions should not
   // end with 'X' because they are handled inconsistently across platforms.
   if (nonPortableTemplateWarn && template.endsWith('X')) {
-    process.emitWarning('mkdtemp() templates ending with X are not portable. ' +
+    process.emitWarning('mkdtemp() and mkstemp() templates ending with X are ' +
+                        'not portable. ' +
                         'For details see: https://nodejs.org/api/fs.html');
     nonPortableTemplateWarn = false;
   }

src/node_file.cc

@@ -633,6 +633,59 @@ void AfterOpenFileHandle(uv_fs_t* req) {
   }
 }
 
+void AfterMkstemp(uv_fs_t* req) {
+  FSReqBase* req_wrap = FSReqBase::from_req(req);
+  FSReqAfterScope after(req_wrap, req);
+
+  if (after.Proceed()) {
+    Environment* env = req_wrap->env();
+
+    Local<Value> error;
+    MaybeLocal<Value> path = StringBytes::Encode(
+        env->isolate(), req->path, req_wrap->encoding(), &error);
+
+    if (path.IsEmpty()) {
+      req_wrap->Reject(error);
+      return;
+    }
+
+    Local<Value> result[] = {
+      path.ToLocalChecked(),
+      Integer::New(env->isolate(), req->result)
+    };
+
+    req_wrap->Resolve(Array::New(env->isolate(), result, arraysize(result)));
+  }
+}
+
+void AfterMkstempFileHandle(uv_fs_t* req) {
+  FSReqBase* req_wrap = FSReqBase::from_req(req);
+  FSReqAfterScope after(req_wrap, req);
+
+  if (after.Proceed()) {
+    Environment* env = req_wrap->env();
+
+    Local<Value> error;
+    MaybeLocal<Value> path = StringBytes::Encode(
+        env->isolate(), req->path, req_wrap->encoding(), &error);
+
+    if (path.IsEmpty()) {
+      req_wrap->Reject(error);
+      return;
+    }
+
+    FileHandle* fd = FileHandle::New(req_wrap->binding_data(), req->result);
+    if (fd == nullptr) return;
+
+    Local<Value> result[] = {
+      path.ToLocalChecked(),
+      fd->object()
+    };
+
+    req_wrap->Resolve(Array::New(env->isolate(), result, arraysize(result)));
+  }
+}
+
 // Reverse the logic applied by path.toNamespacedPath() to create a
 // namespace-prefixed path.
 void FromNamespacedPath(std::string* path) {
@@ -2307,6 +2360,76 @@ static void Mkdtemp(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+static void Mkstemp(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  Isolate* isolate = env->isolate();
+
+  const int argc = args.Length();
+  CHECK_GE(argc, 2);
+
+  BufferValue tmpl(isolate, args[0]);
+  CHECK_NOT_NULL(*tmpl);
+
+  const enum encoding encoding = ParseEncoding(isolate, args[1], UTF8);
+
+  FSReqBase* req_wrap_async = GetReqWrap(args, 2);
+  if (req_wrap_async != nullptr) {  // mkstemp(tmpl, encoding, req)
+    AsyncCall(env,
+              req_wrap_async,
+              args,
+              "mkstemp",
+              encoding,
+              AfterMkstemp,
+              uv_fs_mkstemp,
+              *tmpl);
+  } else {  // mkstemp(tmpl, encoding, undefined, ctx)
+    CHECK_EQ(argc, 4);
+    FSReqWrapSync req_wrap_sync;
+    FS_SYNC_TRACE_BEGIN(mkstemp);
+    SyncCall(env, args[3], &req_wrap_sync, "mkstemp", uv_fs_mkstemp, *tmpl);
+    FS_SYNC_TRACE_END(mkstemp);
+    const char* path = req_wrap_sync.req.path;
+    int fd = req_wrap_sync.req.result;
+
+    Local<Value> error;
+    MaybeLocal<Value> rc = StringBytes::Encode(isolate, path, encoding, &error);
+    if (rc.IsEmpty()) {
+      Local<Object> ctx = args[3].As<Object>();
+      ctx->Set(env->context(), env->error_string(), error).Check();
+      return;
+    }
+
+    Local<Value> result[] = {rc.ToLocalChecked(),
+                             Integer::New(env->isolate(), fd)};
+
+    args.GetReturnValue().Set(
+        Array::New(env->isolate(), result, arraysize(result)));
+  }
+}
+
+static void MkstempFileHandle(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  Isolate* isolate = env->isolate();
+
+  const int argc = args.Length();
+  CHECK_GE(argc, 2);
+
+  BufferValue tmpl(isolate, args[0]);
+  CHECK_NOT_NULL(*tmpl);
+
+  const enum encoding encoding = ParseEncoding(isolate, args[1], UTF8);
+
+  FSReqBase* req_wrap_async = GetReqWrap(args, 2);
+  AsyncCall(env,
+            req_wrap_async,
+            args,
+            "mkstemp",
+            encoding,
+            AfterMkstempFileHandle,
+            uv_fs_mkstemp,
+            *tmpl);
+}
+
 void BindingData::MemoryInfo(MemoryTracker* tracker) const {
   tracker->TrackField("stats_field_array", stats_field_array);
   tracker->TrackField("stats_field_bigint_array", stats_field_bigint_array);
@@ -2367,6 +2490,8 @@ void Initialize(Local<Object> target,
   env->SetMethod(target, "futimes", FUTimes);
 
   env->SetMethod(target, "mkdtemp", Mkdtemp);
+  env->SetMethod(target, "mkstemp", Mkstemp);
+  env->SetMethod(target, "mkstempFileHandle", MkstempFileHandle);
 
   target
       ->Set(context,

test/parallel/test-fs-assert-encoding-error.js

@@ -69,6 +69,14 @@ assert.throws(() => {
   fs.mkdtempSync('path', options);
 }, expectedError);
 
+assert.throws(() => {
+  fs.mkstemp('path', options, common.mustNotCall());
+}, expectedError);
+
+assert.throws(() => {
+  fs.mkstempSync('path', options);
+}, expectedError);
+
 assert.throws(() => {
   fs.ReadStream('path', options);
 }, expectedError);