unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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()
       resolves the path relative to the fildes argument rather than the  cur-
       rent  working  directory.   If  fildes  is  set to AT_FDCWD, defined in
       <&lt;fcntl.h>&gt;, futimesat() resolves the path relative to the current  work-
       ing  directory.  If path is a null pointer, futimesat() sets the access
       and modification 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
       affected.

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
                       address.  For  futimesat(),  path  might have the value
                       NULL if the fildes argument refers to a valid open file
                       descriptor.



       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
                       intermediate result whose length exceeds {PATH_MAX}.



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


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE  VALUE  Interface StabilityT{
       utimes() is Standard; funtimesat() is Evolving T}


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




SunOS 5.10                        19 Apr 2004                        utimes(2)