utime() — Set file access and modification times
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1 |
both |
Format
#define _POSIX_SOURCE
#include <utime.h>
int utime(const char *pathname, const struct utimbuf *newtimes);
General description
Sets the access and modification times of pathname to the values in the utimbuf structure. If newtimes is a NULL pointer, the access and modification times are set to the current time.
Normally, the effective user ID (UID) of the calling process must match the owner UID of the file, or the calling process must have appropriate privileges. However, if newtimes is a NULL pointer, the effective UID of the calling process must match the owner UID of the file, or the calling process must have write permission to the file or appropriate privileges.
The contents
of a utimbuf structure are:
- time_t actime
- The new access time (The time_t type gives the number of seconds since the epoch.)
- time_t modtime
- The new modification time
Returned value
If successful, utime() returns 0 and updates the access and modification times of the file to those specified.
If unsuccessful, utime() returns -1, does not update
file times, and sets errno to one of the following values:
- Error Code
- Description
- EACCES
- The process does not have search permission on some component
of the pathname prefix; or all of the following
are true:
- newtimes is NULL.
- The effective user ID of the process does not match the file's owner.
- The process does not have write permission on the file.
- The process does not have appropriate privileges.
- ELOOP
- A loop exists in symbolic links. This error is issued if more than POSIX_SYMLOOP symbolic links (defined in the limits.h header file) are detected in the resolution of pathname.
- ENAMETOOLONG
- pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().
- ENOENT
- There is no file named pathname, or the pathname argument is an empty string.
- ENOTDIR
- Some component of the pathname prefix is not a directory.
- EPERM
- newtimes is not NULL, the effective user ID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges.
- EROFS
- pathname is on a read-only file system.
Example
CELEBU07
/* CELEBU07 */
#define _POSIX_SOURCE
#include <fcntl.h>
#include <stdio.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <time.h>
#include <unistd.h>
#include <utime.h>
main() {
int fd;
char fn[]="utime.file";
struct utimbuf ubuf;
if ((fd = creat(fn, S_IWUSR)) < 0)
perror("creat() error");
else {
close(fd);
puts("before utime()");
system("ls -l utime.file");
ubuf.modtime = 0;
time(&ubuf.actime);
if (utime(fn, &ubuf) != 0)
perror("utime() error");
else {
puts("after utime()");
system("ls -l utime.file");
}
unlink(fn);
}
}
Output
before utime()
--w------- 1 WELLIE SYS1 0 Apr 19 15:23 utime.file
after utime()
--w------- 1 WELLIE SYS1 0 Dec 31 1969 utime.file