fs: implement lutimes

PR-URL: #33399
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>

Author: arcanis

doc/api/fs.md

@@ -2392,6 +2392,38 @@ changes:
 
 Synchronous lchown(2). Returns `undefined`.
 
+## `fs.lutimes(path, atime, mtime, callback)`
+<!-- YAML
+addded: REPLACEME
+-->
+
+*`path` {string|Buffer|URL}
+*`atime` {number|string|Date}
+*`mtime` {number|string|Date}
+*`callback` {Function}
+*`err` {Error}
+
+Changes the access and modification times of a file in the same way as
+[`fs.utimes()`][], with the difference that if the path refers to a symbolic
+link, then the link is not dereferenced: instead, the timestamps of the
+symbolic link itself are changed.
+
+No arguments other than a possible exception are given to the completion
+callback.
+
+## `fs.lutimesSync(path, atime, mtime)`
+<!-- YAML
+added: REPLACEME
+-->
+
+*`path` {string|Buffer|URL}
+*`atime` {number|string|Date}
+*`mtime` {number|string|Date}
+
+Change the file system timestamps of the symbolic link referenced by `path`.
+Returns `undefined`, or throws an exception when parameters are incorrect or
+the operation fails. This is the synchronous version of [`fs.lutimes()`][].
+
 ## `fs.link(existingPath, newPath, callback)`
 <!-- YAML
 added: v0.1.31
@@ -5011,6 +5043,23 @@ changes:
 Changes the ownership on a symbolic link then resolves the `Promise` with
 no arguments upon success.
 
+### `fsPromises.lutimes(path, atime, mtime)`
+<!-- YAML
+added: REPLACEME
+-->
+
+*`path` {string|Buffer|URL}
+*`atime` {number|string|Date}
+*`mtime` {number|string|Date}
+* Returns: {Promise}
+
+Changes the access and modification times of a file in the same way as
+[`fsPromises.utimes()`][], with the difference that if the path refers to a
+symbolic link, then the link is not dereferenced: instead, the timestamps of
+the symbolic link itself are changed.
+
+Upon success, the `Promise` is resolved without arguments.
+
 ### `fsPromises.link(existingPath, newPath)`
 <!-- YAML
 added: v10.0.0
@@ -5829,6 +5878,7 @@ the file contents.
 [`fs.ftruncate()`]: #fs_fs_ftruncate_fd_len_callback
 [`fs.futimes()`]: #fs_fs_futimes_fd_atime_mtime_callback
 [`fs.lstat()`]: #fs_fs_lstat_path_options_callback
+[`fs.lutimes()`]: #fs_fs_lutimes_path_atime_mtime_callback
 [`fs.mkdir()`]: #fs_fs_mkdir_path_options_callback
 [`fs.mkdtemp()`]: #fs_fs_mkdtemp_prefix_options_callback
 [`fs.open()`]: #fs_fs_open_path_flags_mode_callback
@@ -5852,6 +5902,7 @@ the file contents.
 [`fs.writev()`]: #fs_fs_writev_fd_buffers_position_callback
 [`fsPromises.open()`]: #fs_fspromises_open_path_flags_mode
 [`fsPromises.opendir()`]: #fs_fspromises_opendir_path_options
