Differential D17714 Diff 50274 head/lib/libc/sys/stat.2

Changeset 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