NAME
unveil —
unveil parts of a restricted filesystem
view
SYNOPSIS
#include
<unistd.h>
int
unveil(const
char *path, const char
*permissions);
DESCRIPTION
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- Make path available for read operations, corresponding to the pledge(2) promise rpath.
w- Make path available for write operations, corresponding to the pledge(2) promise wpath.
x- Make path available for execute operations, corresponding to the pledge(2) promise exec.
c- Allow path to be created and removed, corresponding to the pledge(2) promise cpath.
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.
RETURN VALUES
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.
ERRORS
- E2BIG
- The addition of path would exceed the per-process limit for unveiled paths.
- ENOENT
- A directory in path did not exist.
- EINVAL
- An invalid value of permissions was used.
- EPERM
- An attempt to increase permissions was made, or the
path was not accessible, or
unveilwas called after locking.
HISTORY
The unveil() system call first appeared in
OpenBSD 6.4.
BUGS
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.