The Wayback Machine - https://web.archive.org/web/20181020011612/https://man.openbsd.org/unveil
unveil
—
unveil parts of a restricted filesystem view
#include <unistd.h>
intunveil
(
const char *path,
const char *permissions);
The first call to
unveil
removes visibility of the entire filesystem from all other filesystem-related system calls (such as
open(2),
chmod(2) and
rename(2)), except for the specified
path and
permission. Subsequent calls to
unveil
can expose additional paths with specified permissions in the filesystem.
The
unveil
call itself is treated specially and can continue to see the filesystem for subsequent calls.
Future calls to
unveil
can be blocked by passing two
NULL arguments. If the veil is not yet active, this does not activate it. Alternatively,
pledge(2) may be used to remove the
unveil promise.
The
permissions argument points to a string consisting of the following characters:
r
- Makepath available for read operations, corresponding to thepledge(2) promiserpath.
w
- Makepath available for write operations, corresponding to thepledge(2) promisewpath.
x
- Makepath available for execute operations, corresponding to thepledge(2) promiseexec.
c
- Allowpath to be created and removed, corresponding to thepledge(2) promisecpath.
A
path that is a directory will enable all filesystem access underneath
path using
permissions if and only if no more specific matching
unveil
() exists at a lower level. Directories are remembered at the time of a call to
unveil
(). This means that a directory that is removed and recreated after a call to
unveil
() will appear to not exist.
Non-directory paths are remembered by name within their containing directory, and so may be created, removed, or re-created after a call to
unveil
() and still appear to exist.
Attempts to access paths not allowed by
unveil
will result in an error of
EACCES when the
permissions argument does not match the attempted operation.
ENOENT is returned for paths for which no
unveil
permissions qualify.
As with
pledge(2), the use of
unveil
() in an application will require lots of study and understanding of the interfaces called. In most cases it is best practice to unveil the directories in which an application makes use of files.
Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable
errno is set to indicate the error.
-
-
- E2BIG
- The addition ofpath would exceed the per-process limit for unveiled paths.
-
-
- ENOENT
- A directory inpath did not exist.
-
-
- EINVAL
- An invalid value ofpermissions was used.
-
-
- EPERM
- An attempt to increase permissions was made, or thepath was not accessible, or
unveil
was called after locking.
The
unveil
() system call first appeared in
OpenBSD 6.4.
Filesystem lookups work today when they cross an
unveil
() during
namei(9) lookup in the kernel. A program that does relative operations below a higher
unveil
() may currently not see the parts of the filesystem underneath the high level unveil. This is actively being worked on.