utime(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
UTIME(3)                  NetBSD Programmer's Manual                  UTIME(3)


NAME

     utime - set file times


SYNOPSIS

     #include <sys/types.h>
     #include <utime.h>

     int
     utime(const char *file, const struct utimbuf *timep);


DESCRIPTION

     This interface is obsoleted by utimes(2) .

     The utime() function sets the access and modification times of the named
     file.

     If timep is NULL, the access and modification times are set to the cur-
     rent time.  The calling process must be the owner of the file or have
     permission to write the file.

     If timep is non-NULL, time is assumed to be a pointer to a utimbuf struc-
     ture, as defined in <utime.h>:

           struct utimbuf {
                   time_t actime;          /* Access time */
                   time_t modtime;         /* Modification time */
           } ;

     The access time is set to the value of the actime member, and the modifi-
     cation time is set to the value of the modtime member.  The times are
     measured in seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970,
     Coordinated Universal Time.  The calling process must be the owner of the
     file or be the super-user.

     In either case, the inode-change-time of the file is set to the current
     time.


RETURN VALUES

     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.


ERRORS

     Utime() will fail if:

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

     [EFAULT]      File or times points outside the process's allocated ad-
                   dress space.

     [EINVAL]      The pathname contains a character with the high-order bit
                   set.

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

     [ELOOP]       Too many symbolic links were encountered in translating the
                   pathname.

     [ENAMETOOLONG]
                   A component of a pathname exceeded 255 characters, or an

                   entire path name exceeded 1023 characters.

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

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


SEE ALSO

     stat(2),  utimes(2)


STANDARDS

     The utime() function conforms to IEEE Std1003.1-1990 (``POSIX'').


HISTORY

     A utime() function appeared in Version 7 AT&T UNIX.

4th Berkeley Distribution       August 13, 1993                              2