diff --git a/policy/modules/kernel/files.if b/policy/modules/kernel/files.if
index 7fa8309..cf82911 100644
--- a/policy/modules/kernel/files.if
+++ b/policy/modules/kernel/files.if
@@ -58,6 +58,14 @@
## <li>logging_log_file()</li>
## <li>userdom_user_home_content()</li>
## </ul>
+## <p>
+## Example:
+## </p>
+## <p>
+## type myfile_t;
+## files_type(myfile_t)
+## allow mydomain_t myfile_t:file read_file_perms;
+## </p>
## </desc>
## <param name="type">
## <summary>
@@ -160,11 +168,39 @@ interface(`files_security_mountpoint',`
## Make the specified type usable for
## runtime process ID files.
## </summary>
+## <desc>
+## <p>
+## Make the specified type usable for runtime process ID files,
+## typically found in /var/run.
+## This will also make the type usable for files, making
+## calls to files_type() redundant. Failure to use this interface
+## for a PID file type may result in problems with starting
+## or stopping services.
+## </p>
+## <p>
+## Related interfaces:
+## </p>
+## <ul>
+## <li>files_pid_filetrans()</li>
+## </ul>
+## <p>
+## Example usage with a domain that can create and
+## write its PID file with a private PID file type in the
+## /var/run directory:
+## </p>
+## <p>
+## type mypidfile_t;
+## files_pid_file(mypidfile_t)
+## allow mydomain_t mypidfile_t:file { create_file_perms write_file_perms };
+## files_pid_filetrans(mydomain_t, mypidfile_t, file)
+## </p>
+## </desc>
## <param name="type">
## <summary>
## Type to be used for PID files.
## </summary>
## </param>
+## <infoflow type="none"/>
#
interface(`files_pid_file',`
gen_require(`
@@ -180,11 +216,31 @@ interface(`files_pid_file',`
## Make the specified type a
## configuration file.
## </summary>
+## <desc>
+## <p>
+## Make the specified type usable for configuration files.
+## This will also make the type usable for files, making
+## calls to files_type() redundant. Failure to use this interface
+## for a temporary file may result in problems with
+## configuration management tools.
+## </p>
+## <p>
+## Example usage with a domain that can read
+## its configuration file /etc:
+## </p>
+## <p>
+## type myconffile_t;
+## files_config_file(myconffile_t)
+## allow mydomain_t myconffile_t:file read_file_perms;
+## files_search_etc(mydomain_t)
+## </p>
+## </desc>
## <param name="file_type">
## <summary>
## Type to be used as a configuration file.
## </summary>
## </param>
+## <infoflow type="none"/>
#
interface(`files_config_file',`
gen_require(`
@@ -288,12 +344,39 @@ interface(`files_poly_member_tmp',`
## Make the specified type a file
## used for temporary files.
## </summary>
+## <desc>
+## <p>
+## Make the specified type usable for temporary files.
+## This will also make the type usable for files, making
+## calls to files_type() redundant. Failure to use this interface
+## for a temporary file may result in problems with
+## purging temporary files.
+## </p>
+## <p>
+## Related interfaces:
+## </p>
+## <ul>
+## <li>files_tmp_filetrans()</li>
+## </ul>
+## <p>
+## Example usage with a domain that can create and
+## write its temporary file in the system temporary file
+## directories (/tmp or /var/tmp):
+## </p>
+## <p>
+## type mytmpfile_t;
+## files_tmp_file(mytmpfile_t)
+## allow mydomain_t mytmpfile_t:file { create_file_perms write_file_perms };
+## files_tmp_filetrans(mydomain_t, mytmpfile_t, file)
+## </p>
+## </desc>
## <param name="file_type">
## <summary>
## Type of the file to be used as a
## temporary file.
## </summary>
## </param>
+## <infoflow type="none"/>
#
interface(`files_tmp_file',`
gen_require(`
@@ -2178,7 +2261,7 @@ interface(`files_manage_etc_dirs',`
## <li>auth_read_shadow()</li>
## <li>files_read_etc_runtime_files()</li>
## <li>seutil_read_config()</li>
-## </ul>
+## </ul>
## </desc>
## <param name="domain">
## <summary>
@@ -2410,11 +2493,29 @@ interface(`files_create_boot_flag',`
## Read files in /etc that are dynamically
## created on boot, such as mtab.
## </summary>
+## <desc>
+## <p>
+## Allow the specified domain to read dynamically created
+## configuration files in /etc. These files are typically
+## general system configuration files that do
+## not have more specific SELinux types. Some
+## examples of these files are:
+## </p>
+## <ul>
+## <li>/etc/motd</li>
+## <li>/etc/mtab</li>
+## <li>/etc/nologin</li>
+## </ul>
+## <p>
+## This interface does not include access to /etc/shadow.
+## </p>
+## </desc>
## <param name="domain">
## <summary>
## Domain allowed access.
## </summary>
## </param>
+## <infoflow type="read" weight="10" />
## <rolecap/>
#
interface(`files_read_etc_runtime_files',`
@@ -3930,11 +4031,29 @@ interface(`files_getattr_usr_files',`
## <summary>
## Read generic files in /usr.
## </summary>
+## <desc>
+## <p>
+## Allow the specified domain to read generic
+## files in /usr. These files are various program
+## files that do not have more specific SELinux types.
+## Some examples of these files are:
+## </p>
+## <ul>
+## <li>/usr/include/*</li>
+## <li>/usr/share/doc/*</li>
+## <li>/usr/share/info/*</li>
+## </ul>
+## <p>
+## Generally, it is safe for many domains to have
+## this access.
+## </p>
+## </desc>
## <param name="domain">
## <summary>
## Domain allowed access.
## </summary>
## </param>
+## <infoflow type="read" weight="10"/>
#
interface(`files_read_usr_files',`
gen_require(`
@@ -4491,11 +4610,25 @@ interface(`files_getattr_var_lib_dirs',`
## <summary>
## Search the /var/lib directory.
## </summary>
+## <desc>
+## <p>
+## Search the /var/lib directory. This is
+## necessary to access files or directories under
+## /var/lib that have a private type. For example, a
+## domain accessing a private library file in the
+## /var/lib directory:
+## </p>
+## <p>
+## allow mydomain_t mylibfile_t:file read_file_perms;
+## files_search_var_lib(mydomain_t)
+## </p>
+## </desc>
## <param name="domain">
## <summary>
## Domain allowed access.
## </summary>
## </param>
+## <infoflow type="read" weight="5"/>
#
interface(`files_search_var_lib',`
gen_require(`
@@ -4938,9 +5071,34 @@ interface(`files_read_generic_pids',`
########################################
## <summary>
-## Create an object in the process ID directory, with a private
-## type using a type transition.
+## Create an object in the process ID directory, with a private type.
## </summary>
+## <desc>
+## <p>
+## Create an object in the process ID directory (e.g., /var/run)
+## with a private type. Typically this is used for creating
+## private PID files in /var/run with the private type instead
+## of the general PID file type. To accomplish this goal,
+## either the program must be SELinux-aware, or use this interface.
+## </p>
+## <p>
+## Related interfaces:
+## </p>
+## <ul>
+## <li>files_pid_file()</li>
+## </ul>
+## <p>
+## Example usage with a domain that can create and
+## write its PID file with a private PID file type in the
+## /var/run directory:
+## </p>
+## <p>
+## type mypidfile_t;
+## files_pid_file(mypidfile_t)
+## allow mydomain_t mypidfile_t:file { create_file_perms write_file_perms };
+## files_pid_filetrans(mydomain_t, mypidfile_t, file)
+## </p>
+## </desc>
## <param name="domain">
## <summary>
## Domain allowed access.
@@ -4956,6 +5114,7 @@ interface(`files_read_generic_pids',`
## The object class of the object being created.
## </summary>
## </param>
+## <infoflow type="write" weight="10"/>
#
interface(`files_pid_filetrans',`
gen_require(`