.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "aa_policy_cache 3" .TH aa_policy_cache 3 2024-10-14 "AppArmor 4.0.3" AppArmor .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME aa_policy_cache \- an opaque object representing an AppArmor policy cache .PP aa_policy_cache_new \- create a new aa_policy_cache object from a path .PP aa_policy_cache_ref \- increments the ref count of an aa_policy_cache object .PP aa_policy_cache_unref \- decrements the ref count and frees the aa_policy_cache object when 0 .PP aa_policy_cache_remove \- removes all policy cache files under a path .PP aa_policy_cache_replace_all \- performs a kernel policy replacement of all cached policies .PP aa_policy_cache_dir_path \- returns the path to the aa_policy_cache directory .PP aa_policy_cache_dir_path_preview \- returns a preview of the path to the aa_policy_cache directory without an existing aa_policy_cache object .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fB#include \fR .PP \&\fBtypedef struct aa_policy_cache aa_policy_cache;\fR .PP \&\fBint aa_policy_cache_new(aa_policy_cache **policy_cache, aa_features *kernel_features, int dirfd, const char *path, uint16_t max_caches);\fR .PP \&\fBint aa_policy_cache_add_ro_dir(aa_policy_cache *policy_cache, int dirfd, const char *path);\fR .PP \&\fBaa_policy_cache *aa_policy_cache_ref(aa_policy_cache *policy_cache);\fR .PP \&\fBvoid aa_policy_cache_unref(aa_policy_cache *policy_cache);\fR .PP \&\fBint aa_policy_cache_remove(int dirfd, const char *path);\fR .PP \&\fBint aa_policy_cache_replace_all(aa_policy_cache *policy_cache, aa_kernel_interface *kernel_interface);\fR .PP \&\fBchar *aa_policy_cache_dir_path(aa_policy_cache *policy_cache, int level);\fR .PP \&\fBchar *aa_policy_cache_dir_path_preview(aa_features *kernel_features, int dirfd, const char *path);\fR .PP Link with \fB\-lapparmor\fR when compiling. .SH DESCRIPTION .IX Header "DESCRIPTION" The \fIaa_policy_cache\fR object contains information about a set of AppArmor policy cache files. The policy cache files are the binary representation of a human-readable AppArmor profile. The binary representation is the form that is loaded into the kernel. .PP The \fBaa_policy_cache_new()\fR function creates an \fIaa_policy_cache\fR object based upon a directory file descriptor and path. See the \&\fBopenat\fR\|(2) man page for examples of \fIdirfd\fR and \fIpath\fR. The \fIpath\fR must point to a directory and it will be used as the basis for the location of policy cache files. See \fIaa_policy_cache_dir_path\fR to find out which directory will be used to store the binary policy cache files. If additional overlay cache directories are used (see \&\fIaa_policy_cache_add_ro_dir\fR) the directory specified in \&\fIaa_policy_cache_new\fR is the first directory searched and is the writable overlay. If \fIkernel_features\fR is NULL, then the features of the current kernel are used. When specifying a valid \&\fIkernel_features\fR object, it must be compatible with the features of the kernel of interest. The value of \fImax_caches\fR should be equal to the number of caches that should be allowed before old caches are automatically reaped. The definition of what is considered to be an old cache is private to libapparmor. Specifying 0 means that no new caches should be created and only existing, valid caches may be used. Specifying UINT16_MAX means that a new cache may be created and that the reaping of old caches is disabled. The allocated \&\fIaa_policy_cache\fR object must be freed using \fBaa_policy_cache_unref()\fR. .PP The \fBaa_policy_cache_add_ro_dir()\fR function adds an existing cache directory to the policy cache, as a readonly layer under the primary directory the cache was created with. When the cache is searched for an existing cache file the primary directory will be searched and then the readonly directories in the order that they were added to the policy cache. This allows the policy cache to be seeded with precompiled policy that can be updated by overlaying the read only cache file with one written to the primary cache dir. .PP \&\fBaa_policy_cache_ref()\fR increments the reference count on the \fIpolicy_cache\fR object. .PP \&\fBaa_policy_cache_unref()\fR decrements the reference count on the \fIpolicy_cache\fR object and releases all corresponding resources when the reference count reaches zero. .PP The \fBaa_policy_cache_remove()\fR function deletes all of the policy cache files based upon a directory file descriptor and path. The \fIpath\fR must point to a directory. See the \fBopenat\fR\|(2) man page for examples of \fIdirfd\fR and \fIpath\fR. .PP The \fBaa_policy_cache_replace_all()\fR function can be used to perform a policy replacement of all of the cache policies in the cache directory represented by the \fIpolicy_cache\fR object. If \fIkernel_interface\fR is NULL, then the current kernel interface is used. When specifying a valid \fIkernel_interface\fR object, it must be the interface of the currently running kernel. .PP The \fBaa_policy_cache_dir_path()\fR function provides the path to the cache directory for a \fIpolicy_cache\fR object at \fIlevel\fR in the policy cache overlay of cache directories. A \fIlevel\fR of 0 will always be present and is the first directory to search in an overlay of cache directories, and will also be the writable cache directory layer. Binary policy cache files will be located in the directory returned by this function. .PP The \fBaa_policy_cache_dir_levels()\fR function provides access to the number of directories that are being overlaid to create the policy cache. .SH "RETURN VALUE" .IX Header "RETURN VALUE" The \fBaa_policy_cache_new()\fR function returns 0 on success and \fI*policy_cache\fR will point to an \fIaa_policy_cache\fR object that must be freed by \&\fBaa_policy_cache_unref()\fR. \-1 is returned on error, with errno set appropriately, and \fI*policy_cache\fR will be set to NULL. .PP \&\fBaa_policy_cache_ref()\fR returns the value of \fIpolicy_cache\fR. .PP \&\fBaa_policy_cache_remove()\fR and \fBaa_policy_cache_replace_all()\fR return 0 on success. \&\-1 is returned on error, with errno set appropriately. .PP \&\fBaa_policy_cache_dir_path()\fR returns a path string which must be freed by the caller. NULL is returned on error, with errno set appropriately. .PP \&\fBaa_policy_cache_dir_levels()\fR returns a number indicating the number of directory levels there are associated with the \fIpolicy_cache\fR. .PP \&\fBaa_policy_cache_dir_path_preview()\fR is the same as \&\fBaa_policy_cache_dir_path()\fR except that it doesn't require an existing \&\fIaa_policy_cache\fR object. This is useful if the calling program cannot create an \fIaa_policy_cache\fR object due to lack of privileges needed to create the cache directory. .SH ERRORS .IX Header "ERRORS" The errno value will be set according to the underlying error in the \&\fIaa_policy_cache\fR family of functions that return \-1 or NULL on error. .SH NOTES .IX Header "NOTES" All aa_policy_cache functions described above, except for the \&\fBaa_policy_cache_dir_path()\fR function was added in libapparmor version 2.13. All the other aa_policy_cache functions described above are present in libapparmor version 2.10. .PP \&\fBaa_policy_cache_unref()\fR saves the value of errno when called and restores errno before exiting in libapparmor version 2.12 and newer. .SH BUGS .IX Header "BUGS" None known. If you find any, please report them at . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBaa_features\fR\|(3), \fBaa_kernel_interface\fR\|(3), \fBopenat\fR\|(2) and .