]>
Commit | Line | Data |
---|---|---|
8befd5cc MG |
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 |