Annotation of src/lib/libc/gen/utime.3, Revision 1.16
1.16 ! simonb 1: .\" $NetBSD: utime.3,v 1.15 2002/02/07 07:00:18 ross Exp $
1.7 cgd 2: .\"
3: .\" Copyright (c) 1980, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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: .\"
1.7 cgd 34: .\" @(#)utime.3 8.1 (Berkeley) 6/4/93
1.1 cgd 35: .\"
1.3 jtc 36: .Dd August 13, 1993
1.1 cgd 37: .Dt UTIME 3
1.14 garbled 38: .Os
1.1 cgd 39: .Sh NAME
40: .Nm utime
41: .Nd set file times
1.10 perry 42: .Sh LIBRARY
43: .Lb libc
1.1 cgd 44: .Sh SYNOPSIS
1.15 ross 45: .Fd #include \*[Lt]utime.h\*[Gt]
1.1 cgd 46: .Ft int
47: .Fn utime "const char *file" "const struct utimbuf *timep"
48: .Sh DESCRIPTION
1.7 cgd 49: .Bf -symbolic
1.11 fair 50: This interface is obsoleted by
51: .Xr utimes 2 .
1.7 cgd 52: .Ef
53: .Pp
1.1 cgd 54: The
55: .Fn utime
1.3 jtc 56: function sets the access and modification times of the named file.
57: .Pp
58: If
59: .Fa timep
60: is
61: .Dv NULL ,
62: the access and modification times are set to the current time.
1.12 fair 63: The calling process must be the owner of the file or have permission to
1.3 jtc 64: write the file.
65: .Pp
1.12 fair 66: If
1.3 jtc 67: .Fa timep
1.12 fair 68: is
1.3 jtc 69: .Pf non- Dv NULL ,
1.12 fair 70: .Fa time
71: is assumed to be a pointer to a utimbuf structure, as defined in
1.3 jtc 72: .Aq Pa utime.h :
73: .Bd -literal -offset indent
74: struct utimbuf {
75: time_t actime; /* Access time */
76: time_t modtime; /* Modification time */
1.12 fair 77: };
1.3 jtc 78: .Ed
79: .Pp
1.12 fair 80: The access time is set to the value of the actime member, and the
81: modification time is set to the value of the modtime member.
82: The times are measured in seconds since 0 hours, 0 minutes, 0
83: seconds, January 1, 1970 Coordinated Universal Time (UTC).
1.3 jtc 84: The calling process must be the owner of the file or be the super-user.
1.1 cgd 85: .Pp
1.12 fair 86: In either case, the inode-change-time of the file is set to the current
1.3 jtc 87: time.
1.4 jtc 88: .Sh RETURN VALUES
89: Upon successful completion, a value of 0 is returned.
90: Otherwise, a value of -1 is returned and
91: .Va errno
92: is set to indicate the error.
93: .Sh ERRORS
1.13 lukem 94: .Fn utime
1.4 jtc 95: will fail if:
96: .Bl -tag -width Er
97: .It Bq Er EACCES
98: Search permission is denied for a component of the path prefix;
99: or the
100: .Fa times
101: argument is
102: .Dv NULL
103: and the effective user ID of the process does not
104: match the owner of the file, and is not the super-user, and write
105: access is denied.
106: .It Bq Er EFAULT
1.12 fair 107: .Fa file
1.4 jtc 108: or
109: .Fa times
110: points outside the process's allocated address space.
111: .It Bq Er EINVAL
112: The pathname contains a character with the high-order bit set.
113: .It Bq Er EIO
114: An I/O error occurred while reading or writing the affected inode.
115: .It Bq Er ELOOP
116: Too many symbolic links were encountered in translating the pathname.
117: .It Bq Er ENAMETOOLONG
118: A component of a pathname exceeded 255 characters,
119: or an entire path name exceeded 1023 characters.
120: .It Bq Er ENOENT
121: The named file does not exist.
122: .It Bq Er ENOTDIR
123: A component of the path prefix is not a directory.
124: .It Bq Er EPERM
125: The
126: .Fa times
127: argument is not
128: .Dv NULL
129: and the calling process's effective user ID
130: does not match the owner of the file and is not the super-user.
131: .It Bq Er EROFS
132: The file system containing the file is mounted read-only.
133: .El
1.1 cgd 134: .Sh SEE ALSO
1.3 jtc 135: .Xr stat 2 ,
136: .Xr utimes 2
1.9 jtc 137: .Sh STANDARDS
138: The
139: .Fn utime
140: function conforms to
141: .St -p1003.1-90 .
1.7 cgd 142: .Sh HISTORY
143: A
144: .Fn utime
145: function appeared in
146: .At v7 .
CVSweb <webmaster@jp.NetBSD.org>