NAME

       selinux_status_open,     selinux_status_close,     selinux_status_updated,     selinux_status_getenforce,
       selinux_status_policyload and selinux_status_deny_unknown - reference the SELinux kernel  status  without
       invocation of system calls

SYNOPSIS

       #include <selinux/avc.h>

       int selinux_status_open(int fallback);

       void selinux_status_close(void);

       int selinux_status_updated(void);

       int selinux_status_getenforce(void);

       int selinux_status_policyload(void);

       int selinux_status_deny_unknown(void);

DESCRIPTION

       Linux   2.6.37   or   later   provides   a   SELinux   kernel   status   page;  being  mostly  placed  on
       /sys/fs/selinux/status entry. It enables userspace applications to mmap this page  with  read-only  mode,
       then it informs some status without system call invocations.

       In  some  cases  that  a userspace application tries to apply heavy frequent access control; such as row-
       level security in databases, it will face unignorable cost to communicate  with  kernel  space  to  check
       invalidation of userspace avc.

       These  functions provides applications a way to know some kernel events without system-call invocation or
       worker thread for monitoring.

       selinux_status_open() tries to open(2) /sys/fs/selinux/status and mmap(2) it in read-only mode. The file-
       descriptor and pointer to the page shall be stored internally; Don't touch them directly.  Set 1  on  the
       fallback  argument  to  handle a case of older kernels without kernel status page support.  In this case,
       this function tries to open a  netlink  socket  using  avc_netlink_open(3)  and  overwrite  corresponding
       callbacks  (  setenforce  and  policyload).  Thus, we need to pay attention to the interaction with these
       interfaces, when fallback mode is enabled.

       selinux_status_close() unmap the kernel status page and close its file descriptor, or close  the  netlink
       socket if fallbacked.

       selinux_status_updated() informs us whether something has been updated since the last call.  It returns 0
       if nothing was happened, however, 1 if something has been updated in this duration, or -1 on error.

       selinux_status_getenforce()  returns  0 if SELinux is running in permissive mode, 1 if enforcing mode, or
       -1 on error.  Same as security_getenforce(3) except with or without system call invocation.

       selinux_status_policyload() returns times of policy reloaded on the running system, or -1 on error.  Note
       that it is not a reliable value on fallback-mode until it receive the first  event  message  via  netlink
       socket.  Thus, don't use this value to know actual times of policy reloaded.

       selinux_status_deny_unknown()  returns  0 if SELinux treats policy queries on undefined object classes or
       permissions as being allowed, 1 if such queries are denied, or -1 on error.

       Also note that these interfaces are not thread-safe, so you have to protect them  from  concurrent  calls
       using exclusive locks when multiple threads are performing.

RETURN VALUE

       selinux_status_open()  returns  0  or  1  on  success.  1 means we are ready to use these interfaces, but
       netlink socket was opened as fallback instead of the kernel status page.  On error, -1 shall be returned.

       Any other functions with a return value shall return its characteristic value as described above,  or  -1
       on errors.

SEE ALSO

       mmap(2), avc_netlink_open(3), security_getenforce(3), security_deny_unknown(3)

kaigai@ak.jp.nec.com                             22 January 2011                          selinux_status_open(3)