← Back to branch summary

~apparmor-dev/apparmor/master

« back to all changes in this revision

Viewing changes to libraries/libapparmor/doc/aa_policy_cache.pod

  • Committer: Steve Beattie
  • Date: 2019-02-19 09:38:13 UTC
  • Revision ID: sbeattie@ubuntu.com-20190219093813-ud526ee6hwn8nljz
The AppArmor project has been converted to git and is now hosted on
gitlab.

To get the converted repository, please do
  git clone https://gitlab.com/apparmor/apparmor

Show diffs side-by-side

added added

removed removed

Lines of Context:
libraries/libapparmor/doc/aa_policy_cache.pod
1
 
# This publication is intellectual property of Canonical Ltd. Its contents
2
 
# can be duplicated, either in part or in whole, provided that a copyright
3
 
# label is visibly located on each copy.
4
 
#
5
 
# All information found in this book has been compiled with utmost
6
 
# attention to detail. However, this does not guarantee complete accuracy.
7
 
# Neither Canonical Ltd, the authors, nor the translators shall be held
8
 
# liable for possible errors or the consequences thereof.
9
 
#
10
 
# Many of the software and hardware descriptions cited in this book
11
 
# are registered trademarks. All trade names are subject to copyright
12
 
# restrictions and may be registered trade marks. Canonical Ltd.
13
 
# essentially adhere to the manufacturer's spelling.
14
 
#
15
 
# Names of products and trademarks appearing in this book (with or without
16
 
# specific notation) are likewise subject to trademark and trade protection
17
 
# laws and may thus fall under copyright restrictions.
18
 
#
19
 
 
20
 
 
21
 
=pod
22
 
 
23
 
=head1 NAME
24
 
 
25
 
aa_policy_cache - an opaque object representing an AppArmor policy cache
26
 
 
27
 
aa_policy_cache_new - create a new aa_policy_cache object from a path
28
 
 
29
 
aa_policy_cache_ref - increments the ref count of an aa_policy_cache object
30
 
 
31
 
aa_policy_cache_unref - decrements the ref count and frees the aa_policy_cache object when 0
32
 
 
33
 
aa_policy_cache_remove - removes all policy cache files under a path
34
 
 
35
 
aa_policy_cache_replace_all - performs a kernel policy replacement of all cached policies
36
 
 
37
 
=head1 SYNOPSIS
38
 
 
39
 
B<#include E<lt>sys/apparmor.hE<gt>>
40
 
 
41
 
B<typedef struct aa_policy_cache aa_policy_cache;>
42
 
 
43
 
B<int aa_policy_cache_new(aa_policy_cache **policy_cache, aa_features *kernel_features, int dirfd, const char *path, uint16_t max_caches);>
44
 
 
45
 
B<aa_policy_cache *aa_policy_cache_ref(aa_policy_cache *policy_cache);>
46
 
 
47
 
B<void aa_policy_cache_unref(aa_policy_cache *policy_cache);>
48
 
 
49
 
B<int aa_policy_cache_remove(int dirfd, const char *path);>
50
 
 
51
 
B<int aa_policy_cache_replace_all(aa_policy_cache *policy_cache, aa_kernel_interface *kernel_interface);>
52
 
 
53
 
Link with B<-lapparmor> when compiling.
54
 
 
55
 
=head1 DESCRIPTION
56
 
 
57
 
The I<aa_policy_cache> object contains information about a set of AppArmor
58
 
policy cache files. The policy cache files are the binary representation of a
59
 
human-readable AppArmor profile. The binary representation is the form that is
60
 
loaded into the kernel.
61
 
 
62
 
The aa_policy_cache_new() function creates an I<aa_policy_cache> object based
63
 
upon a directory file descriptor and path. The I<path> must point to a
64
 
directory. See the openat(2) man page for examples of I<dirfd> and I<path>. If
65
 
I<kernel_features> is NULL, then the features of the current kernel are used.
66
 
When specifying a valid I<kernel_features> object, it must be the compatible
67
 
with the features of the kernel of interest. The value of I<max_caches> should
68
 
be equal to the number of caches that should be allowed before old caches are
69
 
automatically reaped. The definition of what is considered to be an old cache
70
 
is private to libapparmor. Specifying 0 means that no new caches should be
71
 
created and only existing, valid caches may be used. Specifying UINT16_MAX
72
 
means that a new cache may be created and that the reaping of old caches is
73
 
disabled. The allocated I<aa_policy_cache> object must be freed using
74
 
aa_policy_cache_unref().
75
 
 
76
 
aa_policy_cache_ref() increments the reference count on the I<policy_cache>
77
 
object.
78
 
 
79
 
aa_policy_cache_unref() decrements the reference count on the I<policy_cache>
80
 
object and releases all corresponding resources when the reference count
81
 
reaches zero.
82
 
 
83
 
The aa_policy_cache_remove() function deletes all of the policy cache files
84
 
based upon a directory file descriptor and path. The I<path> must point to a 
85
 
directory. See the openat(2) man page for examples of I<dirfd> and I<path>.
86
 
 
87
 
The aa_policy_cache_replace_all() function can be used to perform a policy
88
 
replacement of all of the cache policies in the cache directory represented by
89
 
the I<policy_cache> object. If I<kernel_interface> is NULL, then the current
90
 
kernel interface is used. When specifying a valid I<kernel_interface> object,
91
 
it must be the interface of the currently running kernel.
92
 
 
93
 
=head1 RETURN VALUE
94
 
 
95
 
The aa_policy_cache_new() function returns 0 on success and I<*policy_cache>
96
 
will point to an I<aa_policy_cache> object that must be freed by
97
 
aa_policy_cache_unref(). -1 is returned on error, with errno set appropriately,
98
 
and I<*policy_cache> will be set to NULL.
99
 
 
100
 
aa_policy_cache_ref() returns the value of I<policy_cache>.
101
 
 
102
 
aa_policy_cache_remove() and aa_policy_cache_replace_all() return 0 on success.
103
 
-1 is returned on error, with errno set appropriately.
104
 
 
105
 
=head1 ERRORS
106
 
 
107
 
The errno value will be set according to the underlying error in the
108
 
I<aa_policy_cache> family of functions that return -1 on error.
109
 
 
110
 
=head1 NOTES
111
 
 
112
 
All aa_policy_cache functions described above are present in libapparmor
113
 
version 2.10 and newer.
114
 
 
115
 
=head1 BUGS
116
 
 
117
 
None known. If you find any, please report them at
118
 
L<https://bugs.launchpad.net/apparmor/+filebug>.
119
 
 
120
 
=head1 SEE ALSO
121
 
 
122
 
aa_features(3), aa_kernel_interface(3), openat(2) and
123
 
L<http://wiki.apparmor.net>.
124
 
 
125
 
=cut