Document the lutimes() and futimes() system calls.

PR:		kern/11213
Obtained from:	NetBSD w/some minor changes by me

2 files changed, 97 insertions, 26 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 292860d..11f80e0 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,5 +1,5 @@
 #	@(#)Makefile.inc	8.3 (Berkeley) 10/24/94
-#	$Id: Makefile.inc,v 1.61 1999/04/11 21:14:40 dt Exp $
+#	$Id: Makefile.inc,v 1.62 1999/04/28 11:38:32 phk Exp $
 
 # sys sources
 .PATH: ${.CURDIR}/../libc/${MACHINE_ARCH}/sys ${.CURDIR}/../libc/sys
@@ -134,6 +134,7 @@ MLINKS+=stat.2 fstat.2 stat.2 lstat.2
 MLINKS+=statfs.2 fstatfs.2
 MLINKS+=syscall.2 __syscall.2
 MLINKS+=truncate.2 ftruncate.2
+MLINKS+=utimes.2 lutimes.2 utimes.2 futimes.2
 MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2
 MLINKS+=write.2 pwrite.2 write.2 writev.2
 .if !defined(NO_P1003_1B)
diff --git a/lib/libc/sys/utimes.2 b/lib/libc/sys/utimes.2
index ca02360..2b0e77e 100644
--- a/lib/libc/sys/utimes.2
+++ b/lib/libc/sys/utimes.2
@@ -1,3 +1,5 @@
+.\"	$NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
+.\"
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -30,47 +32,71 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
-.\"     $Id$
+.\"	$Id"
 .\"
 .Dd June 4, 1993
 .Dt UTIMES 2
-.Os BSD 4
+.Os
 .Sh NAME
-.Nm utimes
+.Nm utimes ,
+.Nm lutimes ,
+.Nm futimes
 .Nd set file access and modification times
 .Sh SYNOPSIS
 .Fd #include <sys/time.h>
 .Ft int
-.Fn utimes "const char *file" "const struct timeval *times"
+.Fn utimes "const char *path" "const struct timeval *times"
+.Ft int
+.Fn lutimes "const char *path" "const struct timeval *times"
+.Ft int
+.Fn futimes "int fd" "const struct timeval *times"
 .Sh DESCRIPTION
-The
-.Fn utimes
-function sets the access and modification times of the named file from
-the structures in the argument array
+The access and modification times of the file named by
+.Fa path
+or referenced by
+.Fa fd
+are changed as specified by the argument
 .Fa times .
 .Pp
-The first structure is the access time, and the second is the modification
-time.
-.Pp
-If the times are specified (the
+If 
 .Fa times
-argument is
-.Pf non- Dv NULL )
-the caller must be the owner of the file or be the super-user.
+is 
+.Dv NULL ,
+the access and modification times are set to the current time.
+The caller must be the owner of the file, have permission to
+write the file, or be the super-user.
 .Pp
-If the times are not specified (the
+If
 .Fa times
-argument is
-.Dv NULL )
-the caller must be the owner of the file, have permission to
-write the file, or be the super-user.
+is
+.Pf non- Dv NULL , 
+it is assumed to point to an array of two timeval structures.
+The access time is set to the value of the first element, and the
+modification time is set to the value of the second element.
+The caller must be the owner of the file or be the super-user.
+.Pp
+In either case, the inode-change-time of the file is set to the current
+time.
+.Pp
+.Fn lutimes
+is like
+.Fn utimes
+except in the case where the named file is a symbolic link,
+in which case
+.Fn lutimes
+changes the access and modification times of the link,
+while
+.Fn utimes
+changes the times of the file the link references.
 .Sh RETURN VALUES
 Upon successful completion, a value of 0 is returned.
 Otherwise, a value of -1 is returned and
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Utimes
+.Fn utimes
+and
+.Fn lutimes
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EACCES
@@ -83,7 +109,7 @@ and the effective user ID of the process does not
 match the owner of the file, and is not the super-user, and write
 access is denied.
 .It Bq Er EFAULT
-.Fa File
+.Fa path
 or
 .Fa times
 points outside the process's allocated address space.
@@ -92,8 +118,11 @@ An I/O error occurred while reading or writing the affected inode.
 .It Bq Er ELOOP
 Too many symbolic links were encountered in translating the pathname.
 .It Bq Er ENAMETOOLONG
-A component of a pathname exceeded 255 characters,
-or an entire path name exceeded 1023 characters.
+A component of a pathname exceeded 
+.Dv {NAME_MAX}
+characters, or an entire path name exceeded 
+.Dv {PATH_MAX}
+characters.
 .It Bq Er ENOENT
 The named file does not exist.
 .It Bq Er ENOTDIR
@@ -108,10 +137,51 @@ does not match the owner of the file and is not the super-user.
 .It Bq Er EROFS
 The file system containing the file is mounted read-only.
 .El
+.Pp
+.Fn futimes
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+.Fa fd
+does not refer to a valid descriptor.
+.El
+.Pp
+All of the functions will fail if:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The
+.Fa times
+argument is
+.Dv NULL
+and the effective user ID of the process does not
+match the owner of the file, and is not the super-user, and write
+access is denied.
+.It Bq Er EFAULT
+.Fa times
+points outside the process's allocated address space.
+.It Bq Er EIO
+An I/O error occurred while reading or writing the affected inode.
+.It Bq Er EPERM
+The
+.Fa times
+argument is not
+.Dv NULL
+and the calling process's effective user ID
+does not match the owner of the file and is not the super-user.
+.It Bq Er EROFS
+The file system containing the file is mounted read-only.
+.El
 .Sh SEE ALSO
-.Xr stat 2
+.Xr stat 2 ,
+.Xr utime 3
 .Sh HISTORY
 The
 .Fn utimes
 function call appeared in
 .Bx 4.2 .
+The
+.Fn futimes
+and
+.Fn lutimes
+function calls first appeared in
+.Fx 3.0 .