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