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

FreeBSD Manual Pages

  
 
  

home | help
utimes(2)			 System	Calls			     utimes(2)

NAME
       utimes, futimesat - set file access and modification times

SYNOPSIS
       #include	<sys/time.h>

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

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

DESCRIPTION
       The utimes() function sets the access and  modification	times  of  the
       file  pointed  to  by the path argument to the value of the times argu-
       ment. It	allows time specifications accurate to the microsecond.

       The futimesat() function	also sets access and modification times.   See
       fsattr(5).  If  path  is	a relative path	name, however, futimesat() re-
       solves the path relative	to the fildes argument rather than the current
       working directory.  If fildes is	set to AT_FDCWD, defined in <fcntl.h>,
       futimesat() resolves the	path relative to the  current  working	direc-
       tory.  If path is a null	pointer, futimesat() sets the access and modi-
       fication	times on the file referenced by	fildes.	The fildes argument is
       ignored even when futimesat() is	provided with an absolute path.

       The  times  argument is an array	of timeval structures. The first array
       member represents the date and time of last access, and the second mem-
       ber  represents	the  date and time of last modification.  The times in
       the timeval structure are measured in seconds  and  microseconds	 since
       the Epoch, although rounding toward the nearest second may occur.

       If  the	times  argument	is a null pointer, the access and modification
       times of	the file are set to the	current	time.  The effective  user  ID
       of  the process must be the same	as the owner of	the file, or must have
       write access to the file	or the {PRIV_FILE_OWNER} privilege to use this
       call  in	 this  manner. Upon completion,	utimes() will mark the time of
       the last	file status change, st_ctime, for update.

RETURN VALUES
       Upon successful completion, 0 is	returned.  Otherwise, -1 is  returned,
       errno  is set to	indicate the error, and	the file times will not	be af-
       fected.

ERRORS
       The utimes() and	futimesat() functions will fail	if:

       EACCES	       Search permission is denied by a	component of the  path
		       prefix; or the times argument is	a null pointer and the
		       effective user ID of the	process	 does  not  match  the
		       owner of	the file and write access is denied.

       EFAULT	       The  path  or  times  argument points to	an illegal ad-
		       dress. For futimesat(), path might have the value  NULL
		       if  the fildes argument refers to a valid open file de-
		       scriptor.

       EINTR	       A  signal  was  caught  during  the  execution  of  the
		       utimes()	function.

       EINVAL	       The  number of microseconds specified in	one or both of
		       the timeval structures pointed to by times was  greater
		       than or equal to	1,000,000 or less than 0.

       EIO	       An  I/O error occurred while reading from or writing to
		       the file	system.

       ELOOP	       Too many	symbolic links were encountered	 in  resolving
		       path.

       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX} or a
		       pathname	component is longer than {NAME_MAX}.

       ENOLINK	       The path	argument points	to a remote  machine  and  the
		       link to that machine is no longer active.

       ENOENT	       A  component  of	path does not name an existing file or
		       path is an empty	string.

       ENOTDIR	       A component of the path prefix is not  a	 directory  or
		       the  path  argument is relative and the fildes argument
		       is not AT_FDCWD or does not refer to a valid directory.

       EPERM	       The times argument is not a null	pointer	and the	 call-
		       ing process's effective user ID has write access	to the
		       file but	does not match the owner of the	file  and  the
		       calling	process	 does  not have	the appropriate	privi-
		       leges.

       EROFS	       The file	system containing the file is read-only.

       The utimes() and	futimesat() functions may fail if:

       ENAMETOOLONG    Path name resolution of a symbolic link produced	an in-
		       termediate result whose length exceeds {PATH_MAX}.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |utimes()	is Standard; fun-  |
       |			     |timesat()	is Evolving	   |
       +-----------------------------+-----------------------------+

SEE ALSO
       stat(2),	utime(2), attributes(5), fsattr(5)

SunOS 5.10			  19 Apr 2004			     utimes(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

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

home | help