mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-06 17:31:01 +01:00
2da4200cc0
Create a section 3 man page for the aa_policy_cache family of functions. Additionally, update the in-code descriptions to match the descriptions in the man page. Signed-off-by: Tyler Hicks <tyhicks@canonical.com> Acked-by: John Johansen <john.johansen@canonical.com>
125 lines
4.9 KiB
Text
125 lines
4.9 KiB
Text
# This publication is intellectual property of Canonical Ltd. Its contents
|
|
# can be duplicated, either in part or in whole, provided that a copyright
|
|
# label is visibly located on each copy.
|
|
#
|
|
# All information found in this book has been compiled with utmost
|
|
# attention to detail. However, this does not guarantee complete accuracy.
|
|
# Neither Canonical Ltd, the authors, nor the translators shall be held
|
|
# liable for possible errors or the consequences thereof.
|
|
#
|
|
# Many of the software and hardware descriptions cited in this book
|
|
# are registered trademarks. All trade names are subject to copyright
|
|
# restrictions and may be registered trade marks. Canonical Ltd.
|
|
# essentially adhere to the manufacturer's spelling.
|
|
#
|
|
# Names of products and trademarks appearing in this book (with or without
|
|
# specific notation) are likewise subject to trademark and trade protection
|
|
# laws and may thus fall under copyright restrictions.
|
|
#
|
|
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
aa_policy_cache - an opaque object representing an AppArmor policy cache
|
|
|
|
aa_policy_cache_new - create a new aa_policy_cache object from a path
|
|
|
|
aa_policy_cache_ref - increments the ref count of an aa_policy_cache object
|
|
|
|
aa_policy_cache_unref - decrements the ref count and frees the aa_policy_cache object when 0
|
|
|
|
aa_policy_cache_remove - removes all policy cache files under a path
|
|
|
|
aa_policy_cache_replace_all - performs a kernel policy replacement of all cached policies
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<#include E<lt>sys/apparmor.hE<gt>>
|
|
|
|
B<typedef struct aa_policy_cache aa_policy_cache;>
|
|
|
|
B<int aa_policy_cache_new(aa_policy_cache **policy_cache, aa_features *kernel_features, int dirfd, const char *path, uint16_t max_caches);>
|
|
|
|
B<aa_policy_cache *aa_policy_cache_ref(aa_policy_cache *policy_cache);>
|
|
|
|
B<void aa_policy_cache_unref(aa_policy_cache *policy_cache);>
|
|
|
|
B<int aa_policy_cache_remove(int dirfd, const char *path);>
|
|
|
|
B<int aa_policy_cache_replace_all(aa_policy_cache *policy_cache, aa_kernel_interface *kernel_interface);>
|
|
|
|
Link with B<-lapparmor> when compiling.
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The I<aa_policy_cache> 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.
|
|
|
|
The aa_policy_cache_new() function creates an I<aa_policy_cache> object based
|
|
upon a directory file descriptor and path. The I<path> must point to a
|
|
directory. See the openat(2) man page for examples of I<dirfd> and I<path>. If
|
|
I<kernel_features> is NULL, then the features of the current kernel are used.
|
|
When specifying a valid I<kernel_features> object, it must be the compatible
|
|
with the features of the kernel of interest. The value of I<max_caches> 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 I<aa_policy_cache> object must be freed using
|
|
aa_policy_cache_unref().
|
|
|
|
aa_policy_cache_ref() increments the reference count on the I<policy_cache>
|
|
object.
|
|
|
|
aa_policy_cache_unref() decrements the reference count on the I<policy_cache>
|
|
object and releases all corresponding resources when the reference count
|
|
reaches zero.
|
|
|
|
The aa_policy_cache_remove() function deletes all of the policy cache files
|
|
based upon a directory file descriptor and path. The I<path> must point to a
|
|
directory. See the openat(2) man page for examples of I<dirfd> and I<path>.
|
|
|
|
The aa_policy_cache_replace_all() function can be used to perform a policy
|
|
replacement of all of the cache policies in the cache directory represented by
|
|
the I<policy_cache> object. If I<kernel_interface> is NULL, then the current
|
|
kernel interface is used. When specifying a valid I<kernel_interface> object,
|
|
it must be the interface of the currently running kernel.
|
|
|
|
=head1 RETURN VALUE
|
|
|
|
The aa_policy_cache_new() function returns 0 on success and I<*policy_cache>
|
|
will point to an I<aa_policy_cache> object that must be freed by
|
|
aa_policy_cache_unref(). -1 is returned on error, with errno set appropriately,
|
|
and I<*policy_cache> will be set to NULL.
|
|
|
|
aa_policy_cache_ref() returns the value of I<policy_cache>.
|
|
|
|
aa_policy_cache_remove() and aa_policy_cache_replace_all() return 0 on success.
|
|
-1 is returned on error, with errno set appropriately.
|
|
|
|
=head1 ERRORS
|
|
|
|
The errno value will be set according to the underlying error in the
|
|
I<aa_policy_cache> family of functions that return -1 on error.
|
|
|
|
=head1 NOTES
|
|
|
|
All aa_policy_cache functions described above are present in libapparmor
|
|
version 2.10 and newer.
|
|
|
|
=head1 BUGS
|
|
|
|
None known. If you find any, please report them at
|
|
L<https://bugs.launchpad.net/apparmor/+filebug>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
aa_features(3), aa_kernel_interface(3), openat(2) and
|
|
L<http://wiki.apparmor.net>.
|
|
|
|
=cut
|