libseccomp/doc/man/man3/seccomp_init.3

   1 .TH "seccomp_init" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
   2 .\" //////////////////////////////////////////////////////////////////////////
   3 .SH NAME
   4 .\" //////////////////////////////////////////////////////////////////////////
   5 seccomp_init, seccomp_reset \- Initialize the seccomp filter state
   6 .\" //////////////////////////////////////////////////////////////////////////
   7 .SH SYNOPSIS
   8 .\" //////////////////////////////////////////////////////////////////////////
   9 .nf
  10 .B #include <seccomp.h>
  11 .sp
  12 .B typedef void * scmp_filter_ctx;
  13 .sp
  14 .BI "scmp_filter_ctx seccomp_init(uint32_t " def_action ");"
  15 .BI "int seccomp_reset(scmp_filter_ctx " ctx ", uint32_t " def_action ");"
  16 .sp
  17 Link with \fI\-lseccomp\fP.
  18 .fi
  19 .\" //////////////////////////////////////////////////////////////////////////
  20 .SH DESCRIPTION
  21 .\" //////////////////////////////////////////////////////////////////////////
  22 .P
  23 The
  24 .BR seccomp_init ()
  25 and
  26 .BR seccomp_reset ()
  27 functions (re)initialize the internal seccomp filter state, prepares it for
  28 use, and sets the default action based on the
  29 .I def_action
  30 parameter.  The
  31 .BR seccomp_init ()
  32 function must be called before any other libseccomp functions as the rest
  33 of the library API will fail if the filter context is not initialized properly.
  34 The
  35 .BR seccomp_reset ()
  36 function releases the existing filter context state before reinitializing it
  37 and can only be called after a call to
  38 .BR seccomp_init ()
  39 has succeeded.
  40 .P
  41 When the caller is finished configuring the seccomp filter and has loaded it
  42 into the kernel, the caller should call
  43 .BR seccomp_release (3)
  44 to release all of the filter context state.
  45 .P
  46 Valid
  47 .I def_action
  48 values are as follows:
  49 .TP
  50 .B SCMP_ACT_KILL
  51 The thread will be terminated by the kernel with SIGSYS when it calls a syscall
  52 that does not match any of the configured seccomp filter rules.  The thread
  53 will not be able to catch the signal.
  54 .TP
  55 .B SCMP_ACT_TRAP
  56 The thread will be sent a SIGSYS signal when it calls a syscall that does not
  57 match any of the configured seccomp filter rules.  It may catch this and change
  58 its behavior accordingly.  When using SA_SIGINFO with
  59 .BR sigaction (2),
  60 si_code will be set to SYS_SECCOMP, si_syscall will be set to the syscall that
  61 failed the rules, and si_arch will be set to the AUDIT_ARCH for the active ABI.
  62 .TP
  63 .B SCMP_ACT_ERRNO(uint16_t errno)
  64 The thread will receive a return value of
  65 .I errno
  66 when it calls a syscall that does not match any of the configured seccomp filter
  67 rules.
  68 .TP
  69 .B SCMP_ACT_TRACE(uint16_t msg_num)
  70 If the thread is being traced and the tracing process specified the
  71 .B PTRACE_O_TRACESECCOMP
  72 option in the call to
  73 .BR ptrace (2),
  74 the tracing process will be notified, via
  75 .BR PTRACE_EVENT_SECCOMP ,
  76 and the value provided in
  77 .I msg_num
  78 can be retrieved using the
  79 .B PTRACE_GETEVENTMSG
  80 option.
  81 .TP
  82 .B SCMP_ACT_ALLOW
  83 The seccomp filter will have no effect on the thread calling the syscall if it
  84 does not match any of the configured seccomp filter rules.
  85 .\" //////////////////////////////////////////////////////////////////////////
  86 .SH RETURN VALUE
  87 .\" //////////////////////////////////////////////////////////////////////////
  88 The
  89 .BR seccomp_init ()
  90 function returns a filter context on success, NULL on failure.  The
  91 .BR seccomp_reset ()
  92 function returns zero on success, negative errno values on failure.
  93 .\" //////////////////////////////////////////////////////////////////////////
  94 .SH EXAMPLES
  95 .\" //////////////////////////////////////////////////////////////////////////
  96 .nf
  97 #include <seccomp.h>
  98
  99 int main(int argc, char *argv[])
 100 {
 101         int rc = \-1;
 102         scmp_filter_ctx ctx;
 103
 104         ctx = seccomp_init(SCMP_ACT_KILL);
 105         if (ctx == NULL)
 106                 goto out;
 107
 108         /* ... */
 109
 110         rc = seccomp_reset(ctx, SCMP_ACT_KILL);
 111         if (rc < 0)
 112                 goto out;
 113
 114         /* ... */
 115
 116 out:
 117         seccomp_release(ctx);
 118         return \-rc;
 119 }
 120 .fi
 121 .\" //////////////////////////////////////////////////////////////////////////
 122 .SH NOTES
 123 .\" //////////////////////////////////////////////////////////////////////////
 124 .P
 125 While the seccomp filter can be generated independent of the kernel, kernel
 126 support is required to load and enforce the seccomp filter generated by
 127 libseccomp.
 128 .P
 129 The libseccomp project site, with more information and the source code
 130 repository, can be found at https://github.com/seccomp/libseccomp.  This tool,
 131 as well as the libseccomp library, is currently under development, please
 132 report any bugs at the project site or directly to the author.
 133 .\" //////////////////////////////////////////////////////////////////////////
 134 .SH AUTHOR
 135 .\" //////////////////////////////////////////////////////////////////////////
 136 Paul Moore <paul@paul-moore.com>
 137 .\" //////////////////////////////////////////////////////////////////////////
 138 .SH SEE ALSO
 139 .\" //////////////////////////////////////////////////////////////////////////
 140 .BR seccomp_release (3)
 141