Base: Write man page for utimensat(3) and futimens(3)

Author: https://github.com/arieldon
Commit: https://github.com/SerenityOS/serenity/commit/210c3f24cd
Pull-request: https://github.com/SerenityOS/serenity/pull/14088
Reviewed-by: https://github.com/EWouters

Base/usr/share/man/man3/futimens.md

@@ -0,0 +1 @@
+utimensat.md

Base/usr/share/man/man3/utimensat.md

@@ -0,0 +1,105 @@
+## Name
+
+futimens, utimensat - update file access and modification times
+
+## Synopsis
+
+```**c++
+#include <sys/stat.h>
+
+int futimens(int fd, struct timespec const times[2]);
+
+#include <fcntl.h>
+
+int utimensat(int dirfd, char const* path, struct timespec const times[2],
+    int flag);
+```
+
+## Description
+
+`futimens()` and `utimensat()` set the access and modification times of a file
+to the values specified in `times`.
+
+`futimens()` updates the times of the file associated with the file descriptor.
+
+`utimensat()` functions in two ways.
+
+1. Given a valid file descriptor for a directory and a non-empty path,
+`utimensat()` updates the value of the file specified by the path relative to
+the directory specified by the file descriptor. This is standard POSIX
+behavior.
+2. Given a valid file descriptor to a regular file and an empty path,
+`utimensat()` updates the value of the file associated with the file
+descriptor. This is not standard POSIX behavior, but it allows `futimens()` to
+be implemented in terms of `utimensat()`.
+
+If the `tv_nsec` field of `times` is set to UTIME_NOW, then the corresponding
+timestamp of the file is set to the current time. If the `tv_nsec` field of
+`times` is set to UTIME_OMIT, then the corresponding timestamp is not modified.
+In both of these special cases, `tv_sec`, the other field in `times`, is
+ignored.
+
+If `times` is a null pointer, then both the last access time and the last
+modification time are set to the current time. This configuration is equivalent
+to setting the `tv_nsec` field to UTIME_NOW for both timespec structures in the
+array.
+
+Parameter `flag` of `utimensat()` may be set to 0 or `AT_SYMLINK_NOFOLLOW`. If
+set to `AT_SYMLINK_NOFOLLOW`, instead of following a symbolic link,
+`utimensat()` updates the timestamps of the link itself. `futimens()` always
+follows symbolic links.
+
+Parameter `dirfd` of `utimensat()` may be set to `AT_FDCWD` to use the current
+working directory as the relative directory.
+
+## Return Value
+
+`futimens()` and `utimensat()` return 0 upon success and -1 otherwise. Upon
+failure, these functions also set `errno` to indicate the error and leave the
+access and modification times of the specified file unmodified.
+
+## Errors
+
+`futimens()` and `utimensat()` may return the following error codes.
+
+* `EFAULT`: `path` of `utimensat()` is a null pointer.
+* `EINVAL`: Length of `path` is too long.
+* `EINVAL`: `flag` is not 0 or `AT_SYMLINK_NOFOLLOW`
+* `EINVAL`: The timestamp is not supported by the file system.
+* `EINVAL`: Fields of `times` are less than 0 or greater than or equal to 1000
+million and not `UTIME_NOW` or `UTIME_OMIT`.
+* `EACCES`: The current user does not have write access to the file.
+* `EROFS`: The file system that contains the file is read-only.
+* `ENOTDIR`: `path` is not absolute and `dirfd` is not a file descriptor
+associated with a directory.
+
+## Examples
+
+```c++
+#include <fcntl.h>
+#include <sys/stat.h>
+
+int main()
+{
+    timespec times[2];
+    auto& atime = times[0];
+    auto& mtime = times[1];
+
+    atime.tv_sec = 0;
+    atime.tv_nsec = UTIME_NOW;
+    mtime.tv_sec = 0;
+    mtime.tv_nsec = UTIME_OMIT;
+
+    // Update only last access time of file "README.md" in current working
+    // directory to current time. Leave last modification time unchanged.
+    if (utimensat(AT_FDCWD, "README.md", times, 0) == -1) {
+        return 1;
+    }
+
+    return 0;
+}
+```
+
+## See also
+
+* [`touch`(1)](help://man/1/touch)