Print this page
13111 Want futimes() and lutimes() functions
Change-ID: I3be82d4242255a4100f8c35db373eb9140402fc4
*** 41,92 ****
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2014, Joyent, Inc.
.\"
! .TH UTIMES 2 "Dec 20, 2014"
.SH NAME
! utimes, futimesat \- set file access and modification times
.SH SYNOPSIS
- .LP
.nf
#include <sys/time.h>
\fBint\fR \fButimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
.fi
.LP
.nf
\fBint\fR \fBfutimesat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
\fBconst struct timeval\fR \fItimes\fR[2]);
.fi
.LP
.nf
#include <sys/stat.h>
! \fBint\fR \fBfutimens\fR(\fBint\fR \fIfiledes\fR, \fBconst timespec_t\fR \fInstimes[2]\fR);
! \fBint\fR \fButimensat\fR(\fBint\fR \fIfiledes\fR, \fBconst char *\fR\fIpath\fR,
\fBconst timespec_t\fR \fInstimes[2]\fR, \fBint\fR \fIflag\fR);
.SH DESCRIPTION
- .LP
The \fButimes()\fR function sets the access and modification times of the file
pointed to by the \fIpath\fR argument to the value of the \fItimes\fR argument.
It allows time specifications accurate to the microsecond.
.sp
.LP
The \fBfutimesat()\fR function also sets access and modification times. See
\fBfsattr\fR(5). If \fIpath\fR is a relative path name, however,
\fBfutimesat()\fR resolves the path relative to the \fIfildes\fR argument
rather than the current working directory. If \fIfildes\fR is set to
\fBAT_FDCWD\fR, defined in <\fBfcntl.h\fR>, \fBfutimesat()\fR resolves the path
relative to the current working directory. If \fIpath\fR is a null pointer,
\fBfutimesat()\fR sets the access and modification times on the file referenced
! by \fIfildes\fR. The \fIfildes\fR argument is ignored even when
\fBfutimesat()\fR is provided with an absolute path.
.sp
.LP
The \fItimes\fR argument is an array of \fBtimeval\fR structures. The first
array member represents the date and time of last access, and the second member
--- 41,111 ----
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2014, Joyent, Inc.
+ .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\"
! .TH UTIMES 2 "Sep 06, 2020"
.SH NAME
! utimes, lutimes, futimes, futimesat, utimens, utimensat \- set file access and modification times
.SH SYNOPSIS
.nf
#include <sys/time.h>
\fBint\fR \fButimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
.fi
.LP
.nf
+ \fBint\fR \fBlutimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
+ .fi
+
+ .LP
+ .nf
+ \fBint\fR \fBfutimes\fR(\fBint\fR \fIfildes\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
+ .fi
+
+ .LP
+ .nf
\fBint\fR \fBfutimesat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
\fBconst struct timeval\fR \fItimes\fR[2]);
.fi
.LP
.nf
#include <sys/stat.h>
! \fBint\fR \fBfutimens\fR(\fBint\fR \fIfildes\fR, \fBconst timespec_t\fR \fInstimes[2]\fR);
! \fBint\fR \fButimensat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
\fBconst timespec_t\fR \fInstimes[2]\fR, \fBint\fR \fIflag\fR);
.SH DESCRIPTION
The \fButimes()\fR function sets the access and modification times of the file
pointed to by the \fIpath\fR argument to the value of the \fItimes\fR argument.
It allows time specifications accurate to the microsecond.
.sp
.LP
+ The \fBlutimes()\fR function operates like \fButimes()\fR except if \fIpath\fR
+ points to a symbolic link; in that case \fBlutimes()\fR changes the access and
+ modifications times of the link, while \fButimes()\fR changes the file that
+ is referenced by the link.
+ .sp
+ .LP
+ The \fBfutimes()\fR function sets the access and modification times of the
+ file referenced by the file descriptor \fIfildes\fR.
+ .sp
+ .LP
The \fBfutimesat()\fR function also sets access and modification times. See
\fBfsattr\fR(5). If \fIpath\fR is a relative path name, however,
\fBfutimesat()\fR resolves the path relative to the \fIfildes\fR argument
rather than the current working directory. If \fIfildes\fR is set to
\fBAT_FDCWD\fR, defined in <\fBfcntl.h\fR>, \fBfutimesat()\fR resolves the path
relative to the current working directory. If \fIpath\fR is a null pointer,
\fBfutimesat()\fR sets the access and modification times on the file referenced
! by \fIfildes\fR. The \fIfildes\fR argument is ignored if
\fBfutimesat()\fR is provided with an absolute path.
.sp
.LP
The \fItimes\fR argument is an array of \fBtimeval\fR structures. The first
array member represents the date and time of last access, and the second member
*** 105,136 ****
.LP
The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
modification times; however, instead of taking \fBstruct timeval\fR, they take
\fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
function sets the access and modification times on the file descriptor
! referenced by \fIfiledes\fR.
.sp
.LP
The \fButimensat()\fR function determines the file to set the access and
! modification times in an similar way to \fBfutemsat()\fR. If the argument
! \fIpath\fR is an absolute path, then the argument \fIfiledes\fR is ignored;
otherwise, \fIpath\fR is interpreted as a path relative to the directory
! specified by \fIfiledes\fR. If \fIfiledes\fR is set to \fBAT_FDCWD\fR, then
\fIpath\fR is resolved relative to the current working directory. The behavior
when encountering symbolic links may be controlled by the value of the
\fIflag\fR argument. If the value of flag is the constant
\fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
resolving a path, it will not be followed. Otherwise, the value of \fIflag\fR
! should be \fB0\fR.
.SH RETURN VALUES
- .LP
Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
returned, \fBerrno\fR is set to indicate the error, and the file times will not
be affected.
.SH ERRORS
! .LP
! The \fButimes()\fR, \fBfutimesat()\fR, \fBfutimens()\fR, and \fButimensat()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
--- 124,155 ----
.LP
The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
modification times; however, instead of taking \fBstruct timeval\fR, they take
\fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
function sets the access and modification times on the file descriptor
! referenced by \fIfildes\fR.
.sp
.LP
The \fButimensat()\fR function determines the file to set the access and
! modification times in an similar way to \fBfutimesat()\fR. If the argument
! \fIpath\fR is an absolute path, then the argument \fIfildes\fR is ignored;
otherwise, \fIpath\fR is interpreted as a path relative to the directory
! specified by \fIfildes\fR. If \fIfildes\fR is set to \fBAT_FDCWD\fR, then
\fIpath\fR is resolved relative to the current working directory. The behavior
when encountering symbolic links may be controlled by the value of the
\fIflag\fR argument. If the value of flag is the constant
\fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
resolving a path, it will not be followed. Otherwise, the value of \fIflag\fR
! should be \fB0\fR. Note that, unlike \fBfutimesat()\fR, \fButimensat()\fR
! does not accept a null pointer for the \fIpath\fR argument.
.SH RETURN VALUES
Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
returned, \fBerrno\fR is set to indicate the error, and the file times will not
be affected.
.SH ERRORS
! The \fButimes()\fR, \fBlutimes()\fR, \fBfutimes()\fR, \fBfutimesat()\fR,
! \fBfutimens()\fR, and \fButimensat()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
*** 145,166 ****
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 16n
! The \fIpath\fR or \fItimes\fR argument points to an illegal address. For
! \fBfutimesat()\fR, \fIpath\fR might have the value \fINULL\fR if the
! \fIfildes\fR argument refers to a valid open file descriptor.
.RE
.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 16n
A signal was caught during the execution of the \fButimes()\fR,
\fBfutimesat()\fR, \fBfutimens()\fR, or \fButimensat()\fR functions.
.RE
.sp
.ne 2
--- 164,184 ----
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 16n
! The \fIpath\fR or \fItimes\fR argument points to an illegal address.
.RE
.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 16n
A signal was caught during the execution of the \fButimes()\fR,
+ \fBlutimes()\fR, \fBfutimes()\fR,
\fBfutimesat()\fR, \fBfutimens()\fR, or \fButimensat()\fR functions.
.RE
.sp
.ne 2
*** 268,278 ****
Path name resolution of a symbolic link produced an intermediate result whose
length exceeds {\fIPATH_MAX\fR}.
.RE
.SH ATTRIBUTES
- .LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
--- 286,295 ----
*** 288,295 ****
.sp
.LP
For \fButimes()\fR, \fButimensat()\fR and \fBfutimensat()\fR, see \fBstandards\fR(5).
.SH SEE ALSO
! .LP
! \fBfutimens\fR(2), \fBstat\fR(2), \fButime\fR(2), \fBattributes\fR(5),
\fBfsattr\fR(5), \fBstandards\fR(5)
--- 305,311 ----
.sp
.LP
For \fButimes()\fR, \fButimensat()\fR and \fBfutimensat()\fR, see \fBstandards\fR(5).
.SH SEE ALSO
! fBstat\fR(2), \fButime\fR(2), \fBattributes\fR(5),
\fBfsattr\fR(5), \fBstandards\fR(5)