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/sys/utimes.2 | |
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/sys/utimes.2')
-rw-r--r-- | lib/libc/sys/utimes.2 | 120 |
1 files changed, 95 insertions, 25 deletions
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 . |