doc: improve the manpages for seccomp_rule_add() and seccomp_load()

Add some text to clarify that you can only have one comparison per
syscall argument in a given rule as well as better explain what
happens when you have multiple filters loaded.

Reviewed-by: Tom Hromatka <tom.hromatka@oracle.com>
Signed-off-by: Paul Moore <paul@paul-moore.com>

2 files changed, 30 insertions, 0 deletions

diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3
index e86bac4..fb40660 100644
--- a/doc/man/man3/seccomp_load.3
+++ b/doc/man/man3/seccomp_load.3
@@ -23,6 +23,16 @@ Loads the seccomp filter provided by
 .I ctx
 into the kernel; if the function
 succeeds the new seccomp filter will be active when the function returns.
+.P
+As it is possible to have multiple stacked seccomp filters for a given task
+(defined as either a process or a thread), it is important to remember that
+each of the filters loaded for a given task are executed when a syscall is
+made and the "strictest" rule is the rule that is applied.  In the case of
+seccomp, "strictest" is defined as the action with the lowest value (e.g.
+.I SCMP_ACT_KILL
+is "stricter" than
+.I SCMP_ACT_ALLOW
+).
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3
index e86f41b..0b9bcff 100644
--- a/doc/man/man3/seccomp_rule_add.3
+++ b/doc/man/man3/seccomp_rule_add.3
@@ -87,6 +87,17 @@ do guarantee the same behavior regardless of the architecture.
 The newly added filter rule does not take effect until the entire filter is
 loaded into the kernel using
 .BR seccomp_load (3).
+When adding rules to a filter, it is important to consider the impact of
+previously loaded filters; see the
+.BR seccomp_load (3)
+documentation for more information.
+.P
+All of the filter rules supplied by the calling application are combined into
+a union, with additional logic to eliminate redundant syscall filters.  For
+example, if a rule is added which allows a given syscall with a specific set of
+argument values and later a rule is added which allows the same syscall
+regardless the argument values then the first, more specific rule, is
+effectively dropped from the filter by the second more generic rule.
 .P
 The
 .BR SCMP_CMP (),
@@ -120,6 +131,15 @@ macros and use the variants which are explicitly 32 or 64-bit.  This should
 help eliminate problems caused by an unwanted sign extension of negative datum
 values.
 .P
+If syscall argument comparisons are included in the filter rule, all of the
+comparisons must be true for the rule to match.
+.P
+When adding syscall argument comparisons to the filter it is important to
+remember that while it is possible to have multiple comparisons in a single
+rule, you can only compare each argument once in a single rule.  In other words,
+you can not have multiple comparisons of the 3rd syscall argument in a single
+rule.
+.P
 While it is possible to specify the
 .I syscall
 value directly using the standard