Differential D17714 Diff 49747 lib/libc/sys/open.2

Changeset View

Standalone View

lib/libc/sys/open.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.
	.\"			.\"
	.\" @(#)open.2 8.2 (Berkeley) 11/16/93			.\" @(#)open.2 8.2 (Berkeley) 11/16/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd October 20, 2018			.Dd October 20, 2018
				0mpUnsubmitted Not Done Inline Actions Remember to bump the date. 0mp: Remember to bump the date.
	.Dt OPEN 2			.Dt OPEN 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm open , openat			.Nm open , openat
	.Nd open or create a file for reading, writing or executing			.Nd open or create a file for reading, writing or executing
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	Show All 30 Lines
	.Xr umask 2 ) .			.Xr umask 2 ) .
	.Pp			.Pp
	The			The
	.Fn openat			.Fn openat
	function is equivalent to the			function is equivalent to the
	.Fn open			.Fn open
	function except in the case where the			function except in the case where the
	.Fa path			.Fa path
	specifies a relative path.			specifies a relative path, or the
	In this case the file to be opened is determined relative to the directory			.Dv O_BENEATH
				flag is provided.
				For
				.Fn openat
				and relative
				.Fa path ,
				the file to be opened is determined relative to the directory
				emasteUnsubmitted Not Done Inline Actions I think we could use a more extensive rewrite of this in light of `O_BENEATH` but don't have a good suggestion at the moment. We can always iterate on it in HEAD. emaste: I think we could use a more extensive rewrite of this in light of `O_BENEATH` but don't have a…
	associated with the file descriptor			associated with the file descriptor
	.Fa fd			.Fa fd
	instead of the current working directory.			instead of the current working directory.
	The			The
	.Fa flag			.Fa flag
	parameter and the optional fourth parameter correspond exactly to			parameter and the optional fourth parameter correspond exactly to
	the parameters of			the parameters of
	.Fn open .			.Fn open .
	If			If
	.Fn openat			.Fn openat
	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			parameter, the current working directory is used
	and the behavior is identical to a call to			and the behavior is identical to a call to
	.Fn open .			.Fn open .
	.Pp			.Pp
				When
				.Fn openat
				is called with an absolute
				.Fa path
				without the
				.Dv O_BENEATH
				flag, it ignores the
				.Fa fd
				argument.
				jillesUnsubmitted Done Inline Actions Perhaps this is better as When .Fn openat is called with an absolute .Fa path without the .Dv O_BENEATH flag, it ignores the .Fa fd argument jilles: Perhaps this is better as ``` When .Fn openat is called with an absolute .Fa path without the .
				When
				.Dv O_BENEATH
				is specified with an absolute
				jillesUnsubmitted Done Inline Actions is specified with an absolute jilles: is specified with an absolute
				.Fa path ,
				a directory passed by the
				.Fa fd
				argument is used as the starting point for the resolution.
				See the definition of the
				.Dv O_BENEATH
				flag below.
				.Pp
	In			In
	.Xr capsicum 4			.Xr capsicum 4
	capability mode,			capability mode,
	.Fn open			.Fn open
	is not permitted.			is not permitted.
	The			The
	.Fa path			.Fa path
	argument to			argument to
	.Fn openat			.Fn openat
	must be strictly relative to a file descriptor			must be strictly relative to a file descriptor
	.Fa fd ,			.Fa fd ,
	as defined in			as defined in
	.Pa sys/kern/vfs_lookup.c .			.Pa sys/kern/vfs_lookup.c .
	.Fa path			.Fa path
	must not be an absolute path and must not contain ".." components.			must not be an absolute path and must not contain ".." components
				which cause the path resolution to escape the directory hierarhy
				jillesUnsubmitted Done Inline Actions which cause the path resolution to escape the directory hierarchy? jilles: which cause the path resolution to escape the directory hierarchy?
				0mpUnsubmitted Done Inline Actions Typo: hierarhy. 0mp: Typo: //hierarhy//.
				starting at
				.Fa fd .
	Additionally, no symbolic link in			Additionally, no symbolic link in
	.Fa path			.Fa path
	may contain ".." components either.			may contain escaping ".." components.
				kibAuthorUnsubmitted Done Inline Actions escaping, will fix with the next patch upload. kib: escaping, will fix with the next patch upload.
	.Fa fd			.Fa fd
	must not be			must not be
	.Dv AT_FDCWD .			.Dv AT_FDCWD .
	.Pp			.Pp
				If the
				jillesUnsubmitted Done Inline Actions If the jilles: If the
				.Dv vfs.lookup_cap_dotdot
				.Xr sysctl 2
				0mpUnsubmitted Not Done Inline Actions I think 2 is a typo here: sysctl(2) does not exist. 0mp: I think //2// is a typo here: sysctl(2) does not exist.
				kibAuthorUnsubmitted Done Inline Actions sysctl is actually sysctl(2), in the sense that it is a syscall, not just some library function. I think it is put into section 3 because other functions are put into the same man page. kib: sysctl is actually sysctl(2), in the sense that it is a syscall, not just some library function.
				MIB is set to zero, ".." components in the paths,
				used in capability mode, or with the
				jillesUnsubmitted Done Inline Actions in capability mode jilles: in capability mode
				.Dv O_BENEATH
				flag, are completely disabled.
				jillesUnsubmitted Done Inline Actions are completely disabled jilles: are completely disabled
				If the
				jillesUnsubmitted Done Inline Actions If the jilles: If the
				.Dv vfs.lookup_cap_dotdot_nonlocal
				MIB is set to zero, ".." is not allowed if found on non-local filesystem.
				.Pp
	The flags specified are formed by			The flags specified are formed by
	.Em or Ns 'ing			.Em or Ns 'ing
	the following values			the following values
	.Pp			.Pp
	.Bd -literal -offset indent -compact			.Bd -literal -offset indent -compact
	O_RDONLY open for reading only			O_RDONLY open for reading only
	O_WRONLY open for writing only			O_WRONLY open for writing only
	O_RDWR open for reading and writing			O_RDWR open for reading and writing
	▲ Show 20 Lines • Show All 140 Lines • ▼ Show 20 Lines
	.Dq verified			.Dq verified
	means is implementation specific.			means is implementation specific.
	The run-time linker (rtld) uses this flag to ensure shared objects have			The run-time linker (rtld) uses this flag to ensure shared objects have
	been verified before operating on them.			been verified before operating on them.
	.Pp			.Pp
	.Dv O_BENEATH			.Dv O_BENEATH
	returns			returns
	.Er ENOTCAPABLE			.Er ENOTCAPABLE
	if the specified path, after resolving all symlinks and ".." references			if the specified relative path, after resolving all symlinks and ".."
	in it, does not reside in the directory hierarchy of children beneath			references in it, does not reside in the directory hierarchy of
	the starting directory, or is an absolute path.			children beneath the starting directory.
	Starting directory is the process current directory if relative			Starting directory is the process current directory if relative
	.Fa path			.Fa path
	is used for			is used for
	.Fn open ,			.Fn open ,
	and the directory referenced by the			and the directory referenced by the
	.Fa fd			.Fa fd
	argument when specifying relative			argument when using
	.Fa path
	for
	.Fn openat .			.Fn openat .
				If the specified path is absolute,
				.Dv O_BENEATH
				allows arbitrary prefix that ends up in the starting directory,
				after which all further resolved components must be under it.
				jillesUnsubmitted Done Inline Actions Note that this means that the sentence "The openat() function is equivalent to the open() function except in the case where the path specifies a relative path." is no longer true if `O_BENEATH` is specified. So the change to the man pages will need to be more extensive, describing that `.Fa fd` is always used when `O_BENEATH` is given. jilles: Note that this means that the sentence "The openat() function is equivalent to the open()…
	.Pp			.Pp
	If successful,			If successful,
	.Fn open			.Fn open
	returns a non-negative integer, termed a file descriptor.			returns a non-negative integer, termed a file descriptor.
	It returns \-1 on failure.			It returns \-1 on failure.
	The file pointer used to mark the current position within the			The file pointer used to mark the current position within the
	file is set to the beginning of the file.			file is set to the beginning of the file.
	.Pp			.Pp
	▲ Show 20 Lines • Show All 270 Lines • Show Last 20 Lines