1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  44 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
  45 .\" Copyright (c) 2014, Joyent, Inc.
  46 .\"
  47 .TH UTIMES 2 "Dec 20, 2014"
  48 .SH NAME
  49 utimes, futimesat \- set file access and modification times
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <sys/time.h>
  54 
  55 \fBint\fR \fButimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
  56 .fi
  57 
  58 .LP
  59 .nf
  60 \fBint\fR \fBfutimesat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
  61      \fBconst struct timeval\fR \fItimes\fR[2]);
  62 .fi
  63 
  64 .LP
  65 .nf
  66 #include <sys/stat.h>
  67 
  68 \fBint\fR \fBfutimens\fR(\fBint\fR \fIfiledes\fR, \fBconst timespec_t\fR \fInstimes[2]\fR);
  69 
  70 \fBint\fR \fButimensat\fR(\fBint\fR \fIfiledes\fR, \fBconst char *\fR\fIpath\fR,
  71     \fBconst timespec_t\fR \fInstimes[2]\fR, \fBint\fR \fIflag\fR);
  72 
  73 .SH DESCRIPTION
  74 .LP
  75 The \fButimes()\fR function sets the access and modification times of the file
  76 pointed to by the \fIpath\fR argument to the value of the \fItimes\fR argument.
  77 It allows time specifications accurate to the microsecond.
  78 .sp
  79 .LP
  80 The \fBfutimesat()\fR function also sets access and modification times.  See
  81 \fBfsattr\fR(5). If \fIpath\fR is a relative path name, however,
  82 \fBfutimesat()\fR resolves the path relative to the \fIfildes\fR argument
  83 rather than the current working directory.  If \fIfildes\fR is set to
  84 \fBAT_FDCWD\fR, defined in <\fBfcntl.h\fR>, \fBfutimesat()\fR resolves the path
  85 relative to the current working directory.  If \fIpath\fR is a null pointer,
  86 \fBfutimesat()\fR sets the access and modification times on the file referenced
  87 by \fIfildes\fR. The \fIfildes\fR argument is ignored even when
  88 \fBfutimesat()\fR is provided with an absolute path.
  89 .sp
  90 .LP
  91 The \fItimes\fR argument is an array of \fBtimeval\fR structures. The first
  92 array member represents the date and time of last access, and the second member
  93 represents the date and time of last modification.  The times in the
  94 \fBtimeval\fR structure are measured in seconds and microseconds since the
  95 Epoch, although rounding toward the nearest second may occur.
  96 .sp
  97 .LP
  98 If the \fItimes\fR argument is a null pointer, the access and modification
  99 times of the file are set to the current time.  The effective user \fBID\fR of
 100 the process must be the same as the owner of the file, or must have write
 101 access to the file or the {\fBPRIV_FILE_OWNER\fR} privilege to use this call in
 102 this manner. Upon completion, \fButimes()\fR will mark the time of the last
 103 file status change, \fBst_ctime\fR, for update.
 104 .sp
 105 .LP
 106 The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
 107 modification times; however, instead of taking \fBstruct timeval\fR, they take
 108 \fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
 109 function sets the access and modification times on the file descriptor
 110 referenced by \fIfiledes\fR.
 111 .sp
 112 .LP
 113 The \fButimensat()\fR function determines the file to set the access and
 114 modification times in an similar way to \fBfutemsat()\fR. If the argument
 115 \fIpath\fR is an absolute path, then the argument \fIfiledes\fR is ignored;
 116 otherwise, \fIpath\fR is interpreted as a path relative to the directory
 117 specified by \fIfiledes\fR. If \fIfiledes\fR is set to \fBAT_FDCWD\fR, then
 118 \fIpath\fR is resolved relative to the current working directory. The behavior
 119 when encountering symbolic links may be controlled by the value of the
 120 \fIflag\fR argument. If the value of flag is the constant
 121 \fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
 122 resolving a path, it will not be followed. Otherwise, the value of \fIflag\fR
 123 should be \fB0\fR.
 124 .SH RETURN VALUES
 125 .LP
 126 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
 127 returned, \fBerrno\fR is set to indicate the error, and the file times will not
 128 be affected.
 129 .SH ERRORS
 130 .LP
 131 The \fButimes()\fR, \fBfutimesat()\fR, \fBfutimens()\fR, and \fButimensat()\fR
 132 functions will fail if:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBEACCES\fR\fR
 137 .ad
 138 .RS 16n
 139 Search permission is denied by a component of the path prefix; or the
 140 \fItimes\fR argument is a null pointer and the effective user \fBID\fR of the
 141 process does not match the owner of the file and write access is denied.
 142 .RE
 143 
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBEFAULT\fR\fR
 148 .ad
 149 .RS 16n
 150 The \fIpath\fR or \fItimes\fR argument points to an illegal address. For
 151 \fBfutimesat()\fR, \fIpath\fR might have the value \fINULL\fR if the
 152 \fIfildes\fR argument refers to a valid open file descriptor.
 153 .RE
 154 
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBEINTR\fR\fR
 159 .ad
 160 .RS 16n
 161 A signal was caught during the execution of the \fButimes()\fR,
 162 \fBfutimesat()\fR, \fBfutimens()\fR, or \fButimensat()\fR functions.
 163 .RE
 164 
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEINVAL\fR\fR
 169 .ad
 170 .RS 16n
 171 The number of microseconds specified in one or both of the \fBtimeval\fR
 172 structures pointed to by \fItimes\fR was greater than or equal to 1,000,000 or
 173 less than 0. The number of nanoseconds specified in one or both of the
 174 \fBtimespec_t\fR structures pointed to by \fInstimes\fR was greater than or
 175 equal to 1,000,000,000 or less than 0.
 176 .RE
 177 
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBEIO\fR\fR
 182 .ad
 183 .RS 16n
 184 An I/O error occurred while reading from or writing to the file system.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBELOOP\fR\fR
 191 .ad
 192 .RS 16n
 193 Too many symbolic links were encountered in resolving \fIpath\fR.
 194 .RE
 195 
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBENAMETOOLONG\fR\fR
 200 .ad
 201 .RS 16n
 202 The length of the \fIpath\fR argument exceeds {\fIPATH_MAX\fR} or a pathname
 203 component is longer than {\fINAME_MAX\fR}.
 204 .RE
 205 
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBENOLINK\fR\fR
 210 .ad
 211 .RS 16n
 212 The \fIpath\fR argument points to a remote machine and the link to that machine
 213 is no longer active.
 214 .RE
 215 
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBENOENT\fR\fR
 220 .ad
 221 .RS 16n
 222 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
 223 empty string.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBENOTDIR\fR\fR
 230 .ad
 231 .RS 16n
 232 A component of the path prefix is not a directory or the \fIpath\fR argument is
 233 relative and the \fIfildes\fR argument is not \fBAT_FDCWD\fR or does not refer
 234 to a valid directory.
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBEPERM\fR\fR
 241 .ad
 242 .RS 16n
 243 The \fItimes\fR argument is not a null pointer and the calling process's
 244 effective user \fBID\fR has write access to the file but does not match the
 245 owner of the file and the calling process does not have the appropriate
 246 privileges.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBEROFS\fR\fR
 253 .ad
 254 .RS 16n
 255 The file system containing the file is read-only.
 256 .RE
 257 
 258 .sp
 259 .LP
 260 The \fButimes()\fR, \fBfutimesat()\fR, and \fButimensat()\fR functions may fail
 261 if:
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBENAMETOOLONG\fR\fR
 266 .ad
 267 .RS 16n
 268 Path name resolution of a symbolic link produced an intermediate result whose
 269 length exceeds {\fIPATH_MAX\fR}.
 270 .RE
 271 
 272 .SH ATTRIBUTES
 273 .LP
 274 See \fBattributes\fR(5) for descriptions of the following attributes:
 275 .sp
 276 
 277 .sp
 278 .TS
 279 box;
 280 c | c
 281 l | l .
 282 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 283 _
 284 Interface Stability     Committed
 285 _
 286 Standard        See below.
 287 .TE
 288 
 289 .sp
 290 .LP
 291 For \fButimes()\fR, \fButimensat()\fR and \fBfutimensat()\fR, see \fBstandards\fR(5).
 292 .SH SEE ALSO
 293 .LP
 294 \fBfutimens\fR(2), \fBstat\fR(2), \fButime\fR(2), \fBattributes\fR(5),
 295 \fBfsattr\fR(5), \fBstandards\fR(5)