mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-06 17:18:32 +00:00
Document the lutimes() and futimes() system calls.
PR: kern/11213 Obtained from: NetBSD w/some minor changes by me
This commit is contained in:
parent
733e6274d7
commit
db58ff7d87
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=49249
|
@ -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)
|
||||
|
|
|
@ -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
|
||||
If
|
||||
.Fa times
|
||||
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
|
||||
.Fa times
|
||||
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
|
||||
If the times are specified (the
|
||||
.Fa times
|
||||
argument is
|
||||
.Pf non- Dv NULL )
|
||||
the caller must be the owner of the file or be the super-user.
|
||||
.Pp
|
||||
If the times are not specified (the
|
||||
.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.
|
||||
.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 .
|
||||
|
|
Loading…
Reference in a new issue