system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-09-06 17:18:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse source 
PR:		kern/11213
Obtained from:	NetBSD w/some minor changes by me
This commit is contained in:
Mike Pritchard 1999-07-30 09:01:45 +00:00
parent 733e6274d7
commit db58ff7d87
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=49249
2 changed files with 98 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
lib/libc/sys/Makefile.inc
View file

@ -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)

122
lib/libc/sys/utimes.2
View file

@ -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 .