| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- set file access and modification times
#include <sys/stat.h>intfutimens(intfd,const struct timespectimes[2]);
intutimensat(intfd,const char *path,const struct timespectimes[2],intflag);
Thefutimens() andutimensat() functions set the access and modification times ofa file to the values of thetimes argument. Thefutimens() functionchanges the times of the file associated with the file descriptorfd.Theutimensat() function changes the times of the file pointed to bythe path argument, relative to the directory associated with the file descriptorfd. Both functions allow time specifications accurate to the nanosecond.
Thetimes argument is an array of twotimespec structures. The firstarray member represents the date and time of last access, and thesecond member represents the date and time of last modification. The timesin thetimespec structure are measured in seconds and nanoseconds since the Epoch.The file's relevant timestamp is set to the greatest value supported bythe file system that is not greater than the specified time.
If thetv_nsec field of atimespec structure has the special valueUTIME_NOW, the file's relevant timestamp is set to the greatest value supportedby the file system that is not greater than the current time.If thetv_nsec field has the special valueUTIME_OMIT, the file's relevanttimestamp is not changed. In either case, thetv_sec field is ignored.
If the times argument is a null pointer, both the access andmodification timestamps are set to the greatest value supported by the filesystem that is not greater than the current time. Ifutimensat() ispassed a relative path in the path argument, the file to beused is relative to the directory associated with the file descriptorfd insteadof the current working directory.
Ifutimensat() is passed the special valueAT_FDCWD in thefd parameter,the current working directory is used.
Only a process with the effective user ID equal to the userID of the file, or with write access to the file, orwith appropriate privileges may usefutimens() orutimensat() with a null pointeras the times argument or with bothtv_nsec fields set to the specialvalueUTIME_NOW. Only a process with the effective user ID equal tothe user ID of the file or with appropriate privileges may usefutimens() orutimensat() with a non-null times argument that does not havebothtv_nsec fields set toUTIME_NOW and does not have bothtv_nsecfields set toUTIME_OMIT. If bothtv_nsec fields are set toUTIME_OMIT,no ownership or permissions check is performed for the file, but other errorconditions are still detected (includingEACCES errors related to the path prefix).
Values for the flag argument ofutimensat() are constructed by a bitwise-inclusiveOR of flags from the following list, defined in<fcntl.h>:
If path names a symbolic link, then the access and modification times of the symbolic link are changed.
Upon completion,futimens() andutimensat() mark the last file status change timestampfor update.
Upon successful completion, these functions return 0. Otherwise, these functions return -1and seterrno to indicate the error. If -1 is returned, thefile times are not affected.
Thefutimens() andutimensat() functions will fail if:
The times argument is a null pointer, or bothtv_nsec values areUTIME_NOW, and the effective user ID of the process does not match the owner of the file and write access is denied.
Either of the times argument structures specified atv_nsec value that was neitherUTIME_NOW norUTIME_OMIT, and was a value less than zero or greater than or equal to 1000 million.
A new file timestamp would be a value whosetv_sec component is not a value supported by the file system.
The times argument is not a null pointer, does not have bothtv_nsec fields set toUTIME_NOW, does not have bothtv_nsec fields set toUTIME_OMIT, the calling process' effective user ID has write access to the file but does not match the owner of the file, and the calling process does not have appropriate privileges.
The file system containing the file is read-only.
Thefutimens() function will fail if:
Thefd argument is not a valid file descriptor.
Theutimensat() function will fail if:
The permissions of the directory underlyingfd do not permit directory searches.
The path argument does not specify an absolute path and thefd argument is neitherAT_FDCWD nor a valid file descriptor open for reading.
The path argument is not an absolute path andfd is neitherAT_FDCWD nor a file descriptor associated with a directory.
Search permission is denied by a component of the path prefix.
Too many symbolic links were encountered during resolution of the path argument.
The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
A component of path does not name an existing file or path is an empty string.
A component of the path prefix is not a directory, or the path argument contains at least one character that is not a slash (/) and ends with one or more trailing slash characters and the last pathname component names an existing file that is neither a directory nor a symbolic link to a directory.
Theutimensat() function will fail if:
Path name resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.
Seeattributes(5) for descriptions of the following attributes:
|
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |