bsd/man/man2/utimes.2

   1 .\"     $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)utimes.2    8.1 (Berkeley) 6/4/93
  35 .\" $FreeBSD: src/lib/libc/sys/utimes.2,v 1.8.2.4 2001/12/14 18:34:02 ru Exp $
  36 .\"
  37 .Dd June 4, 1993
  38 .Dt UTIMES 2
  39 .Os
  40 .Sh NAME
  41 .Nm futimes ,
  42 .Nm utimes
  43 .Nd set file access and modification times
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In sys/time.h
  48 .Ft int
  49 .Fo futimes
  50 .Fa "int fildes"
  51 .Fa "const struct timeval times[2]"
  52 .Fc
  53 .Ft int
  54 .Fo utimes
  55 .Fa "const char *path"
  56 .Fa "const struct timeval times[2]"
  57 .Fc
  58 .Sh DESCRIPTION
  59 The access and modification times of the file named by
  60 .Fa path
  61 or referenced by
  62 .Fa fildes
  63 are changed as specified by the argument
  64 .Fa times .
  65 .Pp
  66 If
  67 .Fa times
  68 is
  69 .Dv NULL ,
  70 the access and modification times are set to the current time.
  71 The caller must be the owner of the file, have permission to
  72 write the file, or be the super-user.
  73 .Pp
  74 If
  75 .Fa times
  76 is
  77 .Pf non- Dv NULL ,
  78 it is assumed to point to an array of two timeval structures.
  79 The access time is set to the value of the first element, and the
  80 modification time is set to the value of the second element.
  81 The caller must be the owner of the file or be the super-user.
  82 .Pp
  83 In either case, the inode-change-time of the file is set to the current
  84 time.
  85 .Sh RETURN VALUES
  86 .Rv -std
  87 .Sh ERRORS
  88 The
  89 .Fn utimes
  90 system call will fail if:
  91 .Bl -tag -width Er
  92 .\" ===========
  93 .It Bq Er EACCES
  94 Search permission is denied for a component of the path prefix;
  95 or the
  96 .Fa times
  97 argument is
  98 .Dv NULL
  99 and the effective user ID of the process does not
 100 match the owner of the file, and is not the super-user, and write
 101 access is denied.
 102 .\" ===========
 103 .It Bq Er EFAULT
 104 .Fa path
 105 or
 106 .Fa times
 107 points outside the process's allocated address space.
 108 .\" ===========
 109 .It Bq Er EIO
 110 An I/O error occurs while reading or writing the affected inode.
 111 .\" ===========
 112 .It Bq Er ELOOP
 113 Too many symbolic links are encountered in translating the pathname.
 114 This is taken to be indicative of a looping symbolic link.
 115 .\" ===========
 116 .It Bq Er ENAMETOOLONG
 117 A component of a pathname exceeds
 118 .Dv NAME_MAX
 119 characters, or an entire path name exceeded
 120 .Dv PATH_MAX
 121 characters.
 122 .\" ===========
 123 .It Bq Er ENOENT
 124 The named file does not exist.
 125 .\" ===========
 126 .It Bq Er ENOTDIR
 127 A component of the path prefix is not a directory.
 128 .\" ===========
 129 .It Bq Er EPERM
 130 The
 131 .Fa times
 132 argument is not
 133 .Dv NULL
 134 and the calling process's effective user ID
 135 does not match the owner of the file and is not the super-user.
 136 .\" ===========
 137 .It Bq Er EROFS
 138 The file system containing the file is mounted read-only.
 139 .El
 140 .Pp
 141 The
 142 .Fn futimes
 143 system call will fail if:
 144 .Bl -tag -width Er
 145 .\" ===========
 146 .It Bq Er EBADF
 147 .Fa fildes
 148 does not refer to a valid descriptor.
 149 .El
 150 .Pp
 151 All of the functions will fail if:
 152 .Bl -tag -width Er
 153 .\" ===========
 154 .It Bq Er EACCES
 155 The
 156 .Fa times
 157 argument is
 158 .Dv NULL
 159 and the effective user ID of the process does not
 160 match the owner of the file, and is not the super-user, and write
 161 access is denied.
 162 .\" ===========
 163 .It Bq Er EFAULT
 164 .Fa times
 165 points outside the process's allocated address space.
 166 .\" ===========
 167 .It Bq Er EIO
 168 An I/O error occurred while reading or writing the affected inode.
 169 .\" ===========
 170 .It Bq Er EPERM
 171 The
 172 .Fa times
 173 argument is not
 174 .Dv NULL
 175 and the calling process's effective user ID
 176 does not match the owner of the file and is not the super-user.
 177 .\" ===========
 178 .It Bq Er EROFS
 179 The file system containing the file is mounted read-only.
 180 .El
 181 .Sh SEE ALSO
 182 .Xr stat 2 ,
 183 .Xr utime 3
 184 .Sh HISTORY
 185 The
 186 .Fn utimes
 187 function call appeared in
 188 .Bx 4.2 .
 189 The
 190 .Fn futimes
 191 function call first appeared in
 192 .Fx 3.0 .