usr/src/man/man2/utime.2

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH UTIME 2 "Sep 1, 2009"
   8 .SH NAME
   9 utime \- set file access and modification times
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <utime.h>
  15
  16 \fBint\fR \fButime\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct utimbuf *\fR\fItimes\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fButime()\fR function sets the access and modification times of the file
  23 pointed to by \fIpath\fR,  and causes the time of the last file status change
  24 (\fBst_ctime\fR) to be updated.
  25 .sp
  26 .LP
  27 If \fItimes\fR is \fINULL\fR, the access and modification times of the file are
  28 set to the current time. A process must be the owner of the file or have write
  29 permission to use \fButime()\fR in this manner.
  30 .sp
  31 .LP
  32 If \fItimes\fR is not \fINULL\fR, \fItimes\fR is interpreted as a pointer to a
  33 \fButimbuf\fR structure (defined in <\fButime.h\fR>) and the access and
  34 modification times are set to the values contained in the designated structure.
  35 Only the owner of the file or a process that has the {\fBPRIV_FILE_OWNER\fR}
  36 privilege asserted in its effective set can use \fButime()\fR in this manner.
  37 .sp
  38 .LP
  39 The \fButimbuf\fR structure contains the following members:
  40 .sp
  41 .in +2
  42 .nf
  43 time_t   actime;    /* access time */
  44 time_t   modtime;   /* modification time */
  45 .fi
  46 .in -2
  47
  48 .sp
  49 .LP
  50 The times contained in the members of the \fButimbuf\fR structure are measured
  51 in seconds since 00:00:00 UTC, January 1, 1970.
  52 .SH RETURN VALUES
  53 .sp
  54 .LP
  55 Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and
  56 \fBerrno\fR is set to indicate the error.
  57 .SH ERRORS
  58 .sp
  59 .LP
  60 The \fButime()\fR function will fail if:
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBEACCES\fR\fR
  65 .ad
  66 .RS 16n
  67 Search permission is denied by a component of the \fIpath\fR prefix.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBEACCES\fR\fR
  74 .ad
  75 .RS 16n
  76 The process does not have appropriate privileges and is not the owner of the
  77 file, write permission is denied for the file, and \fItimes\fR is \fINULL\fR.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBEFAULT\fR\fR
  84 .ad
  85 .RS 16n
  86 The \fIpath\fR argument points to an illegal address.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBEINTR\fR\fR
  93 .ad
  94 .RS 16n
  95 A signal was caught during the execution of the \fButime()\fR function.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBEIO\fR\fR
 102 .ad
 103 .RS 16n
 104 An I/O error occurred while reading from or writing to the file system.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBELOOP\fR\fR
 111 .ad
 112 .RS 16n
 113 Too many symbolic links were encountered in translating \fIpath\fR.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBENAMETOOLONG\fR\fR
 120 .ad
 121 .RS 16n
 122 The length of the \fIpath\fR argument exceeds \fIPATH_MAX\fR, or the length of
 123 a \fIpath\fR component exceeds \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in
 124 effect.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBENOENT\fR\fR
 131 .ad
 132 .RS 16n
 133 The named file does not exist or is a null pathname.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBENOLINK\fR\fR
 140 .ad
 141 .RS 16n
 142 The \fIpath\fR argument points to a remote machine and the link to that machine
 143 is no longer active.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBENOTDIR\fR\fR
 150 .ad
 151 .RS 16n
 152 A component of the \fIpath\fR prefix is not a directory.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBEPERM\fR\fR
 159 .ad
 160 .RS 16n
 161 The effective user of the calling process is not the owner of the file,
 162 {\fBPRIV_FILE_OWNER\fR} is not asserted in the effective set of the calling
 163 process, and \fItimes\fR is not \fINULL\fR.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBEROFS\fR\fR
 170 .ad
 171 .RS 16n
 172 The file system containing the file is mounted read-only.
 173 .RE
 174
 175 .SH ATTRIBUTES
 176 .sp
 177 .LP
 178 See \fBattributes\fR(5) for descriptions of the following attributes:
 179 .sp
 180
 181 .sp
 182 .TS
 183 box;
 184 c | c
 185 l | l .
 186 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 187 _
 188 Interface Stability     Committed
 189 _
 190 MT-Level        Async-Signal-Safe
 191 _
 192 Standard        See \fBstandards\fR(5).
 193 .TE
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBfutimens\fR(2), \fBstat\fR(2), \fButimes\fR(2), \fBattributes\fR(5),
 199 \fBprivileges\fR(5), \fBstandards\fR(5)