.\" Man page generated from reStructuredText.
.
-.TH BPF-HELPERS 7 2022-09-09 "" ""
-.SH NAME
-BPF-HELPERS \- list of eBPF helper functions
.
.nr rst2man-indent-level 0
.
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
+.TH "BPF-HELPERS" 7 "2022-09-26" "Linux v6.1"
+.SH NAME
+BPF-HELPERS \- list of eBPF helper functions
.\" Copyright (C) All BPF authors and contributors from 2014 to present.
.
.\" See git log include/uapi/linux/bpf.h in kernel tree for details.
.
.\"
.
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.
.\"
.
The extended Berkeley Packet Filter (eBPF) subsystem consists in programs
written in a pseudo\-assembly language, then attached to one of the several
kernel hooks and run in reaction of specific events. This framework differs
-from the older, "classic" BPF (or "cBPF") in several aspects, one of them being
-the ability to call special functions (or "helpers") from within a program.
+from the older, \(dqclassic\(dq BPF (or \(dqcBPF\(dq) in several aspects, one of them being
+the ability to call special functions (or \(dqhelpers\(dq) from within a program.
These functions are restricted to a white\-list of helpers defined in the
kernel.
.sp
.INDENT 7.0
.TP
.B Description
-This helper is a "printk()\-like" facility for debugging. It
+This helper is a \(dqprintk()\-like\(dq facility for debugging. It
prints a message defined by format \fIfmt\fP (of size \fIfmt_size\fP)
to file \fI/sys/kernel/debug/tracing/trace\fP from DebugFS, if
available. It can take up to three additional \fBu64\fP
Also, note that \fBbpf_trace_printk\fP() is slow, and should
only be used for debugging purposes. For this reason, a notice
block (spanning several lines) is printed to kernel logs and
-states that the helper should not be used "for production use"
+states that the helper should not be used \(dqfor production use\(dq
the first time this helper is used (or more precisely, when
\fBtrace_printk\fP() buffers are allocated). For passing values
to user space, perf events should be preferred.
.INDENT 7.0
.TP
.B Description
-This special helper is used to trigger a "tail call", or in
+This special helper is used to trigger a \(dqtail call\(dq, or in
other words, to jump into another eBPF program. The same stack
frame is used (but values on stack and in registers for the
caller are not accessible to the callee). This mechanism allows
.sp
This helper is only available is the kernel was compiled with
the \fBCONFIG_CGROUP_NET_CLASSID\fP configuration option set to
-"\fBy\fP" or to "\fBm\fP".
+\(dq\fBy\fP\(dq or to \(dq\fBm\fP\(dq.
.TP
.B Return
The classid, or 0 for the default unconfigured classid.
principal parameters used by various tunneling protocols into a
single struct. This way, it can be used to easily make a
decision based on the contents of the encapsulation header,
-"summarized" in this struct. In particular, it holds the IP
+\(dqsummarized\(dq in this struct. In particular, it holds the IP
address of the remote end (IPv4 or IPv6, depending on the case)
in \fIkey\fP\fB\->remote_ipv4\fP or \fIkey\fP\fB\->remote_ipv6\fP\&. Also,
this struct exposes the \fIkey\fP\fB\->tunnel_id\fP, which is
.UNINDENT
.sp
This interface can also be used with all encapsulation devices
-that can operate in "collect metadata" mode: instead of having
-one network device per specific configuration, the "collect
-metadata" mode only requires a single device where the
+that can operate in \(dqcollect metadata\(dq mode: instead of having
+one network device per specific configuration, the \(dqcollect
+metadata\(dq mode only requires a single device where the
configuration can be extracted from this helper.
.sp
This can be used together with various tunnels such as VXLan,
\fIto\fP\&.
.sp
Since Linux 4.7, usage of this helper has mostly been replaced
-by "direct packet access", enabling packet data to be
+by \(dqdirect packet access\(dq, enabling packet data to be
manipulated with \fIskb\fP\fB\->data\fP and \fIskb\fP\fB\->data_end\fP
pointing respectively to the first byte of packet data and to
the byte after the last byte of packet data. However, it
of \fIsize\fP\&.
.sp
This helper can be used with encapsulation devices that can
-operate in "collect metadata" mode (please refer to the related
+operate in \(dqcollect metadata\(dq mode (please refer to the related
note in the description of \fBbpf_skb_get_tunnel_key\fP() for
more details). A particular example where this can be used is
in combination with the Geneve encapsulation protocol, where it
Pull in non\-linear data in case the \fIskb\fP is non\-linear and not
all of \fIlen\fP are part of the linear section. Make \fIlen\fP bytes
from \fIskb\fP readable and writable. If a zero value is passed for
-\fIlen\fP, then the whole length of the \fIskb\fP is pulled.
+\fIlen\fP, then all bytes in the linear part of \fIskb\fP will be made
+readable and writable.
.sp
This helper is only needed for reading and writing with direct
packet access.
.INDENT 7.0
.IP \(bu 2
\fBBPF_ADJ_ROOM_MAC\fP: Adjust room at the mac layer
-(room space is added or removed below the layer 2 header).
+(room space is added or removed between the layer 2 and
+layer 3 headers).
.IP \(bu 2
\fBBPF_ADJ_ROOM_NET\fP: Adjust room at the network layer
-(room space is added or removed below the layer 3 header).
+(room space is added or removed between the layer 3 and
+layer 4 headers).
.UNINDENT
.sp
The following flags are supported at this time:
.TP
.B Description
Retrieve the XFRM state (IP transform framework, see also
-\fBip\-xfrm(8)\fP) at \fIindex\fP in XFRM "security path" for \fIskb\fP\&.
+\fBip\-xfrm(8)\fP) at \fIindex\fP in XFRM \(dqsecurity path\(dq for \fIskb\fP\&.
.sp
The retrieved value is stored in the \fBstruct bpf_xfrm_state\fP
pointed by \fIxfrm_state\fP and of length \fIsize\fP\&.
Collect a user space stack instead of a kernel stack.
.TP
.B \fBBPF_F_USER_BUILD_ID\fP
-Collect buildid+offset instead of ips for user stack,
-only valid if \fBBPF_F_USER_STACK\fP is also specified.
+Collect (build_id, file_offset) instead of ips for user
+stack, only valid if \fBBPF_F_USER_STACK\fP is also
+specified.
+.sp
+\fIfile_offset\fP is an offset relative to the beginning
+of the executable or shared object file backing the vma
+which the \fIip\fP falls in. It is \fInot\fP an offset relative
+to that object\(aqs base address. Accordingly, it must be
+adjusted by adding (sh_addr \- sh_offset), where
+sh_{addr,offset} correspond to the executable section
+containing \fIfile_offset\fP in the object, for comparisons
+to symbols\(aq st_value to be valid.
.UNINDENT
.sp
\fBbpf_get_stack\fP() can collect up to
Base offset to load data from is \fIskb\fP\(aqs network header.
.UNINDENT
.sp
-In general, "direct packet access" is the preferred method to
+In general, \(dqdirect packet access\(dq is the preferred method to
access packet data, however, this helper is in particular useful
in socket filters where \fIskb\fP\fB\->data\fP does not always point
-to the start of the mac header and where "direct packet access"
+to the start of the mac header and where \(dqdirect packet access\(dq
is not available.
.TP
.B Return
.sp
This helper is only available is the kernel was compiled with
the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to
-"\fBy\fP".
+\(dq\fBy\fP\(dq.
.TP
.B Return
0
.sp
This helper is only available is the kernel was compiled with
the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to
-"\fBy\fP".
+\(dq\fBy\fP\(dq.
.TP
.B Return
0
.sp
This helper is only available is the kernel was compiled with
the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to
-"\fBy\fP".
+\(dq\fBy\fP\(dq.
.TP
.B Return
0
.sp
\fIiph\fP points to the start of the IPv4 or IPv6 header, while
\fIiph_len\fP contains \fBsizeof\fP(\fBstruct iphdr\fP) or
-\fBsizeof\fP(\fBstruct ip6hdr\fP).
+\fBsizeof\fP(\fBstruct ipv6hdr\fP).
.sp
\fIth\fP points to the start of the TCP header, while \fIth_len\fP
-contains \fBsizeof\fP(\fBstruct tcphdr\fP).
+contains the length of the TCP header (at least
+\fBsizeof\fP(\fBstruct tcphdr\fP)).
.TP
.B Return
0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK, or a negative
.sp
The buffer is always NUL terminated, unless it\(aqs zero\-sized.
.sp
-If \fIflags\fP is zero, full name (e.g. "net/ipv4/tcp_mem") is
+If \fIflags\fP is zero, full name (e.g. \(dqnet/ipv4/tcp_mem\(dq) is
copied. Use \fBBPF_F_SYSCTL_BASE_NAME\fP flag to copy base name
-only (e.g. "tcp_mem").
+only (e.g. \(dqtcp_mem\(dq).
.TP
.B Return
Number of character copied (not including the trailing NUL).
.sp
Underneath, the value is stored locally at \fIsk\fP instead of
the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage
-"type". The bpf\-local\-storage "type" (i.e. the \fImap\fP) is
+\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is
searched against all bpf\-local\-storages residing at \fIsk\fP\&.
.sp
\fIsk\fP is a kernel \fBstruct sock\fP pointer for LSM program.
.sp
\fIiph\fP points to the start of the IPv4 or IPv6 header, while
\fIiph_len\fP contains \fBsizeof\fP(\fBstruct iphdr\fP) or
-\fBsizeof\fP(\fBstruct ip6hdr\fP).
+\fBsizeof\fP(\fBstruct ipv6hdr\fP).
.sp
\fIth\fP points to the start of the TCP header, while \fIth_len\fP
-contains the length of the TCP header.
+contains the length of the TCP header with options (at least
+\fBsizeof\fP(\fBstruct tcphdr\fP)).
.TP
.B Return
On success, lower 32 bits hold the generated SYN cookie in
.sp
.nf
.ft C
-SEC("kprobe/sys_open")
+SEC(\(dqkprobe/sys_open\(dq)
void bpf_sys_open(struct pt_regs *ctx)
{
char buf[PATHLEN]; // PATHLEN is defined to 256
.sp
If the searching kind is an experimental kind
(i.e. 253 or 254 according to RFC6994). It also
-needs to specify the "magic" which is either
+needs to specify the \(dqmagic\(dq which is either
2 bytes or 4 bytes. It then also needs to
specify the size of the magic by using
-the 2nd byte which is "kind\-length" of a TCP
-header option and the "kind\-length" also
-includes the first 2 bytes "kind" and "kind\-length"
+the 2nd byte which is \(dqkind\-length\(dq of a TCP
+header option and the \(dqkind\-length\(dq also
+includes the first 2 bytes \(dqkind\(dq and \(dqkind\-length\(dq
itself as a normal TCP header option also does.
.sp
For example, to search experimental kind 254 with
.sp
Underneath, the value is stored locally at \fIinode\fP instead of
the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage
-"type". The bpf\-local\-storage "type" (i.e. the \fImap\fP) is
+\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is
searched against all bpf_local_storage residing at \fIinode\fP\&.
.sp
An optional \fIflags\fP (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) can be
a \fImap\fP with \fItask\fP as the \fBkey\fP\&. From this
perspective, the usage is not much different from
\fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fItask\fP) except this
-helper enforces the key must be an task_struct and the map must also
+helper enforces the key must be a task_struct and the map must also
be a \fBBPF_MAP_TYPE_TASK_STORAGE\fP\&.
.sp
Underneath, the value is stored locally at \fItask\fP instead of
the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage
-"type". The bpf\-local\-storage "type" (i.e. the \fImap\fP) is
+\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is
searched against all bpf_local_storage residing at \fItask\fP\&.
.sp
An optional \fIflags\fP (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) can be
.INDENT 7.0
.TP
.B Description
-Return a BTF pointer to the "current" task.
+Return a BTF pointer to the \(dqcurrent\(dq task.
This pointer can also be used in helpers that accept an
\fIARG_PTR_TO_BTF_ID\fP of type \fItask_struct\fP\&.
.TP
.sp
The argument \fIlen_diff\fP can be used for querying with a planned
size change. This allows to check MTU prior to changing packet
-ctx. Providing an \fIlen_diff\fP adjustment that is larger than the
+ctx. Providing a \fIlen_diff\fP adjustment that is larger than the
actual packet size (resulting in negative packet size) will in
-principle not exceed the MTU, why it is not considered a
-failure. Other BPF\-helpers are needed for performing the
-planned size change, why the responsibility for catch a negative
-packet size belong in those helpers.
+principle not exceed the MTU, which is why it is not considered
+a failure. Other BPF helpers are needed for performing the
+planned size change; therefore the responsibility for catching
+a negative packet size belongs in those helpers.
.sp
Specifying \fIifindex\fP zero means the MTU check is performed
against the current net device. This is practical if this isn\(aqt
.TP
.B Return
Address of the traced function.
+0 for kprobes placed within the function (not at the entry).
.UNINDENT
.TP
.B \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP
.INDENT 7.0
.TP
.B Description
-Get \fBn\fP\-th argument (zero based) of the traced function (for tracing programs)
+Get \fBn\fP\-th argument register (zero based) of the traced function (for tracing programs)
returned in \fBvalue\fP\&.
.TP
.B Return
0 on success.
-\fB\-EINVAL\fP if n >= arguments count of traced function.
+\fB\-EINVAL\fP if n >= argument register count of traced function.
.UNINDENT
.TP
.B \fBlong bpf_get_func_ret(void *\fP\fIctx\fP\fB, u64 *\fP\fIvalue\fP\fB)\fP
.INDENT 7.0
.TP
.B Description
-Get number of arguments of the traced function (for tracing programs).
+Get number of registers of the traced function (for tracing programs) where
+function arguments are stored in these registers.
.TP
.B Return
-The number of arguments of the traced function.
+The number of argument registers of the traced function.
.UNINDENT
.TP
.B \fBint bpf_get_retval(void)\fP
.INDENT 7.0
.TP
.B Description
-Get the syscall\(aqs return value that will be returned to userspace.
+Get the BPF program\(aqs return value that will be returned to the upper layers.
.sp
-This helper is currently supported by cgroup programs only.
+This helper is currently supported by cgroup programs and only by the hooks
+where BPF program\(aqs return value is returned to the userspace via errno.
.TP
.B Return
-The syscall\(aqs return value.
+The BPF program\(aqs return value.
.UNINDENT
.TP
.B \fBint bpf_set_retval(int\fP \fIretval\fP\fB)\fP
.INDENT 7.0
.TP
.B Description
-Set the syscall\(aqs return value that will be returned to userspace.
+Set the BPF program\(aqs return value that will be returned to the upper layers.
+.sp
+This helper is currently supported by cgroup programs and only by the hooks
+where BPF program\(aqs return value is returned to the userspace via errno.
+.sp
+Note that there is the following corner case where the program exports an error
+via bpf_set_retval but signals success via \(aqreturn 1\(aq:
+.INDENT 7.0
+.INDENT 3.5
+bpf_set_retval(\-EPERM);
+return 1;
+.UNINDENT
+.UNINDENT
.sp
-This helper is currently supported by cgroup programs only.
+In this case, the BPF program\(aqs return value will use helper\(aqs \-EPERM. This
+still holds true for cgroup/bind{4,6} which supports extra \(aqreturn 3\(aq success case.
.TP
.B Return
0 on success, or a negative error in case of failure.
\fB\-EOPNOTSUP\fP if the hash calculation failed or \fB\-EINVAL\fP if
invalid arguments are passed.
.UNINDENT
+.TP
+.B \fBvoid *bpf_kptr_xchg(void *\fP\fImap_value\fP\fB, void *\fP\fIptr\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Exchange kptr at pointer \fImap_value\fP with \fIptr\fP, and return the
+old value. \fIptr\fP can be NULL, otherwise it must be a referenced
+pointer which will be released when this helper is called.
+.TP
+.B Return
+The old value of kptr (which can be NULL). The returned pointer
+if not NULL, is a reference which must be released using its
+corresponding release function, or moved into a BPF map before
+program exit.
+.UNINDENT
+.TP
+.B \fBvoid *bpf_map_lookup_percpu_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB, u32\fP \fIcpu\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Perform a lookup in \fIpercpu map\fP for an entry associated to
+\fIkey\fP on \fIcpu\fP\&.
+.TP
+.B Return
+Map value associated to \fIkey\fP on \fIcpu\fP, or \fBNULL\fP if no entry
+was found or \fIcpu\fP is invalid.
+.UNINDENT
+.TP
+.B \fBstruct mptcp_sock *bpf_skc_to_mptcp_sock(void *\fP\fIsk\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Dynamically cast a \fIsk\fP pointer to a \fImptcp_sock\fP pointer.
+.TP
+.B Return
+\fIsk\fP if casting is valid, or \fBNULL\fP otherwise.
+.UNINDENT
+.TP
+.B \fBlong bpf_dynptr_from_mem(void *\fP\fIdata\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Get a dynptr to local memory \fIdata\fP\&.
+.sp
+\fIdata\fP must be a ptr to a map value.
+The maximum \fIsize\fP supported is DYNPTR_MAX_SIZE.
+\fIflags\fP is currently unused.
+.TP
+.B Return
+0 on success, \-E2BIG if the size exceeds DYNPTR_MAX_SIZE,
+\-EINVAL if flags is not 0.
+.UNINDENT
+.TP
+.B \fBlong bpf_ringbuf_reserve_dynptr(void *\fP\fIringbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Reserve \fIsize\fP bytes of payload in a ring buffer \fIringbuf\fP
+through the dynptr interface. \fIflags\fP must be 0.
+.sp
+Please note that a corresponding bpf_ringbuf_submit_dynptr or
+bpf_ringbuf_discard_dynptr must be called on \fIptr\fP, even if the
+reservation fails. This is enforced by the verifier.
+.TP
+.B Return
+0 on success, or a negative error in case of failure.
+.UNINDENT
+.TP
+.B \fBvoid bpf_ringbuf_submit_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64\fP \fIflags\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Submit reserved ring buffer sample, pointed to by \fIdata\fP,
+through the dynptr interface. This is a no\-op if the dynptr is
+invalid/null.
+.sp
+For more information on \fIflags\fP, please see
+\(aqbpf_ringbuf_submit\(aq.
+.TP
+.B Return
+Nothing. Always succeeds.
+.UNINDENT
+.TP
+.B \fBvoid bpf_ringbuf_discard_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64\fP \fIflags\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Discard reserved ring buffer sample through the dynptr
+interface. This is a no\-op if the dynptr is invalid/null.
+.sp
+For more information on \fIflags\fP, please see
+\(aqbpf_ringbuf_discard\(aq.
+.TP
+.B Return
+Nothing. Always succeeds.
+.UNINDENT
+.TP
+.B \fBlong bpf_dynptr_read(void *\fP\fIdst\fP\fB, u32\fP \fIlen\fP\fB, struct bpf_dynptr *\fP\fIsrc\fP\fB, u32\fP \fIoffset\fP\fB, u64\fP \fIflags\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Read \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP
+into \fIsrc\fP\&.
+\fIflags\fP is currently unused.
+.TP
+.B Return
+0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length
+of \fIsrc\fP\(aqs data, \-EINVAL if \fIsrc\fP is an invalid dynptr or if
+\fIflags\fP is not 0.
+.UNINDENT
+.TP
+.B \fBlong bpf_dynptr_write(struct bpf_dynptr *\fP\fIdst\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIsrc\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Write \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP
+into \fIdst\fP\&.
+\fIflags\fP is currently unused.
+.TP
+.B Return
+0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length
+of \fIdst\fP\(aqs data, \-EINVAL if \fIdst\fP is an invalid dynptr or if \fIdst\fP
+is a read\-only dynptr or if \fIflags\fP is not 0.
+.UNINDENT
+.TP
+.B \fBvoid *bpf_dynptr_data(struct bpf_dynptr *\fP\fIptr\fP\fB, u32\fP \fIoffset\fP\fB, u32\fP \fIlen\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Get a pointer to the underlying dynptr data.
+.sp
+\fIlen\fP must be a statically known value. The returned data slice
+is invalidated whenever the dynptr is invalidated.
+.TP
+.B Return
+Pointer to the underlying dynptr data, NULL if the dynptr is
+read\-only, if the dynptr is invalid, or if the offset and length
+is out of bounds.
+.UNINDENT
+.TP
+.B \fBs64 bpf_tcp_raw_gen_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Try to issue a SYN cookie for the packet with corresponding
+IPv4/TCP headers, \fIiph\fP and \fIth\fP, without depending on a
+listening socket.
+.sp
+\fIiph\fP points to the IPv4 header.
+.sp
+\fIth\fP points to the start of the TCP header, while \fIth_len\fP
+contains the length of the TCP header (at least
+\fBsizeof\fP(\fBstruct tcphdr\fP)).
+.TP
+.B Return
+On success, lower 32 bits hold the generated SYN cookie in
+followed by 16 bits which hold the MSS value for that cookie,
+and the top 16 bits are unused.
+.sp
+On failure, the returned value is one of the following:
+.sp
+\fB\-EINVAL\fP if \fIth_len\fP is invalid.
+.UNINDENT
+.TP
+.B \fBs64 bpf_tcp_raw_gen_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Try to issue a SYN cookie for the packet with corresponding
+IPv6/TCP headers, \fIiph\fP and \fIth\fP, without depending on a
+listening socket.
+.sp
+\fIiph\fP points to the IPv6 header.
+.sp
+\fIth\fP points to the start of the TCP header, while \fIth_len\fP
+contains the length of the TCP header (at least
+\fBsizeof\fP(\fBstruct tcphdr\fP)).
+.TP
+.B Return
+On success, lower 32 bits hold the generated SYN cookie in
+followed by 16 bits which hold the MSS value for that cookie,
+and the top 16 bits are unused.
+.sp
+On failure, the returned value is one of the following:
+.sp
+\fB\-EINVAL\fP if \fIth_len\fP is invalid.
+.sp
+\fB\-EPROTONOSUPPORT\fP if CONFIG_IPV6 is not builtin.
+.UNINDENT
+.TP
+.B \fBlong bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Check whether \fIiph\fP and \fIth\fP contain a valid SYN cookie ACK
+without depending on a listening socket.
+.sp
+\fIiph\fP points to the IPv4 header.
+.sp
+\fIth\fP points to the TCP header.
+.TP
+.B Return
+0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK.
+.sp
+On failure, the returned value is one of the following:
+.sp
+\fB\-EACCES\fP if the SYN cookie is not valid.
+.UNINDENT
+.TP
+.B \fBlong bpf_tcp_raw_check_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Check whether \fIiph\fP and \fIth\fP contain a valid SYN cookie ACK
+without depending on a listening socket.
+.sp
+\fIiph\fP points to the IPv6 header.
+.sp
+\fIth\fP points to the TCP header.
+.TP
+.B Return
+0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK.
+.sp
+On failure, the returned value is one of the following:
+.sp
+\fB\-EACCES\fP if the SYN cookie is not valid.
+.sp
+\fB\-EPROTONOSUPPORT\fP if CONFIG_IPV6 is not builtin.
+.UNINDENT
+.TP
+.B \fBu64 bpf_ktime_get_tai_ns(void)\fP
+.INDENT 7.0
+.TP
+.B Description
+A nonsettable system\-wide clock derived from wall\-clock time but
+ignoring leap seconds. This clock does not experience
+discontinuities and backwards jumps caused by NTP inserting leap
+seconds as CLOCK_REALTIME does.
+.sp
+See: \fBclock_gettime\fP(\fBCLOCK_TAI\fP)
+.TP
+.B Return
+Current \fIktime\fP\&.
+.UNINDENT
+.TP
+.B \fBlong bpf_user_ringbuf_drain(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIctx\fP\fB, u64\fP \fIflags\fP\fB)\fP
+.INDENT 7.0
+.TP
+.B Description
+Drain samples from the specified user ring buffer, and invoke
+the provided callback for each such sample:
+.sp
+long (*callback_fn)(struct bpf_dynptr *dynptr, void *ctx);
+.sp
+If \fBcallback_fn\fP returns 0, the helper will continue to try
+and drain the next sample, up to a maximum of
+BPF_MAX_USER_RINGBUF_SAMPLES samples. If the return value is 1,
+the helper will skip the rest of the samples and return. Other
+return values are not used now, and will be rejected by the
+verifier.
+.TP
+.B Return
+The number of drained samples if no error was encountered while
+draining samples, or 0 if no samples were present in the ring
+buffer. If a user\-space producer was epoll\-waiting on this map,
+and at least one sample was drained, they will receive an event
+notification notifying them of available space in the ring
+buffer. If the BPF_RB_NO_WAKEUP flag is passed to this
+function, no wakeup notification will be sent. If the
+BPF_RB_FORCE_WAKEUP flag is passed, a wakeup notification will
+be sent even if no sample was drained.
+.sp
+On failure, the returned value is one of the following:
+.sp
+\fB\-EBUSY\fP if the ring buffer is contended, and another calling
+context was concurrently draining the ring buffer.
+.sp
+\fB\-EINVAL\fP if user\-space is not properly tracking the ring
+buffer due to the producer position not being aligned to 8
+bytes, a sample not being aligned to 8 bytes, or the producer
+position not matching the advertised length of a sample.
+.sp
+\fB\-E2BIG\fP if user\-space has tried to publish a sample which is
+larger than the size of the ring buffer, or which cannot fit
+within a struct bpf_dynptr.
+.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
eBPF programs can have an associated license, passed along with the bytecode
instructions to the kernel when the programs are loaded. The format for that
string is identical to the one in use for kernel modules (Dual licenses, such
-as "Dual BSD/GPL", may be used). Some helper functions are only accessible to
+as \(dqDual BSD/GPL\(dq, may be used). Some helper functions are only accessible to
programs that are compatible with the GNU Privacy License (GPL).
.sp
In order to use such helpers, the eBPF program must be loaded with the correct
.sp
.nf
.ft C
-char ____license[] __attribute__((section("license"), used)) = "GPL";
+char ____license[] __attribute__((section(\(dqlicense\(dq), used)) = \(dqGPL\(dq;
.ft P
.fi
.UNINDENT
projects / thirdparty / man-pages.git / commitdiff
