utimes(2)

NAME

utimes, lutimes, futimes - set file access and modification

times

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <sys/time.h>
int
utimes(const char *path, const struct timeval *times);
int
lutimes(const char *path, const struct timeval *times);
int
futimes(int fd, const struct timeval *times);

DESCRIPTION

The access and modification times of the file named by path

or referenced
by fd are changed as specified by the argument times.

If times is NULL, the access and modification times are set

to the current time. The caller must be the owner of the file, have

permission to
write the file, or be the super-user.

If times is non-NULL, it is assumed to point to an array of

two timeval
structures. The access time is set to the value of the

first element,
and the modification time is set to the value of the second

element. For
file systems that support file birth (creation) times (such

as UFS2), the
birth time will be set to the value of the second element if

the second
element is older than the currently set birth time. To set

both a birth
time and a modification time, two calls are required; the

first to set
the birth time and the second to set the (presumably newer)

modification
time. Ideally a new system call will be added that allows

the setting of
all three times at once. The caller must be the owner of

the file or be
the super-user.

In either case, the inode-change-time of the file is set to

the current
time.

The lutimes() system call is like utimes() except in the

case where the
named file is a symbolic link, in which case lutimes()

changes the access
and modification times of the link, while utimes() changes

the times of
the file the link references.

RETURN VALUES

The function returns the value 0 if successful; otherwise

the value -1 is
returned and the global variable errno is set to indicate

the error.

ERRORS

The utimes() and lutimes() system calls will fail if:

[EACCES] Search permission is denied for a compo

nent of the

path prefix; or the times argument is

NULL and the
effective user ID of the process does not

match the
owner of the file, and is not the super

user, and
write access is denied.

[EFAULT] The path or times argument points outside

the pro

cess's allocated address space.

[EIO] An I/O error occurred while reading or

writing the

affected inode.

[ELOOP] Too many symbolic links were encountered

in translat

ing the pathname.

[ENAMETOOLONG] A component of a pathname exceeded

NAME_MAX charac

ters, or an entire path name exceeded

PATH_MAX characters.

[ENOENT] The named file does not exist.

[ENOTDIR] A component of the path prefix is not a

directory.

[EPERM] The times argument is not NULL and the

calling pro

cess's effective user ID does not match

the owner of
the file and is not the super-user.

[EROFS] The file system containing the file is

mounted read

only.

The futimes() system call will fail if:

[EBADF] The fd argument does not refer to a valid

descriptor.

All of the system calls will fail if:

[EACCES] The times argument is NULL and the effec

tive user ID

of the process does not match the owner

of the file,
and is not the super-user, and write ac

cess is denied.

[EFAULT] The times argument points outside the

process's allo

cated address space.

[EINVAL] The tv_usec component of at least one of

the values

specified by the times argument has a

value less than
0 or greater than 999999.

[EIO] An I/O error occurred while reading or

writing the

affected inode.

[EPERM] The times argument is not NULL and the

calling pro

cess's effective user ID does not match

the owner of
the file and is not the super-user.

[EROFS] The file system containing the file is

mounted read

only.

SEE ALSO

stat(2), utime(3)

HISTORY

The utimes() system call appeared in 4.2BSD. The futimes()

and lutimes()
system calls first appeared in FreeBSD 3.0.

BSD January 22, 2006

BSD