.TH "seccomp_transaction_start" 3 "21 September 2023" "paul@paul-moore.com" "libseccomp Documentation"
.\" //////////////////////////////////////////////////////////////////////////
.SH NAME
.\" //////////////////////////////////////////////////////////////////////////
seccomp_transaction_start, seccomp_transaction_commit, seccomp_transaction_reject \- Manage seccomp filter transactions
.\" //////////////////////////////////////////////////////////////////////////
.SH SYNOPSIS
.\" //////////////////////////////////////////////////////////////////////////
.nf
.B #include <seccomp.h>
.sp
.B typedef void * scmp_filter_ctx;
.sp
.BI "int seccomp_transaction_start(scmp_filter_ctx " ctx ");
.BI "int seccomp_transaction_commit(scmp_filter_ctx " ctx ");
.BI "void seccomp_transaction_reject(scmp_filter_ctx " ctx ");
.sp
Link with \fI\-lseccomp\fP.
.fi
.\" //////////////////////////////////////////////////////////////////////////
.SH DESCRIPTION
.\" //////////////////////////////////////////////////////////////////////////
.P
The
.BR seccomp_transaction_start ()
function starts a new seccomp filter
transaction that the caller can use to perform any number of filter
modifications which can then be committed to the filter using
.BR seccomp_transaction_commit ()
or rejected using
.BR seccomp_transaction_reject ().
It is important to note that transactions only affect the seccomp filter state
while it is being managed by libseccomp; seccomp filters which have been loaded
into the kernel can not be modified, only new seccomp filters can be added on
top of the existing loaded filter stack.
.P
Finishing, or committing, a transaction is optional, although it is encouraged.
At any point in time, regardless of the transaction state, the seccomp filter
is determined by all of the libseccomp operations performed on the filter up to
that point.  Committing a transaction simply flushes the transaction rollback
marker of the current transaction making the filter changes permanent;
rejecting a transaction rolls the filter state back to immediately before the
transaction was started.
.P
Transactions can be nested arbitrarily deep with the
.BR seccomp_transaction_commit ()
and
.BR seccomp_transaction_reject ()
functions always operating on the deepest, or more recently started transaction.
A nested set of filter modifications, even if committed, is still subject to
rejection by shallower, or older transactions that have yet to be committed or
rejected.
.\" //////////////////////////////////////////////////////////////////////////
.SH RETURN VALUE
.\" //////////////////////////////////////////////////////////////////////////
The
.BR seccomp_transaction_start ()
and
.BR seccomp_transaction_commit ()
functions return zero on success or one of the following error codes on
failure:
.TP
.B -EINVAL
The context is invalid.
.TP
.B -ENOMEM
The library was unable to allocate enough memory.
.\" //////////////////////////////////////////////////////////////////////////
.SH EXAMPLES
.\" //////////////////////////////////////////////////////////////////////////
.nf
#include <seccomp.h>

int libseccomp_generate(scmp_filter_ctx *ctx)
{
	int rc;

	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
	if (rc)
		return rc;
	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit_group), 0);
	if (rc)
		return rc;
	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit), 0);
	if (rc)
		return rc;

	return 0;
}

int main(int argc, char *argv[])
{
	int rc = \-1;
	scmp_filter_ctx ctx;

	ctx = seccomp_init(SCMP_ACT_KILL);
	if (ctx == NULL)
		goto out;

	rc = seccomp_transaction_start(ctx)
	if (rc)
		goto out;
	rc = libseccomp_generate(ctx);
	if (rc == 0) {
		rc = seccomp_transaction_commit(ctx);
		if (rc)
			goto out;
	} else
		seccomp_transaction_reject(ctx);

	/* ... */

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_init (3),