UNVEIL(2)                     System Calls Manual                    UNVEIL(2)

NNAAMMEE
     uunnvveeiill - unveil parts of a restricted filesystem view

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<uunniissttdd..hh>>

     _i_n_t
     uunnvveeiill(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_o_n_s_t _c_h_a_r _*_p_e_r_m_i_s_s_i_o_n_s);

DDEESSCCRRIIPPTTIIOONN
     The first call to uunnvveeiill() that specifies a _p_a_t_h 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 _p_a_t_h
     and _p_e_r_m_i_s_s_i_o_n_s.

     The uunnvveeiill() system call remains capable of traversing to any _p_a_t_h in the
     filesystem, so additional calls can set permissions at other points in
     the filesystem hierarchy.

     After establishing a collection of _p_a_t_h and _p_e_r_m_i_s_s_i_o_n_s rules, future
     calls to uunnvveeiill() can be disabled by passing two NULL arguments.
     Alternatively, pledge(2) may be used to remove the "unveil" promise.

     The _p_e_r_m_i_s_s_i_o_n_s argument points to a string consisting of zero or more of
     the following characters:

           rr     Make _p_a_t_h available for read operations, corresponding to the
                 pledge(2) promise "rpath".
           ww     Make _p_a_t_h available for write operations, corresponding to
                 the pledge(2) promise "wpath".
           xx     Make _p_a_t_h available for execute operations, corresponding to
                 the pledge(2) promise "exec".
           cc     Allow _p_a_t_h to be created and removed, corresponding to the
                 pledge(2) promise "cpath".

     A _p_a_t_h that is a directory will enable all filesystem access underneath
     _p_a_t_h using _p_e_r_m_i_s_s_i_o_n_s if and only if no more specific matching uunnvveeiill()
     exists at a lower level.  Directories are remembered at the time of a
     call to uunnvveeiill().  This means that a directory that is removed and
     recreated after a call to uunnvveeiill() 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
     uunnvveeiill() and still appear to exist.

     Attempts to access paths not allowed by uunnvveeiill() will result in an error
     of EACCES when the _p_e_r_m_i_s_s_i_o_n_s argument does not match the attempted
     operation.  ENOENT is returned for paths for which no uunnvveeiill()
     permissions qualify.  After a process has terminated, lastcomm(1) will
     mark it with the `U' flag if file access was prevented by uunnvveeiill().

     uunnvveeiill() use can be tricky because programs misbehave badly when their
     files unexpectedly disappear.  In many cases it is easier to unveil the
     directories in which an application makes use of files.

RREETTUURRNN VVAALLUUEESS
     Upon successful completion, the value 0 is returned; otherwise the
     value -1 is returned and the global variable _e_r_r_n_o is set to indicate the
     error.

EERRRROORRSS
     [E2BIG]            The addition of _p_a_t_h would exceed the per-process
                        limit for unveiled paths.

     [EFAULT]           _p_a_t_h or _p_e_r_m_i_s_s_i_o_n_s points outside the process's
                        allocated address space.

     [ENOENT]           A directory in _p_a_t_h did not exist.

     [EINVAL]           An invalid value of _p_e_r_m_i_s_s_i_o_n_s was used.

     [EPERM]            An attempt to increase permissions was made, or the
                        _p_a_t_h was not accessible, or uunnvveeiill() was called after
                        locking.

HHIISSTTOORRYY
     The uunnvveeiill() system call first appeared in OpenBSD 6.4.

OpenBSD 7.6                    September 6, 2021                   OpenBSD 7.6