diff options
author | mpp <mpp@FreeBSD.org> | 1999-07-30 09:01:45 +0000 |
---|---|---|
committer | mpp <mpp@FreeBSD.org> | 1999-07-30 09:01:45 +0000 |
commit | 25e85c42a745fff0156b668de8771cd5b4fac041 (patch) | |
tree | ecf85e58c8a1a2b891f29dfadb26ce52e675a204 /lib/libc | |
parent | 3c387886064bc9a59a81eb6e634cf28b91f848bb (diff) | |
download | FreeBSD-src-25e85c42a745fff0156b668de8771cd5b4fac041.zip FreeBSD-src-25e85c42a745fff0156b668de8771cd5b4fac041.tar.gz |
Document the lutimes() and futimes() system calls.
PR: kern/11213
Obtained from: NetBSD w/some minor changes by me
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/sys/Makefile.inc | 3 | ||||
-rw-r--r-- | lib/libc/sys/utimes.2 | 120 |
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 . |