unveil parts of a restricted filesystem view
unveil(const char *path, const char *permissions); The first call to
unveilremoves 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
unveilcan expose additional paths with specified permissions in the filesystem. The
unveilcall itself is treated specially and can continue to see the filesystem for subsequent calls. Future calls to
unveilcan 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:
- Make path available for read operations, corresponding to the pledge(2) promise rpath.
- Make path available for write operations, corresponding to the pledge(2) promise wpath.
- Make path available for execute operations, corresponding to the pledge(2) promise exec.
- Allow path to be created and removed, corresponding to the pledge(2) promise cpath.
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-directories 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
unveilwill result in an error of EACCES when the permissions argument does not match the attempted operation. ENOENT is returned for paths for which no
unveilpermissions 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.
unveil() returns 0 on success or -1 on failure.
- The addition of path would exceed the per-process limit for unveiled paths.
- A directory in path did not exist.
- An invalid value of permissions was used.
- An attempt to increase permissions was made, or the path was not accessible, or
unveilwas called after locking.
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.