NAME
	  utime, utimes	- Sets file access and modification times

     SYNOPSIS
	  #include <sys/time.h>

	  #include <utime.h>

	  #include <sys/types.h>

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

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

     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;  however, 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 towards 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 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	superuser privilege in
	  order	to use the call	in this	manner.

	  If the times parameter is not	null, the access and modifica-
	  tion 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() func-
	  tions	mark the time of the last file status change,
	  st_ctime, for	update.

     NOTES
	  AES Support Level: Full use

     RETURN VALUES
	  Upon successful completion, a	value of 0 (zero) is returned.
	  Otherwise, a value of	-1 is returned,	errno is set to	indi-
	  cate 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:

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

	  [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 sys-
		    tem	privilege.

	  [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.

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

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

	  [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.

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

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

     RELATED INFORMATION
	  Functions: stat(2)