diff options
Diffstat (limited to 'doc/man/man3/seccomp_notify_alloc.3')
| -rw-r--r-- | doc/man/man3/seccomp_notify_alloc.3 | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/doc/man/man3/seccomp_notify_alloc.3 b/doc/man/man3/seccomp_notify_alloc.3 new file mode 100644 index 0000000..cb1c048 --- /dev/null +++ b/doc/man/man3/seccomp_notify_alloc.3 @@ -0,0 +1,114 @@ +.TH "seccomp_notify_alloc" 3 "30 May 2020" "tycho@tycho.ws" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive, +seccomp_notify_respond, seccomp_notify_id_valid, seccomp_notify_fd \- Manage seccomp notifications +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.BI "int seccomp_notify_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")" +.BI "void seccomp_notify_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notify_receive(int " fd ", struct seccomp_notif *" req ")" +.BI "int seccomp_notify_respond(int " fd ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notify_id_valid(int " fd ", uint64_t " id ")" +.BI "int seccomp_notify_fd(const scmp_filter_ctx " ctx ")" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_notify_alloc () +function dynamically allocates enough memory for a seccomp notification and +response. Note that one should always use these functions and not depend on the +structure sizes in headers, since the size can vary depending on the kernel +version. This function takes care to ask the kernel how big each structure +should be, and allocates the right amount of memory. The +.BR seccomp_notify_free () +function frees memory allocated by +.BR seccomp_notify_alloc (). +.P +The +.BR seccomp_notify_receive () +function receives a notification from a seccomp notify fd (obtained from +.BR seccomp_notify_fd ()). +.P +The +.BR seccomp_notify_respond () +function sends a response to a particular notification. The id field should be +the same as the id from the request, so that the kernel knows which request +this response corresponds to. +.P +The +.BR seccomp_notify_id_valid () +function checks to see if the syscall from a particular notification request is +still valid, i.e. if the task is still alive. See NOTES below for details on +race conditions. +.P +The +.BR seccomp_notify_fd () +returns the notification fd of a filter after it has been loaded. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_notify_fd () +returns the notification fd of the loaded filter, -1 if a notification fd has +not yet been created, and -EINVAL if the filter context is invalid. +.P +The +.BR seccomp_notify_id_valid () +returns 0 if the id is valid, and -ENOENT if it is not. +.P +The +.BR seccomp_notify_alloc (), +.BR seccomp_notify_receive (), +and +.BR seccomp_notify_respond () +functions return zero on success, or one of the following error codes on +failure: +.TP +.B -ECANCELED +There was a system failure beyond the control of the library, check the +\fIerrno\fP value for more information. +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.TP +.B -EOPNOTSUPP +The library doesn't support the particular operation. +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +Care should be taken to avoid two different time of check/time of use errors. +First, after opening any resources relevant to the pid for a notification (e.g. +/proc/pid/mem for reading tracee memory to make policy decisions), applications +should call +.BR seccomp_notify_id_valid () +to make sure that the resources the application has opened correspond to the +right pid, i.e. that the pid didn't die and a different task take its place. +.P +Second, the classic time of check/time of use issue with seccomp memory should +also be avoided: applications should copy any memory they wish to use to make +decisions from the tracee into its own address space before applying any policy +decisions, since a multi-threaded tracee may edit the memory at any time, +including after it's used to make a policy decision. +.P +A complete example of how to avoid these two races is available in the Linux +Kernel source tree at +.BR /samples/seccomp/user-trap.c. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Tycho Andersen <tycho@tycho.ws> +.\" ////////////////////////////////////////////////////////////////////////// |