Page MenuHomeFreeBSD
Differential D17714 Diff 50274 head/lib/libc/sys/open.2

Changeset View

Standalone View

View Options

head/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 November 11, 2018
.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
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.
When
.Dv O_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.
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 hierarchy
starting at
.Fa fd .
Additionally, no symbolic link in Additionally, no symbolic link in
.Fa path .Fa path
may contain ".." components either. 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
.Dv vfs.lookup_cap_dotdot
.Xr sysctl 3
MIB is set to zero, ".." components in the paths,
used in capability mode, or with the
.Dv O_BENEATH
flag, are completely disabled.
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 All 9 Lines
O_FSYNC synchronous writes O_FSYNC synchronous writes
O_SYNC synchronous writes O_SYNC synchronous 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 path to be strictly relative to starting directory O_BENEATH require 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 114 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, does not reside in the directory hierarchy of
the starting directory, or is an absolute path. children beneath the topping directory.
Starting directory is the process current directory if relative Topping 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 at the topping directory,
after which all further resolved components must be under it.
.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 207 Lines • ▼ Show 20 Lines
.Fn open .Fn open
was called and the process is in capability mode. was called and the process is in capability mode.
.It Bq Er ENOTCAPABLE .It Bq Er ENOTCAPABLE
.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 or the and the process is in capability mode.
.It Bq Er ENOTCAPABLE
The
.Dv O_BENEATH .Dv O_BENEATH
flag was provided. 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.
.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 44 Lines • Show Last 20 Lines