Differential D18359 Diff 51220 lib/libc/sys/getfh.2

Changeset View

Standalone View

lib/libc/sys/getfh.2

Context not available.
	.\" @(#)getfh.2 8.1 (Berkeley) 6/9/93	.\" @(#)getfh.2 8.1 (Berkeley) 6/9/93
	.\" $FreeBSD$	.\" $FreeBSD$
	.\"	.\"
	.Dd April 14, 2011	.Dd November 26, 2018
	.Dt GETFH 2	.Dt GETFH 2
	.Os	.Os
	.Sh NAME	.Sh NAME
	.Nm getfh ,	.Nm getfh ,
	.Nm lgetfh	.Nm lgetfh ,
		.Nm getfhat
	.Nd get file handle	.Nd get file handle
	.Sh LIBRARY	.Sh LIBRARY
	.Lb libc	.Lb libc
Context not available.
	.Fn getfh "const char path" "fhandle_t fhp"	.Fn getfh "const char path" "fhandle_t fhp"
	.Ft int	.Ft int
	.Fn lgetfh "const char path" "fhandle_t fhp"	.Fn lgetfh "const char path" "fhandle_t fhp"
		.Ft int
		.Fn getfhat "int fd" "const char path" "fhandle_t fhp" "int flag"
	.Sh DESCRIPTION	.Sh DESCRIPTION
	The	The
	.Fn getfh	.Fn getfh
Context not available.
	returns a file handle for the specified file or directory	returns a file handle for the specified file or directory
	in the file handle pointed to by	in the file handle pointed to by
	.Fa fhp .	.Fa fhp .
		.Pp
	The	The
	.Fn lgetfh	.Fn lgetfh
	system call is like	system call is like
Context not available.
	while	while
	.Fn getfh	.Fn getfh
	returns information about the file the link references.	returns information about the file the link references.
		.Pp
		The
		.Fn getfhat
		system call is equivalent to
		.Fn getfh
		and
		.Fn lgetfh
		except when the
		.Fa path
		specifies a relative path, or the
		.Dv AT_BENEATH
		flag is provided.
		For
		.Fn getfhat
		and relative
		.Fa path ,
		the status is retrieved from a file relative to
		the directory associated with the file descriptor
		.Fa fd
		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
		The values for the
		.Fa flag
		are constructed by a bitwise-inclusive OR of flags from this list,
		defined in
		.In fcntl.h :
		.Bl -tag -width indent
		.It Dv AT_SYMLINK_NOFOLLOW
		If
		.Fa path
		names a symbolic link, the status of the symbolic link is returned.
		.It Dv AT_BENEATH
		Only stat files and directories below the topping directory.
		See the description of the
		.Dv O_BENEATH
		flag in the
		.Xr open 2
		manual page.
		.El
		.Pp
		If
		.Fn getfhat
		is passed the special value
		.Dv AT_FDCWD
		in the
		.Fa fd
		parameter, the current working directory is used and the behavior is
		identical to a call to
		.Fn getfth
		or
		.Fn lgetfh
		respectively, depending on whether or not the
		.Dv AT_SYMLINK_NOFOLLOW
		bit is set in
		.Fa flag .
		.Pp
		When
		.Fn getfhat
		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.
	These system calls are restricted to the superuser.	These system calls are restricted to the superuser.
	.Sh RETURN VALUES	.Sh RETURN VALUES
		markjUnsubmitted Done Inline Actions This looks incomplete. markj: This looks incomplete.
	.Rv -std	.Rv -std
Context not available.
	.Tn I/O	.Tn I/O
	error occurred while reading from or writing to the file system.	error occurred while reading from or writing to the file system.
	.El	.El
		.Pp
		brooksUnsubmitted Done Inline Actions I'd use "points to an invalid address." here. brooks: I'd use "points to an invalid address." here.
		In addition to the errors returned by
		.Fn getfh ,
		and
		.Fn lgetfh ,
		the
		.Fn getfhat
		system call may fail if:
		.Bl -tag -width Er
		markjUnsubmitted Done Inline Actions Missing a period. markj: Missing a period.
		.It Bq Er EBADF
		The
		.Fa path
		argument does not specify an absolute path and the
		.Fa fd
		argument, is neither
		.Dv AT_FDCWD
		nor a valid file descriptor open for searching.
		.It Bq Er EINVAL
		The value of the
		.Fa flag
		argument is not valid.
		.It Bq Er ENOTDIR
		The
		.Fa path
		argument is not an absolute path and
		.Fa fd
		is neither
		.Dv AT_FDCWD
		nor a file descriptor associated with a directory.
	.Sh SEE ALSO	.Sh SEE ALSO
	.Xr fhopen 2 ,	.Xr fhopen 2 ,
	.Xr open 2 ,	.Xr open 2 ,
Context not available.