utime, utimes, futimens, or utimensat Subroutine
Purpose
Sets file-access and modification times.
Library
Standard C Library (libc.a)
Syntax
#include <sys/time.h>#include <utime.h>const char *Path;
const struct utimbuf *Times;
#include <sys/stat.h>
int futimens ( FileDescriptor, Times)
int FileDescriptor;
struct timespec Times[2];
#include <sys/stat.h>
int utimensat ( DirFileDescriptor, Path, Times, Flag)
int DirFileDescriptor;
char *Path;
struct timespec Times[2];
int Flag;
Description
The utimes subroutine sets the access and modification times of the file pointed to by the Path parameter to the value of the Times parameter.
The futimens and utimensat subroutines set the access and modification times of a file to the value of the Times parameter. The futimens subroutine file is specified by the FileDescriptor parameter, which is a file descriptor of an open file.
The utimensat subroutine file is specified by the DirFileDescriptor and Path parameters. If the DirFileDescriptor parameter is set to AT_FDCWD or the Path parameter is an absolute path name, the utimensat subroutine is equivalent to the utimes subroutine when the Flag parameter of the utimensat subroutine set to zero.
If the tv_nsec field of a timespec structure or the tv_usec field of the timeval structure has the value UTIME_NOW, the corresponding timestamp for the file is set to the current time. If the field has the value UTIME_OMIT, the corresponding timestamp for the file is not changed. In either case, the tv_sec field is ignored. If the Times parameter is NULL, both timestamps are set to the current time.
The utime subroutine also sets file access and modification times. Each time is contained in a single integer and is accurate only to the nearest second. If successful, the utime subroutine marks the time of the last file-status change (st_ctime) to be updated.
Parameters
| Item | Description |
|---|---|
| FileDescriptor | Specifies the file descriptor of an open file. |
| Path | Points to the path name of the file. If the DirFileDescriptor is specified and Path is a relative path name, then Path is considered relative to the directory specified by DirFileDescriptor. |
| DirFileDescriptor | Specifies the file descriptor of an open directory. |
| Flag | Specifies a bit field. If the AT_SYMLINK_NOFOLLOW bit is set and Path points to a symbolic link, then the access and modification times of the symbolic link are changed. If the AT_SYMLINK_NOFOLLOW bit is not set, the times of the file the symbolic link points at are changed. |
| Times | Specifies the date and time of last access and of last modification.
For the utimes subroutine, this is an array of timespec structures,
as defined in the <sys/time.h> file. The first array
element represents the date and time of last access, and the second
element represents the date and time of last modification. The times
in the timeval structure are measured in seconds and microseconds
since 00:00:00 Greenwich Mean Time (GMT), 1 January 1970. The times
in the timespec structure are measured in seconds and nanoseconds
since 00:00:00 Greenwich Mean Time (GMT), 1 January 1970. For the utime subroutine, this parameter is a pointer to a utimbuf structure, as defined in the utime.h file. The first structure member represents the date and time of last access, and the second member represents the date and time of last modification. The times in the utimbuf structure are measured in seconds since 00:00:00 Greenwich Mean Time (GMT), 1 January 1970. If the Times parameter has a null value, the access and modification times of the file are set to the current time. If the file is remote, the current time at the remote node, rather than the local node, is used. To use the call this way, the effective user ID of the process must be the same as the owner of the file or must have root authority, or the process must have write permission to the file. If the Times parameter does not have a null value and the UTIME_NOW or the UTIME_OMIT values are not set, the access and modification times are set to the values contained in the designated structure, regardless of whether those times are the same as the current time. Only the owner of the file or a user with root authority can use the call this way. |
Return Values
Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, the errno global variable is set to indicate the error, and the file times are not changed.
Error Codes
The futimens, utimensat, utimes or utime subroutines fail if one of the following is true:
| Item | Description |
|---|---|
| EPERM | The Times parameter is not null and the calling process neither owns the file nor has root user authority. |
| EACCES | The Times parameter is null, effective user ID is neither the owner of the file nor has root authority, or write access is denied. |
| EROFS | The file system that contains the file is mounted read-only. |
The utimensat subroutine fails if one or more of the following settings are true:
| Item | Description |
|---|---|
| EBADF | The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor. |
| ENOTDIR | The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory. |
| EINVAL | The value of the Flag parameter is not valid. |
The futimens subroutine fails if the following is true:
| Item | Description |
|---|---|
| EBADF | The FileDescriptor parameter does not specify a valid file descriptor. |
The futimens or utimensat subroutine fails if one or more of the following settings are true:
| Item | Description |
|---|---|
| EINVAL | The Times parameter has a negative tv_sec field. |
| EINVAL | The Times parameter has a negative tv_nsec field, or the tv_nsec field is equal to or greater than 1000 million. |
The utimes subroutine fails if one or more of the following settings are true:
| Item | Description |
|---|---|
| EINVAL | The Times parameter has a negative tv_sec field. |
| EINVAL | The Times parameter has a negative tv_usec field, or the tv_usec field is greater than or equal to a million. |
The utimes, utimensat, or utime subroutine can be unsuccessful for other reasons. For a list of additional errors, see ../bostechref/bos_error_codes.html