utime, utimes, futimens, or utimensat Subroutine

Purpose

Sets file-access and modification times.

Library

Standard C Library (libc.a)

Syntax

#include <sys/time.h>


int utimes ( Path,  Times)
char *Path;
struct timeval Times[2];

#include <utime.h>
int utime ( Path,  Times)
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

Table 1. 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:

Table 2. futimens, utimensat, utimes or utime Error Codes
Item	Description
`EPERM`	The `Times` parameter is not null and the calling process neither owns the file or has root user authority.
`EACCES`	The `Times` parameter is null, effective user ID is not the owner of the file and has not 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:

Table 3. utimensat Error Codes
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` or a file descriptor that is associated with a directory.
`EINVAL`	The value of the `Flag` parameter is not valid.

The futimens subroutine fails if the following is true:

Table 4. futimens Error Codes
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:

Table 5. futimens or utimensat Error Codes
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:

Table 6. utimes Error Codes
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