doc: update the API to reflect the new filter context parameter

Signed-off-by: Paul Moore <pmoore@redhat.com>

7 files changed, 121 insertions, 70 deletions

diff --git a/doc/man/man3/seccomp_attr_set.3 b/doc/man/man3/seccomp_attr_set.3
index 3cbd513..d024227 100644
--- a/doc/man/man3/seccomp_attr_set.3
+++ b/doc/man/man3/seccomp_attr_set.3
@@ -1,4 +1,4 @@
-.TH "seccomp_attr_set" 3 "16 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_attr_set" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,10 +9,13 @@ seccomp_attr_set, seccomp_attr_get \- Manage the seccomp filter attributes
 .nf
 .B #include <seccomp.h>
 .sp
+.B typedef void * scmp_filter_ctx;
 .B enum scmp_filter_attr;
 .sp
-.BI "int seccomp_attr_set(enum scmp_filter_attr " attr ", uint32_t " value ");"
-.BI "int seccomp_attr_get(enum scmp_filter_attr " attr ", uint32_t *" value ");"
+.BI "int seccomp_attr_set(scmp_filter_ctx " ctx ","
+.BI "                     enum scmp_filter_attr " attr ", uint32_t " value ");"
+.BI "int seccomp_attr_get(scmp_filter_ctx " ctx ","
+.BI "                     enum scmp_filter_attr " attr ", uint32_t *" value ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
@@ -26,9 +29,14 @@ function fetches the filter attributes.  The seccomp filter attributes are
 tunable values that affect how the library behaves when generating and loading
 the seccomp filter into the kernel.  The attributes are reset to their default
 values whenever the filter is initialized or reset via
-.BR seccomp_filter_init ()
+.BR seccomp_filter_init (3)
 or
-.BR seccomp_filter_reset ().
+.BR seccomp_filter_reset (3).
+.P
+The filter context
+.I ctx
+is the value returned by the call to
+.BR seccomp_init (3).
 .P
 Valid
 .I attr
@@ -36,9 +44,9 @@ values are as follows:
 .TP
 .B SCMP_FLTATR_ACT_DEFAULT
 The default filter action as specified in the call to
-.BR seccomp_filter_init ()
+.BR seccomp_filter_init (3)
 or
-.BR seccomp_filter_reset ().
+.BR seccomp_filter_reset (3).
 This attribute is read-only.
 .TP
 .B SCMP_FLTATR_ACT_BADARCH
@@ -67,22 +75,23 @@ Returns zero on success, negative errno values on failure.
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 
-	rc = seccomp_init(SCMP_ACT_ALLOW);
-	if (rc < 0)
+	ctx = seccomp_init(SCMP_ACT_ALLOW);
+	if (ctx == NULL)
 		goto out;
 
 	/* ... */
 
-	rc = seccomp_attr_set(SCMP_FLTATR_ACT_BADARCH, SCMP_ACT_TRAP);
+	rc = seccomp_attr_set(ctx, SCMP_FLTATR_ACT_BADARCH, SCMP_ACT_TRAP);
 	if (rc < 0)
 		goto out;
 
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi
diff --git a/doc/man/man3/seccomp_export_bpf.3 b/doc/man/man3/seccomp_export_bpf.3
index 33b5344..926b638 100644
--- a/doc/man/man3/seccomp_export_bpf.3
+++ b/doc/man/man3/seccomp_export_bpf.3
@@ -1,4 +1,4 @@
-.TH "seccomp_export_bpf" 3 "15 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_export_bpf" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,8 +9,10 @@ seccomp_export_bpf, seccomp_export_pfc \- Export the seccomp filter
 .nf
 .B #include <seccomp.h>
 .sp
-.BI "int seccomp_export_bpf(int " fd ");"
-.BI "int seccomp_export_pfc(int " fd ");"
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "int seccomp_export_bpf(const scmp_filter_ctx " ctx ", int " fd ");"
+.BI "int seccomp_export_pfc(const scmp_filter_ctx " ctx ", int " fd ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
@@ -30,6 +32,11 @@ using libseccomp.  Both functions write the filter to the
 .I fd
 file descriptor.
 .P
+The filter context
+.I ctx
+is the value returned by the call to
+.BR seccomp_init (3).
+.P
 While the two output formats are guaranteed to be functionally equivalent for
 the given seccomp filter configuration, the filter instructions, and their
 ordering, are not guaranteed to be the same in both the BPF and PFC formats.
@@ -45,11 +52,12 @@ Returns zero on success, negative errno values on failure.
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 	int filter_fd;
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
 		goto out;
 
 	/* ... */
@@ -60,7 +68,7 @@ int main(int argc, char *argv[])
 		goto out;
 	}
 
