selinux_status_open(3)					     SELinux API documentation					    selinux_status_open(3)

NAME

       selinux_status_open,  selinux_status_close,  selinux_status_updated,  selinux_status_getenforce, selinux_status_policyload and selinux_sta-
       tus_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 /selinux/status entry. It  enables  userspace  applica-
       tions 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) /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  secu-
       rity_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)