unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



utime(2)							     utime(2)



NAME

  utime, utimes	- Sets file access and modification times

SYNOPSIS

  #include <&lt;sys/time.h>&gt;
  #include <&lt;utime.h>&gt;

  #include <&lt;sys/types.h>&gt;

  int utime (
	  const	char *path,
	  const	struct utimbuf *times );

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

  The following	definition of the utime() function does	not conform to
  current standards and	is supported only for backward compatibility (see
  standards(5)):


  int utime (
	  const	char *path,
	  struct utimbuf *times	);

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

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  utime(), utimes(): XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  path	    Points to the file.	 If the	final component	of the path parameter
	    names a symbolic link, the link will be traversed and pathname
	    resolution will continue.

  times	    Points to a	utimbuf	structure for the utime() function, or to an
	    array of timeval structures	for the	utimes() function.



DESCRIPTION

  The utimes() function	sets the access	and modification times of the file
  pointed to by	the path parameter to the value	of the times parameter.	 The
  utimes() function allows time	specifications accurate	to the microsecond.

  The utime() function also sets file access and modification times;  how-
  ever,	each time is contained in a single integer and is accurate only	to
  the nearest second.

  For utime(), the times parameter is a	pointer	to a utimbuf structure,
  defined in the utime.h header	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 the	epoch (00:00:00, January 1, 1970, Coordinated
  Universal Time (CUT)).

  For utimes(),	the times parameter is an array	of timeval structures, as
  defined in the sys/time.h header 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 the epoch,	although rounding
  toward the nearest second may	occur.

  If the times parameter is null, the access and modification times of the
  file are set to the current time. If the file	is a remote file, the current
  time at the remote node, rather than the local node, is used.	 The effec-
  tive user ID of the process must be the same as the owner of the file, or
  must have write access to the	file or	superuser privilege in order to	use
  the call in this manner.

  If the times parameter is not	null, the access and modification times	are
  set to the values contained in the designated	structure, regardless of
  whether those	times correlate	with the current time. Only the	owner of the
  file or a user with superuser	privilege can use the call this	way.

  Upon successful completion, the utime() and utimes() functions mark the
  time of the last file	status change, st_ctime, for update.

NOTES

  The utime() and utimes() functions are not recommended for operations, such
  as backing up	or archiving files, that need to change	a file's atime
  (access time)	or mtime (modification time) but not change the	file's ctime
  (attribute change time).  For	such operations, use the fcntl() function's
  F_GETTIMES and F_SETTIMES requests. See fcntl(2) for more information.

RETURN VALUES

  Upon successful completion, a	value of 0 (zero) is returned. Otherwise, a
  value	of -1 is returned, errno is set	to indicate the	error, and the file
  times	will not be affected.

ERRORS

  If the utimes() or utime() function fails, errno may be set to one of	the
  following values:

  [EACCES]  Search permission is denied	by a component of the path prefix; or
	    the	times parameter	is null	and effective user ID is neither the
	    owner of the file nor has appropriate system privilege, and	write
	    access is denied.

  [EFAULT]  The	path parameter is an invalid address, or (for utimes())
	    either the path or times parameter is an invalid address.

  [EINVAL]  The	file is	not a regular file.

  [ELOOP]   Too	many links were	encountered in translating path.

  [ENAMETOOLONG]
	    The	length of the path parameter exceeds PATH_MAX or a pathname
	    component is longer	than NAME_MAX.

  [ENOENT]  The	named file does	not exist or the path parameter	points to an
	    empty string.

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

  [EPERM]   The	times parameter	is not the null	value and the calling process
	    has	write access to	the file but neither owns the file nor has
	    the	appropriate system privilege.

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

  [ESTALE]  The	process' root or current directory is located in a virtual
	    file system	that has been unmounted.

  The utimes() function	can also fail if additional errors occur.

RELATED	INFORMATION

  Functions: fcntl(2), stat(2)

  Standards: standards(5)