Changeset View
Changeset View
Standalone View
Standalone View
head/lib/libc/sys/stat.2
Show All 22 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)stat.2 8.4 (Berkeley) 5/1/95 | .\" @(#)stat.2 8.4 (Berkeley) 5/1/95 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd October 20, 2018 | .Dd November 11, 2018 | ||||
.Dt STAT 2 | .Dt STAT 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm stat , | .Nm stat , | ||||
.Nm lstat , | .Nm lstat , | ||||
.Nm fstat , | .Nm fstat , | ||||
.Nm fstatat | .Nm fstatat | ||||
.Nd get file status | .Nd get file status | ||||
Show All 39 Lines | |||||
The | The | ||||
.Fn fstatat | .Fn fstatat | ||||
system call is equivalent to | system call is equivalent to | ||||
.Fn stat | .Fn stat | ||||
and | and | ||||
.Fn lstat | .Fn lstat | ||||
except when the | except when the | ||||
.Fa path | .Fa path | ||||
specifies a relative path. | specifies a relative path, or the | ||||
In this case the status is retrieved from a file relative to | .Dv AT_BENEATH | ||||
flag is provided. | |||||
For | |||||
.Fn fstatat | |||||
and relative | |||||
.Fa path , | |||||
the status is retrieved from a file relative to | |||||
the directory associated with the file descriptor | the directory associated with the file descriptor | ||||
.Fa fd | .Fa fd | ||||
instead of the current working directory. | instead of the current working directory. | ||||
For | |||||
.Dv AT_BENEATH | |||||
and absolute | |||||
.Fa path , | |||||
the status is retrieved from a file specified by the | |||||
.Fa path , | |||||
but additional permission checks are performed, see below. | |||||
.Pp | .Pp | ||||
The values for the | The values for the | ||||
.Fa flag | .Fa flag | ||||
are constructed by a bitwise-inclusive OR of flags from this list, | are constructed by a bitwise-inclusive OR of flags from this list, | ||||
defined in | defined in | ||||
.In fcntl.h : | .In fcntl.h : | ||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
.It Dv AT_SYMLINK_NOFOLLOW | .It Dv AT_SYMLINK_NOFOLLOW | ||||
If | If | ||||
.Fa path | .Fa path | ||||
names a symbolic link, the status of the symbolic link is returned. | names a symbolic link, the status of the symbolic link is returned. | ||||
.It Dv AT_BENEATH | .It Dv AT_BENEATH | ||||
Only stat files and directories below the starting directory. | Only stat files and directories below the topping directory. | ||||
See the description of the | See the description of the | ||||
.Dv O_BENEATH | .Dv O_BENEATH | ||||
flag in the | flag in the | ||||
.Xr open 2 | .Xr open 2 | ||||
manual page. | manual page. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
If | If | ||||
.Fn fstatat | .Fn fstatat | ||||
is passed the special value | is passed the special value | ||||
.Dv AT_FDCWD | .Dv AT_FDCWD | ||||
in the | in the | ||||
.Fa fd | .Fa fd | ||||
parameter, the current working directory is used and the behavior is | parameter, the current working directory is used and the behavior is | ||||
identical to a call to | identical to a call to | ||||
.Fn stat | .Fn stat | ||||
or | or | ||||
.Fn lstat | .Fn lstat | ||||
respectively, depending on whether or not the | respectively, depending on whether or not the | ||||
.Dv AT_SYMLINK_NOFOLLOW | .Dv AT_SYMLINK_NOFOLLOW | ||||
bit is set in | bit is set in | ||||
.Fa flag . | .Fa flag . | ||||
.Pp | .Pp | ||||
When | |||||
.Fn fstatat | |||||
is called with an absolute | |||||
.Fa path | |||||
without the | |||||
.Dv AT_BENEATH | |||||
flag, it ignores the | |||||
.Fa fd | |||||
argument. | |||||
When | |||||
.Dv AT_BENEATH | |||||
is specified with an absolute | |||||
.Fa path , | |||||
a directory passed by the | |||||
.Fa fd | |||||
argument is used as the topping point for the resolution. | |||||
.Pp | |||||
The | The | ||||
.Fa sb | .Fa sb | ||||
argument is a pointer to a | argument is a pointer to a | ||||
.Vt stat | .Vt stat | ||||
structure | structure | ||||
as defined by | as defined by | ||||
.In sys/stat.h | .In sys/stat.h | ||||
and into which information is placed concerning the file. | and into which information is placed concerning the file. | ||||
▲ Show 20 Lines • Show All 264 Lines • ▼ Show 20 Lines | |||||
The | The | ||||
.Fa path | .Fa path | ||||
argument is not an absolute path and | argument is not an absolute path and | ||||
.Fa fd | .Fa fd | ||||
is neither | is neither | ||||
.Dv AT_FDCWD | .Dv AT_FDCWD | ||||
nor a file descriptor associated with a directory. | nor a file descriptor associated with a directory. | ||||
.It Bq Er ENOTCAPABLE | .It Bq Er ENOTCAPABLE | ||||
.Fa path | |||||
is an absolute path, | |||||
or contained a ".." component leading to a | |||||
directory outside of the directory hierarchy specified by | |||||
.Fa fd , | |||||
and the process is in capability mode. | |||||
.It Bq Er ENOTCAPABLE | |||||
The | The | ||||
.Dv AT_BENEATH | .Dv AT_BENEATH | ||||
flag was specified but | flag was provided to | ||||
.Fn fstatat , | |||||
and the absolute | |||||
.Fa path | .Fa path | ||||
is not strictly relative to the starting directory. | does not have its tail fully contained under the topping directory, | ||||
For example, | or the relative | ||||
.Fa path | .Fa path | ||||
is absolute or includes a ".." component that escapes the starting directory. | escapes it. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr access 2 , | .Xr access 2 , | ||||
.Xr chmod 2 , | .Xr chmod 2 , | ||||
.Xr chown 2 , | .Xr chown 2 , | ||||
.Xr fhstat 2 , | .Xr fhstat 2 , | ||||
.Xr statfs 2 , | .Xr statfs 2 , | ||||
.Xr utimes 2 , | .Xr utimes 2 , | ||||
Show All 34 Lines |