[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 2
utimes or utime 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;
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.
This subroutine allows time specifications accurate to the second.
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.
Microsecond time stamps are not implemented, even
though the utimes subroutine provides a way to specify
them.
Parameters
Path |
Points to the file. |
Times |
Specifies the date and time of last access and of last modification.
For the utimes subroutine, this is an array of timeval 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,
rounded to the nearest second.
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,
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 utimes or utime subroutine fails if one of the following is true:
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 utimes or utime subroutine
can be unsuccessful for other reasons. For a list of additional errors, see "Base Operating System Error Codes For Services That
Require Path-Name Resolution."
The utimes or utime subroutine can be unsuccessful for other reasons. For a list of
additional errors, see Appendix A, "Base Operating System Error Codes For
Services That Require Path-Name Resolution."
Related Information
The stat (statx, stat, lstat, fstatx, fstat, fullstat, ffullstat, stat64, lstat64,
or fstat64 Subroutine) subroutine.
Files, Directories, and File
Systems for Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]