utimensat, utimensat64 - Setting file access and update times

Syntax	#include <sys/stat.h> int utimensat(int fd, const char *path, const struct timespec times[2], int flag); CRTE111A30 int utimensat64(int fd, const char *path, const struct timespec64 times[2], int flag); (End)
Description	The utimensat() function sets the access and update times of a file to the values specified in times. The times of the file are changed to which the path parameter points relative to the directory connected with the file descriptor fd. The function permits time specifications which are accurate to the nanosecond. The times parameter is an array consisting of two structures of the type timespec. The access time is set to the value of the first element, and the update time to the value of the second element. The times in the timespec structure are specified in seconds and nanoseconds since the epoch. If the tv_nsec field of a timespec structure has the special value UTIME_NOW, the corresponding timestamp of the file is set to the current time. If the tv_nsec field of a timespec structure has the special value UTIME_OMIT, the corresponding timestamp of the file should not be updated. In both cases the content of the tv_sec field is ignored. When times is the null pointer, the access and update times are set to the current time. If the file descriptor was opened without O_SEARCH, the function checks whether a search is permitted in the connected file descriptor with the authorizations applicable for the directory. If the file descriptor was opened with O_SEARCH, the check is not performed. A process may call utimensat() with the null pointer for times set or with both tv_nesc fields set to UTIME_NOW only if it has one of the following properties: owner of the file, write authorization for the file, or special rights. A process may call utimensat() with a pointer other than NULL for times in which both tv_nesc fields are not set to UTIME_NOW or UTIME_OMIT only if it is the owner of the file or a process with special rights. When both tv_nesc fields are set to UTIME_OMIT, the access authorization is not checked. However, other errors can occur. When the value AT_FDCWD is transferred to the utimensat() function for the fd parameter, the current directory is used. In the flag parameter, the value AT_SYMLINK_NOFOLLOW, which is defined in the fnctl.h header, can be transferred. If path specifies a symbolic link, the timestamps of the symbolic link are updated. The function utimensat64() behaves like the function utimensat(), except that it uses the structure timespec64 instead of the structure timespec and therefore can process timestamps beyond 01/19/2038 03:14:07 UTC.
Return val.	0	in the case of success,
	-1	in the case of an error errno is set to display the error.
Errors	utimensat() and utimensat46() fail when the following applies:
	EACCES	A component of the path may not be searched, or times is a null pointer and the effective user number is not that of the system administrator and not that of the owner of the file, and write access is rejected or the fd parameter was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.
	EBADF	The path parameter does not specify an absolute pathname, and the fd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching.
	Extension
	EFAULT	times is not equal to zero and points beyond the process's assigned address space, or path points beyond the process's assigned address space.
	EINTR	A signal was intercepted during the system call utimensat() resp. utimensat64().
	EINVAL	An attempt was made to access a BS2000 file or the value of the flag parameter is invalid.
	ELOOP	During the compilation of path too many symbolic links occurred to (End).
	ENAMETOOLONG
		The length of path exceeds {PATH_MAX} or the length of a component of path exceeds {NAME_MAX}.
	ENOENT	The specified file does not exist.
	ENOTDIR	A component of the path is not a directory, or the path parameter does not specify an absolute pathname, and the file descriptor fd is not connected with a directory.
	EPERM	The effective user number if not that of the system administrator and not that of the owner of the file, and times is not equal to zero.
	EROFS	The file system containing the file has been mounted write-protected.
	utimensat64() fails when the following applies:
	ENOSYS	POSIX-BC correction status < A47.
See also	fcntl.h, sys/stat.h.