Changeset View
Changeset View
Standalone 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 September 23, 2020 | .Dd February 23, 2021 | ||||
.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, or the | specifies a relative path. | ||||
.Dv O_BENEATH | |||||
flag is provided. | |||||
For | For | ||||
.Fn openat | .Fn openat | ||||
and relative | and relative | ||||
.Fa path , | .Fa path , | ||||
the file to be opened is determined relative to the directory | the file to be opened is determined relative to the directory | ||||
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. | ||||
Show All 10 Lines | |||||
.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 | When | ||||
.Fn openat | .Fn openat | ||||
is called with an absolute | is called with an absolute | ||||
.Fa path | |||||
without the | |||||
.Dv O_BENEATH | |||||
flag, it ignores the | |||||
.Fa fd | |||||
argument. | |||||
When | |||||
.Dv O_BENEATH | |||||
is specified with an absolute | |||||
.Fa path , | .Fa path , | ||||
a directory passed by the | it ignores the | ||||
.Fa fd | .Fa fd | ||||
argument is used as the topping point for the resolution. | argument. | ||||
When | |||||
.Dv O_BENEATH | |||||
is specified with a relative path, the | |||||
.Fa fd | |||||
argument is used both as the starting point, and as the topping point | |||||
for the resolution. | |||||
See the definition of the | |||||
.Dv O_BENEATH | |||||
flag below. | |||||
.Pp | .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 | |||||
.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 hierarchy | which cause the path resolution to escape the directory hierarchy | ||||
starting at | starting at | ||||
.Fa fd . | .Fa fd . | ||||
Additionally, no symbolic link in | Additionally, no symbolic link in | ||||
.Fa path | .Fa path | ||||
may target absolute path or contain escaping ".." components. | may target absolute path or contain escaping ".." components. | ||||
.Fa fd | .Fa fd | ||||
must not be | must not be | ||||
.Dv AT_FDCWD . | .Dv AT_FDCWD . | ||||
.Pp | .Pp | ||||
If the | If the | ||||
.Dv vfs.lookup_cap_dotdot | .Dv vfs.lookup_cap_dotdot | ||||
.Xr sysctl 3 | .Xr sysctl 3 | ||||
MIB is set to zero, ".." components in the paths, | MIB is set to zero, ".." components in the paths, | ||||
used in capability mode, or with the | used in capability mode, | ||||
.Dv O_BENEATH | are completely disabled. | ||||
flag, are completely disabled. | |||||
If the | If the | ||||
.Dv vfs.lookup_cap_dotdot_nonlocal | .Dv vfs.lookup_cap_dotdot_nonlocal | ||||
MIB is set to zero, ".." is not allowed if found on non-local filesystem. | MIB is set to zero, ".." is not allowed if found on non-local filesystem. | ||||
.Pp | .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 | ||||
Show All 15 Lines | |||||
O_SYNC synchronous writes | O_SYNC synchronous writes | ||||
O_DSYNC synchronous data writes | O_DSYNC synchronous data writes | ||||
O_NOFOLLOW do not follow symlinks | O_NOFOLLOW do not follow symlinks | ||||
O_NOCTTY ignored | O_NOCTTY ignored | ||||
O_TTY_INIT ignored | O_TTY_INIT ignored | ||||
O_DIRECTORY error if file is not a directory | O_DIRECTORY error if file is not a directory | ||||
O_CLOEXEC set FD_CLOEXEC upon open | O_CLOEXEC set FD_CLOEXEC upon open | ||||
O_VERIFY verify the contents of the file | O_VERIFY verify the contents of the file | ||||
O_BENEATH require resolved path to be strictly relative to topping directory | O_RESOLVE_BENEATH path resolution must not cross the fd directory | ||||
markj: Is "starting directory" the right term? Resolution starts at the CWD. This might be better… | |||||
O_RESOLVE_BENEATH require walked path to be strictly relative to topping directory | |||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
Opening a file with | Opening a file with | ||||
.Dv O_APPEND | .Dv O_APPEND | ||||
set causes each write on the file | set causes each write on the file | ||||
to be appended to the end. | to be appended to the end. | ||||
If | If | ||||
.Dv O_TRUNC | .Dv O_TRUNC | ||||
▲ Show 20 Lines • Show All 111 Lines • ▼ Show 20 Lines | |||||
may be used to indicate to the kernel that the contents of the file should | may be used to indicate to the kernel that the contents of the file should | ||||
be verified before allowing the open to proceed. | be verified before allowing the open to proceed. | ||||
The details of what | The details of what | ||||
.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 | |||||
returns | |||||
.Er ENOTCAPABLE | |||||
if the specified path, after resolving all symlinks and ".." | |||||
references, does not end up with tail residing in the directory hierarchy of | |||||
children beneath the topping directory. | |||||
Topping directory is the process current directory if relative | |||||
Done Inline ActionsThis removes the definition of "topping directory", but it is still referenced in other places. markj: This removes the definition of "topping directory", but it is still referenced in other places. | |||||
.Fa path | |||||
is used for | |||||
.Fn open , | |||||
and the directory referenced by the | |||||
.Fa fd | |||||
argument when using | |||||
.Fn openat . | |||||
.Dv O_BENEATH | |||||
allows arbitrary prefix that ends up at the topping directory, | |||||
after which all further resolved components must be under it. | |||||
.Pp | |||||
.Dv O_RESOLVE_BENEATH | .Dv O_RESOLVE_BENEATH | ||||
returns | returns | ||||
.Er ENOTCAPABLE | .Er ENOTCAPABLE | ||||
if any intermediate component of the specified relative path does not | if any intermediate component of the specified relative path does not | ||||
reside in the directory hierarchy beneath the topping directory. | reside in the directory hierarchy beneath the starting directory. | ||||
Comparing to | Absolute paths or even the temporal escape from beneath of the starting | ||||
.Dv O_BENEATH , | |||||
absolute paths or even the temporal escape from beneath of the topping | |||||
directory is not allowed. | directory is not allowed. | ||||
.Pp | .Pp | ||||
When | When | ||||
.Fa fd | .Fa fd | ||||
is opened with | is opened with | ||||
.Dv O_SEARCH , | .Dv O_SEARCH , | ||||
execute permissions are checked at open time. | execute permissions are checked at open time. | ||||
The | The | ||||
▲ Show 20 Lines • Show All 240 Lines • ▼ Show 20 Lines | |||||
.Fa path | .Fa path | ||||
is an absolute path, | is an absolute path, | ||||
or contained a ".." component leading to a | or contained a ".." component leading to a | ||||
directory outside of the directory hierarchy specified by | directory outside of the directory hierarchy specified by | ||||
.Fa fd , | .Fa fd , | ||||
and the process is in capability mode. | and the process is in capability mode. | ||||
.It Bq Er ENOTCAPABLE | .It Bq Er ENOTCAPABLE | ||||
The | The | ||||
.Dv O_BENEATH | |||||
flag was provided, and the absolute | |||||
.Fa path | |||||
does not have its tail fully contained under the topping directory, | |||||
or the relative | |||||
.Fa path | |||||
escapes it. | |||||
.It Bq Er ENOTCAPABLE | |||||
The | |||||
.Dv O_RESOLVE_BENEATH | .Dv O_RESOLVE_BENEATH | ||||
flag was provided, and the relative | flag was provided, and the relative | ||||
.Fa path | .Fa path | ||||
escapes topping directory. | escapes the | ||||
.Ar fd | |||||
directory. | |||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr chmod 2 , | .Xr chmod 2 , | ||||
.Xr close 2 , | .Xr close 2 , | ||||
.Xr dup 2 , | .Xr dup 2 , | ||||
.Xr fexecve 2 , | .Xr fexecve 2 , | ||||
.Xr fhopen 2 , | .Xr fhopen 2 , | ||||
.Xr getdtablesize 2 , | .Xr getdtablesize 2 , | ||||
▲ Show 20 Lines • Show All 51 Lines • Show Last 20 Lines |
Is "starting directory" the right term? Resolution starts at the CWD. This might be better phrased as, "path resolution is required to not cross the directory specified by .Ar fd".