system: add function comment headers for the notify functions

This really should have been done when the notification code was
merged.  Looking at the code, the seccomp.h.in comments can apply
here so we're just going to do a cut-n-paste job.

We also fixup some formatting/consistency issues in the seccomp.h.in
comments.

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

2 files changed, 44 insertions, 5 deletions

diff --git a/include/seccomp.h.in b/include/seccomp.h.in
index ce48a1e..17c90b7 100644
--- a/include/seccomp.h.in
+++ b/include/seccomp.h.in
@@ -723,7 +723,7 @@ int seccomp_rule_add_exact_array(scmp_filter_ctx ctx,
 				 const struct scmp_arg_cmp *arg_array);
 
 /**
- * Allocate a pair of notification request/response structures.
+ * Allocate a pair of notification request/response structures
  * @param req the request location
  * @param resp the response location
  *
@@ -744,7 +744,7 @@ void seccomp_notify_free(struct seccomp_notif *req,
 			 struct seccomp_notif_resp *resp);
 
 /**
- * Receive a notification from a seccomp notification fd.
+ * Receive a notification from a seccomp notification fd
  * @param fd the notification fd
  * @param req the request buffer to save into
  *
@@ -756,7 +756,7 @@ void seccomp_notify_free(struct seccomp_notif *req,
 int seccomp_notify_receive(int fd, struct seccomp_notif *req);
 
 /**
- * Send a notification response to a seccomp notification fd.
+ * Send a notification response to a seccomp notification fd
  * @param fd the notification fd
  * @param resp the response buffer to use
  *
@@ -768,7 +768,7 @@ int seccomp_notify_receive(int fd, struct seccomp_notif *req);
 int seccomp_notify_respond(int fd, struct seccomp_notif_resp *resp);
 
 /**
- * Check if a notification id is still valid.
+ * Check if a notification id is still valid
  * @param fd the notification fd
  * @param id the id to test
  *
@@ -779,7 +779,7 @@ int seccomp_notify_respond(int fd, struct seccomp_notif_resp *resp);
 int seccomp_notify_id_valid(int fd, uint64_t id);
 
 /**
- * Return the notification fd from a filter that has already been loaded.
+ * Return the notification fd from a filter that has already been loaded
  * @param ctx the filter context
  *
  * This returns the listener fd that was generated when the seccomp policy was
diff --git a/src/system.c b/src/system.c
index e2b2a9d..737558e 100644
--- a/src/system.c
+++ b/src/system.c
@@ -347,6 +347,16 @@ filter_load_out:
 	return rc;
 }
 
+/**
+ * Allocate a pair of notification request/response structures
+ * @param req the request location
+ * @param resp the response location
+ *
+ * This function allocates a pair of request/response structure by computing
+ * the correct sized based on the currently running kernel. It returns zero on
+ * success, and negative values on failure.
+ *
+ */
 int sys_notify_alloc(struct seccomp_notif **req,
 		     struct seccomp_notif_resp **resp)
 {
@@ -382,6 +392,16 @@ int sys_notify_alloc(struct seccomp_notif **req,
 	return 0;
 }
 
+/**
+ * Receive a notification from a seccomp notification fd
+ * @param fd the notification fd
+ * @param req the request buffer to save into
+ *
+ * Blocks waiting for a notification on this fd. This function is thread safe
+ * (synchronization is performed in the kernel). Returns zero on success,
+ * negative values on error.
+ *
+ */
 int sys_notify_receive(int fd, struct seccomp_notif *req)
 {
 	if (_support_seccomp_user_notif <= 0)
@@ -393,6 +413,16 @@ int sys_notify_receive(int fd, struct seccomp_notif *req)
 	return 0;
 }
 
+/**
+ * Send a notification response to a seccomp notification fd
+ * @param fd the notification fd
+ * @param resp the response buffer to use
+ *
+ * Sends a notification response on this fd. This function is thread safe
+ * (synchronization is performed in the kernel). Returns zero on success,
+ * negative values on error.
+ *
+ */
 int sys_notify_respond(int fd, struct seccomp_notif_resp *resp)
 {
 	if (_support_seccomp_user_notif <= 0)
@@ -403,6 +433,15 @@ int sys_notify_respond(int fd, struct seccomp_notif_resp *resp)
 	return 0;
 }
 
+/**
+ * Check if a notification id is still valid
+ * @param fd the notification fd
+ * @param id the id to test
+ *
+ * Checks to see if a notification id is still valid. Returns 0 on success, and
+ * negative values on failure.
+ *
+ */
 int sys_notify_id_valid(int fd, uint64_t id)
 {
 	if (_support_seccomp_user_notif <= 0)