Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UTIMES(2)		  FreeBSD System Calls Manual		     UTIMES(2)

NAME
     utimes, futimes, utimensat, futimens -- set file access and modification
     times

SYNOPSIS
     #include <sys/time.h>

     int
     utimes(const char *path, const struct timeval times[2]);

     int
     futimes(int fd, const struct timeval times[2]);

     #include <sys/stat.h>
     #include <fcntl.h>

     int
     utimensat(int fd, const char *path, const struct timespec times[2],
	 int flag);

     int
     futimens(int fd, const struct timespec times[2]);

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	cur-
     rent time.	 The caller must be the	owner of the file, have	permission to
     write the file, or	be the superuser.

     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.  The
     caller must be the	owner of the file or be	the superuser.

     In	either case, the file status change time is set	to the current time.

     The utimensat() and futimens() are	equivalent to utimes() and futimes(),
     respectively, with	the following differences.

     Both utimensat() and futimens() take two timespec values instead of two
     timeval values.  Further, either of the tv_nsec fields can	be set to one
     of	the following special values defined in	<sys/stat.h>, in which case
     the value of tv_sec is ignored:

	   UTIME_NOW   Set the respective timestamp to the greatest value sup-
		       ported that is not greater than the current time.
	   UTIME_OMIT  Do not change the respective timestamp.

     Additionally, if the path argument	to utimensat() specifies a relative
     path, the file whose timestamps are changed is determined relative	to the
     directory associated with file descriptor fd instead of the current work-
     ing directory.

     If	utimensat() is passed the special value	AT_FDCWD (defined in
     <fcntl.h>)	in the fd parameter, the current working directory is used.

     The flag argument is the bitwise OR of zero or more of the	following val-
     ues:

	   AT_SYMLINK_NOFOLLOW	If path	names a	symbolic link, then the	time-
				stamps of the symbolic link are	changed.

RETURN VALUES
     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the
     error.

ERRORS
     utimes() and utimensat() will fail	if:

     [EACCES]		Search permission is denied for	a component of the
			path prefix; or	the times argument is NULL and the ef-
			fective	user ID	of the process does not	match the
			owner of the file, and is not the superuser, and write
			access is denied.

     [EFAULT]		path or	times points outside the process's allocated
			address	space.

     [EIO]		An I/O error occurred while reading or writing the af-
			fected 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 pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [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
			process's effective user ID does not match the owner
			of the file and	is not the superuser.

     [EROFS]		The file system	containing the file is mounted read-
			only.

     Additionally, utimensat() will fail if:

     [EINVAL]		The value of the flag argument was neither zero	nor
			AT_SYMLINK_NOFOLLOW.

     [EBADF]		The path argument specifies a relative path and	the fd
			argument is neither AT_FDCWD nor a valid file descrip-
			tor.

     [ENOTDIR]		The path argument specifies a relative path and	the fd
			argument is a valid file descriptor but	it does	not
			reference a directory.

     [EACCES]		The path argument specifies a relative path but	search
			permission is denied for the directory which the fd
			file descriptor	references.

     futimes() and futimens() will fail	if:

     [EBADF]		fd does	not refer to a valid descriptor.

     [EACCES]		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 superuser, and write access is denied.

     [EFAULT]		times points outside the process's allocated address
			space.

     [EIO]		An I/O error occurred while reading or writing the af-
			fected inode.

     [EPERM]		The times argument is not NULL and the calling
			process's effective user ID does not match the owner
			of the file and	is not the superuser.

     [EROFS]		The file system	containing the file is mounted read-
			only.

     utimes() and futimes() will fail if:

     [EINVAL]		Either of the times arguments specified	a microsecond
			value less than	zero or	greater	than or	equal to 1
			million, or a second value less	than zero.

     utimesat()	and futimens() will fail if:

     [EINVAL]		Either of the times argument specified a nanosecond
			value less than	zero or	greater	than or	equal to 1000
			million, or a second value less	than zero.

SEE ALSO
     clock_gettime(2), stat(2),	utime(3)

STANDARDS
     The utimes(), utimensat(),	and futimens() functions conform to IEEE Std
     1003.1-2008 ("POSIX.1").

HISTORY
     The predecessors of utimes() were smdate()	in Version 1 AT&T UNIX,
     mdate() in	Version	3 AT&T UNIX, and utime() in Version 7 AT&T UNIX; the
     latter first supported the	concept	of an access time in addition to the
     modification time.

     The utimes() function call	appeared in 4.2BSD.  The futimes() function
     call appeared in NetBSD 1.2.  The utimensat() and futimens() function
     calls appeared in OpenBSD 5.0.

CAVEATS
     Some filesystems, such as FAT, use	the same timestamp for both modifica-
     tion and file status change; on those filesystems,	the file status	change
     timestamp will not	be updated if UTIME_OMIT is specified for the modifi-
     cation timestamp argument.	 Similarly, on NFS the file status change
     timestamp will not	be updated if UTIME_OMIT is specified for both the ac-
     cess and the modification timestamp arguments.

FreeBSD	13.0		      September	30, 2020		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=utimes&sektion=2&manpath=OpenBSD+6.9>

home | help