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 utimes ,
  42 .Nm futimes
  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 .Fn utimes "const char *path" "const struct timeval *times"
  50 .Ft int
  51 .Fn futimes "int fd" "const struct timeval *times"
  52 .Sh DESCRIPTION
  53 The access and modification times of the file named by
  54 .Fa path
  55 or referenced by
  56 .Fa fd
  57 are changed as specified by the argument
  58 .Fa times .
  59 .Pp
  60 If
  61 .Fa times
  62 is
  63 .Dv NULL ,
  64 the access and modification times are set to the current time.
  65 The caller must be the owner of the file, have permission to
  66 write the file, or be the super-user.
  67 .Pp
  68 If
  69 .Fa times
  70 is
  71 .Pf non- Dv NULL ,
  72 it is assumed to point to an array of two timeval structures.
  73 The access time is set to the value of the first element, and the
  74 modification time is set to the value of the second element.
  75 The caller must be the owner of the file or be the super-user.
  76 .Pp
  77 In either case, the inode-change-time of the file is set to the current
  78 time.
  79 .Sh RETURN VALUES
  80 .Rv -std
  81 .Sh ERRORS
  82 .Fn utimes
  83 will fail if:
  84 .Bl -tag -width Er
  85 .It Bq Er EACCES
  86 Search permission is denied for a component of the path prefix;
  87 or the
  88 .Fa times
  89 argument is
  90 .Dv NULL
  91 and the effective user ID of the process does not
  92 match the owner of the file, and is not the super-user, and write
  93 access is denied.
  94 .It Bq Er EFAULT
  95 .Fa path
  96 or
  97 .Fa times
  98 points outside the process's allocated address space.
  99 .It Bq Er EIO
 100 An I/O error occurred while reading or writing the affected inode.
 101 .It Bq Er ELOOP
 102 Too many symbolic links were encountered in translating the pathname.
 103 .It Bq Er ENAMETOOLONG
 104 A component of a pathname exceeded
 105 .Dv NAME_MAX
 106 characters, or an entire path name exceeded
 107 .Dv PATH_MAX
 108 characters.
 109 .It Bq Er ENOENT
 110 The named file does not exist.
 111 .It Bq Er ENOTDIR
 112 A component of the path prefix is not a directory.
 113 .It Bq Er EPERM
 114 The
 115 .Fa times
 116 argument is not
 117 .Dv NULL
 118 and the calling process's effective user ID
 119 does not match the owner of the file and is not the super-user.
 120 .It Bq Er EROFS
 121 The file system containing the file is mounted read-only.
 122 .El
 123 .Pp
 124 .Fn futimes
 125 will fail if:
 126 .Bl -tag -width Er
 127 .It Bq Er EBADF
 128 .Fa fd
 129 does not refer to a valid descriptor.
 130 .El
 131 .Pp
 132 All of the functions will fail if:
 133 .Bl -tag -width Er
 134 .It Bq Er EACCES
 135 The
 136 .Fa times
 137 argument is
 138 .Dv NULL
 139 and the effective user ID of the process does not
 140 match the owner of the file, and is not the super-user, and write
 141 access is denied.
 142 .It Bq Er EFAULT
 143 .Fa times
 144 points outside the process's allocated address space.
 145 .It Bq Er EIO
 146 An I/O error occurred while reading or writing the affected inode.
 147 .It Bq Er EPERM
 148 The
 149 .Fa times
 150 argument is not
 151 .Dv NULL
 152 and the calling process's effective user ID
 153 does not match the owner of the file and is not the super-user.
 154 .It Bq Er EROFS
 155 The file system containing the file is mounted read-only.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr stat 2 ,
 159 .Xr utime 3
 160 .Sh HISTORY
 161 The
 162 .Fn utimes
 163 function call appeared in
 164 .Bx 4.2 .
 165 The
 166 .Fn futimes
 167 function call first appeared in
 168 .Fx 3.0 .