-	rc = seccomp_export_bpf(filter_fd);
+	rc = seccomp_export_bpf(ctx, filter_fd);
 	if (rc < 0) {
 		close(filter_fd);
 		goto out;
@@ -70,7 +78,7 @@ int main(int argc, char *argv[])
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi
diff --git a/doc/man/man3/seccomp_init.3 b/doc/man/man3/seccomp_init.3
index 69a6800..067c042 100644
--- a/doc/man/man3/seccomp_init.3
+++ b/doc/man/man3/seccomp_init.3
@@ -1,4 +1,4 @@
-.TH "seccomp_init" 3 "5 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_init" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,8 +9,10 @@ seccomp_init, seccomp_reset \- Initialize the seccomp filter state
 .nf
 .B #include <seccomp.h>
 .sp
-.BI "int seccomp_init(uint32_t " def_action ");"
-.BI "int seccomp_reset(uint32_t " def_action ");"
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "scmp_filter_ctx seccomp_init(uint32_t " def_action ");"
+.BI "int seccomp_reset(scmp_filter_ctx " ctx ", uint32_t " def_action ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
@@ -20,24 +22,24 @@ The
 .BR seccomp_init ()
 and
 .BR seccomp_reset ()
-functions initialize the internal seccomp filter state, prepares it for use, and
-sets the default action based on the
+functions (re)initialize the internal seccomp filter state, prepares it for
+use, and sets the default action based on the
 .I def_action
 parameter.  The
 .BR seccomp_init ()
 function must be called before any other libseccomp functions as the rest
-of the library API will fail if the filter state is not initialized properly.
+of the library API will fail if the filter context is not initialized properly.
 The
 .BR seccomp_reset ()
-function releases the existing filter state before reinitializing it and can
-only be called after a call to
+function releases the existing filter context state before reinitializing it
+and can only be called after a call to
 .BR seccomp_init ()
 has succeeded.
 .P
 When the caller is finished configuring the seccomp filter and has loaded it
 into the kernel, the caller should call
 .BR seccomp_release (3)
-to release all of the internal filter state.
+to release all of the filter context state.
 .P
 Valid
 .I def_action
@@ -76,7 +78,11 @@ does not match any of the configured seccomp filter rules.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
-Returns zero on success, negative errno values on failure.
+The
+.BR seccomp_init ()
+function returns a filter context on success, NULL on failure.  The
+.BR seccomp_reset ()
+function returns zero on success, negative errno values on failure.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH EXAMPLES
 .\" //////////////////////////////////////////////////////////////////////////
@@ -85,22 +91,23 @@ Returns zero on success, negative errno values on failure.
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
 		goto out;
 
 	/* ... */
 
-	rc = seccomp_reset(SCMP_ACT_KILL);
+	rc = seccomp_reset(ctx, SCMP_ACT_KILL);
 	if (rc < 0)
 		goto out;
 
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi
diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3
index 8a88ba3..78944a2 100644
--- a/doc/man/man3/seccomp_load.3
+++ b/doc/man/man3/seccomp_load.3
@@ -1,4 +1,4 @@
-.TH "seccomp_load" 3 "5 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_load" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,13 +9,17 @@ seccomp_load \- Load the current seccomp filter into the kernel
 .nf
 .B #include <seccomp.h>
 .sp
-.BI "int seccomp_load(void);"
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "int seccomp_load(scmp_filter_ctx " ctx ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
 .\" //////////////////////////////////////////////////////////////////////////
 .P
-Loads the currently configured seccomp filter into the kernel; if the function
+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.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
@@ -29,22 +33,23 @@ Returns zero on success, negative errno values on failure.
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
-		return -rc;
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
+		goto out;
 
 	/* ... */
 
-	rc = seccomp_load();
+	rc = seccomp_load(ctx);
 	if (rc < 0)
 		goto out;
 
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi
diff --git a/doc/man/man3/seccomp_release.3 b/doc/man/man3/seccomp_release.3
index 749770d..08a0a0b 100644
--- a/doc/man/man3/seccomp_release.3
+++ b/doc/man/man3/seccomp_release.3
@@ -1,4 +1,4 @@
-.TH "seccomp_release" 3 "5 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_release" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,17 +9,21 @@ seccomp_release \- Release the seccomp filter state
 .nf
 .B #include <seccomp.h>
 .sp
-.BI "void seccomp_release(void);"
+.B typedef void * scmp_filter_ctx;
+.sp
+.BI "void seccomp_release(scmp_filter_ctx " ctx ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
 .\" //////////////////////////////////////////////////////////////////////////
 .P
-Releases the internal seccomp filter state initialized by
+Releases the seccomp filter in
+.I ctx
+which was first initialized by
 .BR seccomp_init (3)
 or
 .BR seccomp_reset (3)
-and frees any memory associated with the currently configured seccomp filter.
+and frees any memory associated with the given seccomp filter context.
 Any seccomp filters loaded into the kernel are not affected.
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
@@ -34,14 +38,15 @@ Does not return a value.
 int main(int argc, char *argv[])
 {
 	int rc;
+	scmp_filter_ctx ctx;
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
-		return -rc;
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
+		return -1;
 
 	/* ... */
 
-	seccomp_release();
+	seccomp_release(ctx);
 	return 0;
 }
 .fi
diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3
index 7de90b3..77c64a0 100644
--- a/doc/man/man3/seccomp_rule_add.3
+++ b/doc/man/man3/seccomp_rule_add.3
@@ -1,4 +1,4 @@
-.TH "seccomp_rule_add" 3 "5 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_rule_add" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,6 +9,8 @@ seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule
 .nf
 .B #include <seccomp.h>
 .sp
+.B typedef void * scmp_filter_ctx;
+.sp
 .BI "int SCMP_SYS(" syscall_name ");"
 .sp
 .BI "struct scmp_arg_cmp SCMP_CMP(unsigned int " arg ","
@@ -20,9 +22,9 @@ seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule
 .BI "struct scmp_arg_cmp SCMP_A4(enum scmp_compare " op ", " ... ");"
 .BI "struct scmp_arg_cmp SCMP_A5(enum scmp_compare " op ", " ... ");"
 .sp
-.BI "int seccomp_rule_add(uint32_t " action ","
+.BI "int seccomp_rule_add(scmp_filter_ctx " ctx ", uint32_t " action ","
 .BI "                     int " syscall ", unsigned int " arg_cnt ", " ... ");"
-.BI "int seccomp_rule_add_exact(uint32_t " action ","
+.BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action ","
 .BI "                           int " syscall ", unsigned int " arg_cnt ", " ... ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
@@ -73,6 +75,11 @@ is highly recommended to use the
 .BR SCMP_SYS ()
 macro instead.  See the EXAMPLES section below.
 .P
+The filter context
+.I ctx
+is the value returned by the call to
+.BR seccomp_init (3).
+.P
 Valid
 .I action
 values are as follows:
@@ -200,12 +207,13 @@ functions return zero on success, negative errno values on failure.
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 	int fd;
 	unsigned char buf[BUF_SIZE];
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
 		goto out;
 
 	/* ... */
@@ -214,30 +222,30 @@ int main(int argc, char *argv[])
 
 	/* ... */
 
-	rc = seccomp_rule_add(SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
+	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
 	if (rc < 0)
 		goto out;
 
-	rc = seccomp_rule_add(SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
+	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
 			      SCMP_A0(SCMP_CMP_EQ, fd),
 			      SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
 			      SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
 	if (rc < 0)
 		goto out;
 
-	rc = seccomp_rule_add(SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
+	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
 			      SCMP_CMP(0, SCMP_CMP_EQ, fd));
 	if (rc < 0)
 		goto out;
 
-	rc = seccomp_load();
+	rc = seccomp_load(ctx);
 	if (rc < 0)
 		goto out;
 
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi
diff --git a/doc/man/man3/seccomp_syscall_priority.3 b/doc/man/man3/seccomp_syscall_priority.3
index 4337484..eb86069 100644
--- a/doc/man/man3/seccomp_syscall_priority.3
+++ b/doc/man/man3/seccomp_syscall_priority.3
@@ -1,4 +1,4 @@
-.TH "seccomp_syscall_priority" 3 "5 April 2012" "paul@paul-moore.com" "libseccomp Documentation"
+.TH "seccomp_syscall_priority" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
 .\" //////////////////////////////////////////////////////////////////////////
 .SH NAME
 .\" //////////////////////////////////////////////////////////////////////////
@@ -9,9 +9,12 @@ seccomp_syscall_priority \- Prioritize syscalls in the seccomp filter
 .nf
 .B #include <seccomp.h>
 .sp
+.B typedef void * scmp_filter_ctx;
+.sp
 .BI "int SCMP_SYS(" syscall_name ");"
 .sp
-.BI "int seccomp_syscall_priority(int " syscall ", uint8_t " priority ");"
+.BI "int seccomp_syscall_priority(scmp_filter_ctx " ctx ","
+.BI "                             int " syscall ", uint8_t " priority ");"
 .fi
 .\" //////////////////////////////////////////////////////////////////////////
 .SH DESCRIPTION
@@ -39,6 +42,11 @@ The
 .I priority
 parameter takes an 8-bit value ranging from 0 - 255; a higher value represents
 a higher priority.
+.P
+The filter context
+.I ctx
+is the value returned by the call to
+.BR seccomp_init ().
 .\" //////////////////////////////////////////////////////////////////////////
 .SH RETURN VALUE
 .\" //////////////////////////////////////////////////////////////////////////
@@ -58,22 +66,23 @@ value in
 
 int main(int argc, char *argv[])
 {
-	int rc;
+	int rc = -1;
+	scmp_filter_ctx ctx;
 
-	rc = seccomp_init(SCMP_ACT_KILL);
-	if (rc < 0)
+	ctx = seccomp_init(SCMP_ACT_KILL);
+	if (ctx == NULL)
 		goto out;
 
 	/* ... */
 
-	rc = seccomp_syscall_priority(SCMP_SYS(read), 200);
+	rc = seccomp_syscall_priority(ctx, SCMP_SYS(read), 200);
 	if (rc < 0)
 		goto out;
 
 	/* ... */
 
 out:
-	seccomp_release();
+	seccomp_release(ctx);
 	return -rc;
 }
 .fi