+++ /dev/null
-.TH "seccomp_rule_add" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
-.\" //////////////////////////////////////////////////////////////////////////
-.SH NAME
-.\" //////////////////////////////////////////////////////////////////////////
-seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule
-.\" //////////////////////////////////////////////////////////////////////////
-.SH SYNOPSIS
-.\" //////////////////////////////////////////////////////////////////////////
-.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 ","
-.BI " enum scmp_compare " op ", " ... ");"
-.BI "struct scmp_arg_cmp SCMP_A0(enum scmp_compare " op ", " ... ");"
-.BI "struct scmp_arg_cmp SCMP_A1(enum scmp_compare " op ", " ... ");"
-.BI "struct scmp_arg_cmp SCMP_A2(enum scmp_compare " op ", " ... ");"
-.BI "struct scmp_arg_cmp SCMP_A3(enum scmp_compare " op ", " ... ");"
-.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(scmp_filter_ctx " ctx ", uint32_t " action ","
-.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
-.BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action ","
-.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
-.sp
-.BI "int seccomp_rule_add_array(scmp_filter_ctx " ctx ","
-.BI " uint32_t " action ", int " syscall ","
-.BI " unsigned int " arg_cnt ","
-.BI " const struct scmp_arg_cmp *"arg_array ");"
-.BI "int seccomp_rule_add_exact_array(scmp_filter_ctx " ctx ","
-.BI " uint32_t " action ", int " syscall ","
-.BI " unsigned int " arg_cnt ","
-.BI " const struct scmp_arg_cmp *"arg_array ");"
-.sp
-Link with \fI\-lseccomp\fP.
-.fi
-.\" //////////////////////////////////////////////////////////////////////////
-.SH DESCRIPTION
-.\" //////////////////////////////////////////////////////////////////////////
-.P
-The
-.BR seccomp_rule_add (),
-.BR seccomp_rule_add_array (),
-.BR seccomp_rule_add_exact (),
-and
-.BR seccomp_rule_add_exact_array ()
-functions all add a new filter rule to the current seccomp filter. The
-.BR seccomp_rule_add ()
-and
-.BR seccomp_rule_add_array ()
-functions will make a "best effort" to add the rule as specified, but may alter
-the rule slightly due to architecture specifics, e.g. socket and ipc functions
-on x86. The
-.BR seccomp_rule_add_exact ()
-and
-.BR seccomp_rule_add_exact_array ()
-functions will attempt to add the rule exactly as specified so it may behave
-differently on different architectures. While it does not guarantee a exact
-filter ruleset,
-.BR seccomp_rule_add ()
-and
-.BR seccomp_rule_add_array ()
-do guarantee the same behavior regardless of the architecture.
-.P
-The newly added filter rule does not take effect until the entire filter is
-loaded into the kernel using
-.BR seccomp_load (3).
-.P
-The
-.BR SCMP_CMP ()
-and
-.BR SCMP_A{0-5} ()
-macros generate a scmp_arg_cmp structure for use with the above functions. The
-.BR SCMP_CMP ()
-macro allows the caller to specify an arbitrary argument along with the
-comparison operator, mask, and datum values where the
-.BR SCMP_A{0-5} ()
-macros are specific to a certain argument. See the EXAMPLES section below.
-.P
-While it is possible to specify the
-.I syscall
-value directly using the standard
-.B __NR_syscall
-values, in order to ensure proper operation across multiple architectures it
-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:
-.TP
-.B SCMP_ACT_KILL
-The thread will be killed by the kernel when it calls a syscall that does not
-match any of the configured seccomp filter rules.
-.TP
-.B SCMP_ACT_TRAP
-The thread will throw a SIGSYS signal when it calls a syscall that does not
-match any of the configured seccomp filter rules.
-.TP
-.B SCMP_ACT_ERRNO(uint16_t errno)
-The thread will receive a return value of
-.I errno
-when it calls a syscall that does not match any of the configured seccomp filter
-rules.
-.TP
-.B SCMP_ACT_TRACE(uint16_t msg_num)
-If the thread is being traced and the tracing process specified the
-.B PTRACE_O_TRACESECCOMP
-option in the call to
-.BR ptrace (2),
-the tracing process will be notified, via
-.B PTRACE_EVENT_SECCOMP
-, and the value provided in
-.I msg_num
-can be retrieved using the
-.B PTRACE_GETEVENTMSG
-option.
-.TP
-.B SCMP_ACT_ALLOW
-The seccomp filter will have no effect on the thread calling the syscall if it
-does not match any of the configured seccomp filter rules.
-.P
-Valid comparison
-.I op
-values are as follows:
-.TP
-.B SCMP_CMP_NE
-Matches when the argument value is not equal to the datum value, example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_NE ,
-.I datum
-)
-.TP
-.B SCMP_CMP_LT
-Matches when the argument value is less than the datum value, example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_LT ,
-.I datum
-)
-.TP
-.B SCMP_CMP_LE
-Matches when the argument value is less than or equal to the datum value,
-example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_LE ,
-.I datum
-)
-.TP
-.B SCMP_CMP_EQ
-Matches when the argument value is equal to the datum value, example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_EQ ,
-.I datum
-)
-.TP
-.B SCMP_CMP_GE
-Matches when the argument value is greater than or equal to the datum value,
-example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_GE ,
-.I datum
-)
-.TP
-.B SCMP_CMP_GT
-Matches when the argument value is greater than the datum value, example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_GT ,
-.I datum
-)
-.TP
-.B SCMP_CMP_MASKED_EQ
-Matches when the masked argument value is equal to the masked datum value,
-example:
-.sp
-SCMP_CMP(
-.I arg
-, SCMP_CMP_MASKED_EQ ,
-.I mask
-,
-.I datum
-)
-.\" //////////////////////////////////////////////////////////////////////////
-.SH RETURN VALUE
-.\" //////////////////////////////////////////////////////////////////////////
-The
-.BR seccomp_rule_add (),
-.BR seccomp_rule_add_array (),
-.BR seccomp_rule_add_exact (),
-and
-.BR seccomp_rule_add_exact_array ()
-functions return zero on success, negative errno values on failure.
-.\" //////////////////////////////////////////////////////////////////////////
-.SH EXAMPLES
-.\" //////////////////////////////////////////////////////////////////////////
-.nf
-#include <fcntl.h>
-#include <seccomp.h>
-#include <sys/stat.h>
-#include <sys/types.h>
-
-#define BUF_SIZE 256
-
-int main(int argc, char *argv[])
-{
- int rc = \-1;
- scmp_filter_ctx ctx;
- struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
- int fd;
- unsigned char buf[BUF_SIZE];
-
- ctx = seccomp_init(SCMP_ACT_KILL);
- if (ctx == NULL)
- goto out;
-
- /* ... */
-
- fd = open("file.txt", 0);
-
- /* ... */
-
- rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
- if (rc < 0)
- goto out;
-
- 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(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
- SCMP_CMP(0, SCMP_CMP_EQ, fd));
- if (rc < 0)
- goto out;
-
- rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
- arg_cmp);
- if (rc < 0)
- goto out;
-
- rc = seccomp_load(ctx);
- if (rc < 0)
- goto out;
-
- /* ... */
-
-out:
- seccomp_release(ctx);
- return \-rc;
-}
-.fi
-.\" //////////////////////////////////////////////////////////////////////////
-.SH NOTES
-.\" //////////////////////////////////////////////////////////////////////////
-.P
-While the seccomp filter can be generated independent of the kernel, kernel
-support is required to load and enforce the seccomp filter generated by
-libseccomp.
-.P
-The libseccomp project site, with more information and the source code
-repository, can be found at https://github.com/seccomp/libseccomp. This tool,
-as well as the libseccomp library, is currently under development, please
-report any bugs at the project site or directly to the author.
-.\" //////////////////////////////////////////////////////////////////////////
-.SH AUTHOR
-.\" //////////////////////////////////////////////////////////////////////////
-Paul Moore <paul@paul-moore.com>
-.\" //////////////////////////////////////////////////////////////////////////
-.SH SEE ALSO
-.\" //////////////////////////////////////////////////////////////////////////
-.BR seccomp_syscall_priority (3),
-.BR seccomp_load (3)
projects / linux-seccomp.git / blobdiff