+[`fsPromises.utimes()`]: #fs_fspromises_utimes_path_atime_mtime
 [`inotify(7)`]: http://man7.org/linux/man-pages/man7/inotify.7.html
 [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
 [`net.Socket`]: net.html#net_class_net_socket

lib/fs.js

@@ -1325,6 +1325,28 @@ function futimesSync(fd, atime, mtime) {
 handleErrorFromBinding(ctx);
 }
 
+functionlutimes(path,atime,mtime,callback){
+callback=makeCallback(callback);
+path=getValidatedPath(path);
+
+constreq=newFSReqCallback();
+req.oncomplete=callback;
+binding.lutimes(pathModule.toNamespacedPath(path),
+toUnixTimestamp(atime),
+toUnixTimestamp(mtime),
+req);
+}
+
+functionlutimesSync(path,atime,mtime){
+path=getValidatedPath(path);
+constctx={ path };
+binding.lutimes(pathModule.toNamespacedPath(path),
+toUnixTimestamp(atime),
+toUnixTimestamp(mtime),
+undefined,ctx);
+handleErrorFromBinding(ctx);
+}
+
 functionwriteAll(fd,isUserFd,buffer,offset,length,callback){
 // write(fd, buffer, offset, length, position, callback)
 fs.write(fd,buffer,offset,length,null,(writeErr,written)=>{
@@ -1971,6 +1993,8 @@ module.exports = fs = {
  linkSync,
  lstat,
  lstatSync,
+ lutimes,
+ lutimesSync,
  mkdir,
  mkdirSync,
  mkdtemp,

lib/internal/fs/promises.js

@@ -510,6 +510,14 @@ async function futimes(handle, atime, mtime) {
 returnbinding.futimes(handle.fd,atime,mtime,kUsePromises);
 }
 
+asyncfunctionlutimes(path,atime,mtime){
+path=getValidatedPath(path);
+returnbinding.lutimes(pathModule.toNamespacedPath(path),
+toUnixTimestamp(atime),
+toUnixTimestamp(mtime),
+kUsePromises);
+}
+
 asyncfunctionrealpath(path,options){
 options=getOptions(options,{});
 path=getValidatedPath(path);
@@ -582,6 +590,7 @@ module.exports = {
  lchown,
  chown,
  utimes,
+ lutimes,
  realpath,
  mkdtemp,
  writeFile,

src/node_file.cc

@@ -2304,6 +2304,35 @@ static void FUTimes(const FunctionCallbackInfo<Value>& args) {
  }
 }
 
+staticvoidLUTimes(const FunctionCallbackInfo<Value>& args) {
+ Environment* env = Environment::GetCurrent(args);
+
+constint argc = args.Length();
+CHECK_GE(argc, 3);
+
+ BufferValue path(env->isolate(), args[0]);
+CHECK_NOT_NULL(*path);
+
+CHECK(args[1]->IsNumber());
+constdouble atime = args[1].As<Number>()->Value();
+
+CHECK(args[2]->IsNumber());
+constdouble mtime = args[2].As<Number>()->Value();
+
+ FSReqBase* req_wrap_async = GetReqWrap(args, 3);
+if (req_wrap_async != nullptr) { // lutimes(path, atime, mtime, req)
+AsyncCall(env, req_wrap_async, args, "lutime", UTF8, AfterNoArgs,
+ uv_fs_lutime, *path, atime, mtime);
+ } else { // lutimes(path, atime, mtime, undefined, ctx)
+CHECK_EQ(argc, 5);
+ FSReqWrapSync req_wrap_sync;
+FS_SYNC_TRACE_BEGIN(lutimes);
+SyncCall(env, args[4], &req_wrap_sync, "lutime",
+ uv_fs_lutime, *path, atime, mtime);
+FS_SYNC_TRACE_END(lutimes);
+ }
+}
+
 staticvoidMkdtemp(const FunctionCallbackInfo<Value>& args) {
  Environment* env = Environment::GetCurrent(args);
  Isolate* isolate = env->isolate();
@@ -2399,6 +2428,7 @@ void Initialize(Local<Object> target,
 
  env->SetMethod(target, "utimes", UTimes);
  env->SetMethod(target, "futimes", FUTimes);
+ env->SetMethod(target, "lutimes", LUTimes);
 
  env->SetMethod(target, "mkdtemp", Mkdtemp);
 

test/parallel/test-fs-utimes.js

@@ -24,13 +24,17 @@ const common = require('../common');
 constassert=require('assert');
 constutil=require('util');
 constfs=require('fs');
+consturl=require('url');
 
 consttmpdir=require('../common/tmpdir');
 tmpdir.refresh();
 
-functionstat_resource(resource){
+constlpath=`${tmpdir.path}/symlink`;
+fs.symlinkSync('unoent-entry',lpath);
+
+functionstat_resource(resource,statSync=fs.statSync){
 if(typeofresource==='string'){
-returnfs.statSync(resource);
+returnstatSync(resource);
 }
 conststats=fs.fstatSync(resource);
 // Ensure mtime has been written to disk
@@ -41,9 +45,9 @@ function stat_resource(resource) {
 returnfs.fstatSync(resource);
 }
 
-functioncheck_mtime(resource,mtime){
+functioncheck_mtime(resource,mtime,statSync){
 mtime=fs._toUnixTimestamp(mtime);
-conststats=stat_resource(resource);
+conststats=stat_resource(resource,statSync);
 constreal_mtime=fs._toUnixTimestamp(stats.mtime);
 returnmtime-real_mtime;
 }
@@ -55,8 +59,8 @@ function expect_errno(syscall, resource, err, errno) {
 );
 }
 
-functionexpect_ok(syscall,resource,err,atime,mtime){
-constmtime_diff=check_mtime(resource,mtime);
+functionexpect_ok(syscall,resource,err,atime,mtime,statSync){
+constmtime_diff=check_mtime(resource,mtime,statSync);
 assert(
 // Check up to single-second precision.
 // Sub-second precision is OS and fs dependant.
@@ -68,45 +72,55 @@ function expect_ok(syscall, resource, err, atime, mtime) {
 
 conststats=fs.statSync(tmpdir.path);
 
+constasPath=(path)=>path;
+constasUrl=(path)=>url.pathToFileURL(path);
+
 constcases=[
-newDate('1982-09-10 13:37'),
-newDate(),
-123456.789,
-stats.mtime,
-['123456',-1],
-newDate('2017-04-08T17:59:38.008Z')
+[asPath,newDate('1982-09-10 13:37')],
+[asPath,newDate()],
+[asPath,123456.789],
+[asPath,stats.mtime],
+[asPath,'123456',-1],
+[asPath,newDate('2017-04-08T17:59:38.008Z')],
+[asUrl,newDate()],
 ];
+
 runTests(cases.values());
 
 functionrunTests(iter){
 const{ value, done }=iter.next();
 if(done)return;
+
 // Support easy setting same or different atime / mtime values.
-const[atime,mtime]=Array.isArray(value) ?value : [value,value];
+const[pathType,atime,mtime=atime]=value;
 
 letfd;
 //
 // test async code paths
 //
-fs.utimes(tmpdir.path,atime,mtime,common.mustCall((err)=>{
+fs.utimes(pathType(tmpdir.path),atime,mtime,common.mustCall((err)=>{
 expect_ok('utimes',tmpdir.path,err,atime,mtime);
 
-fs.utimes('foobarbaz',atime,mtime,common.mustCall((err)=>{
-expect_errno('utimes','foobarbaz',err,'ENOENT');
+fs.lutimes(pathType(lpath),atime,mtime,common.mustCall((err)=>{
+expect_ok('lutimes',lpath,err,atime,mtime,fs.lstatSync);
+
+fs.utimes(pathType('foobarbaz'),atime,mtime,common.mustCall((err)=>{
+expect_errno('utimes','foobarbaz',err,'ENOENT');
 
-// don't close this fd
-if(common.isWindows){
-fd=fs.openSync(tmpdir.path,'r+');
-}else{
-fd=fs.openSync(tmpdir.path,'r');
-}
+// don't close this fd
+if(common.isWindows){
+fd=fs.openSync(tmpdir.path,'r+');
+}else{
+fd=fs.openSync(tmpdir.path,'r');
+}
 
-fs.futimes(fd,atime,mtime,common.mustCall((err)=>{
-expect_ok('futimes',fd,err,atime,mtime);
+fs.futimes(fd,atime,mtime,common.mustCall((err)=>{
+expect_ok('futimes',fd,err,atime,mtime);
 
-syncTests();
+syncTests();
 
-setImmediate(common.mustCall(runTests),iter);
+setImmediate(common.mustCall(runTests),iter);
+}));
 }));
 }));
 }));
@@ -115,9 +129,12 @@ function runTests(iter) {
 // test synchronized code paths, these functions throw on failure
 //
 functionsyncTests(){
-fs.utimesSync(tmpdir.path,atime,mtime);
+fs.utimesSync(pathType(tmpdir.path),atime,mtime);
 expect_ok('utimesSync',tmpdir.path,undefined,atime,mtime);
 
+fs.lutimesSync(pathType(lpath),atime,mtime);
+expect_ok('lutimesSync',lpath,undefined,atime,mtime,fs.lstatSync);
+
 // Some systems don't have futimes
 // if there's an error, it should be ENOSYS
 try{
@@ -129,7 +146,7 @@ function runTests(iter) {
 
 leterr;
 try{
-fs.utimesSync('foobarbaz',atime,mtime);
+fs.utimesSync(pathType('foobarbaz'),atime,mtime);
 }catch(ex){
 err=ex;
 }