| .TH "selinux_status_open" "3" "22 January 2011" "kaigai@ak.jp.nec.com" "SELinux API documentation" |
| .SH "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 |
| . |
| .SH "SYNOPSIS" |
| .B #include <selinux/avc.h> |
| .sp |
| .BI "int selinux_status_open(int " fallback ");" |
| .sp |
| .BI "void selinux_status_close(void);" |
| .sp |
| .BI "int selinux_status_updated(void);" |
| .sp |
| .BI "int selinux_status_getenforce(void);" |
| .sp |
| .BI "int selinux_status_policyload(void);" |
| .sp |
| .BI "int selinux_status_deny_unknown(void);" |
| . |
| .SH "DESCRIPTION" |
| Linux 2.6.37 or later provides a SELinux kernel status page; being mostly |
| placed on |
| .I /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. |
| .sp |
| 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. |
| .sp |
| These functions provides applications a way to know some kernel events |
| without system-call invocation or worker thread for monitoring. |
| .sp |
| .BR selinux_status_open () |
| tries to |
| .BR open (2) |
| .I /sys/fs/selinux/status |
| and |
| .BR 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 |
| .I 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 |
| .BR 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. |
| .sp |
| .BR selinux_status_close () |
| unmap the kernel status page and close its file descriptor, or close the |
| netlink socket if fallbacked. |
| .sp |
| .BR 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. |
| .sp |
| .BR selinux_status_getenforce () |
| returns 0 if SELinux is running in permissive mode, 1 if enforcing mode, |
| or \-1 on error. |
| Same as |
| .BR security_getenforce (3) |
| except with or without system call invocation. |
| .sp |
| .BR 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. |
| .sp |
| .BR 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. |
| .sp |
| 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. |
| . |
| .SH "RETURN VALUE" |
| .BR 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. |
| .sp |
| Any other functions with a return value shall return its characteristic |
| value as described above, or \-1 on errors. |
| . |
| .SH "SEE ALSO" |
| .ad l |
| .nh |
| .BR mmap (2), |
| .BR avc_netlink_open (3), |
| .BR security_getenforce (3), |
| .BR security_deny_unknown (3) |
