mirror of https://github.com/mkerrisk/man-pages
bpf-helpers.7: Sync against Linux 5.7-rc1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
d407f83e5f
commit
4e2b112c91
|
|
@ -1,6 +1,6 @@
|
|||
.\" Man page generated from reStructuredText.
|
||||
.
|
||||
.TH BPF-HELPERS 7 2019-11-19 "Linux" "Linux Programmer's Manual"
|
||||
.TH BPF-HELPERS 7 "" "" ""
|
||||
.SH NAME
|
||||
BPF-HELPERS \- list of eBPF helper functions
|
||||
.
|
||||
|
|
@ -32,17 +32,17 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
..
|
||||
.\" Copyright (C) All BPF authors and contributors from 2014 to present.
|
||||
.\" See git log include/uapi/linux/bpf.h in kernel tree for details.
|
||||
.\"
|
||||
.\"
|
||||
.\" %%%LICENSE_START(VERBATIM)
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
|
|
@ -50,15 +50,16 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\" %%%LICENSE_END
|
||||
.\"
|
||||
.\"
|
||||
.\" Please do not edit this file. It was generated from the documentation
|
||||
.\" located in file include/uapi/linux/bpf.h of the Linux kernel sources
|
||||
.\" (helpers description), and from scripts/bpf_helpers_doc.py in the same
|
||||
.\" repository (header and footer).
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
.sp
|
||||
The extended Berkeley Packet Filter (eBPF) subsystem consists in programs
|
||||
|
|
@ -135,12 +136,15 @@ Delete entry with \fIkey\fP from \fImap\fP\&.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIsrc\fP\fB)\fP
|
||||
.B \fBint bpf_probe_read(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
For tracing programs, safely attempt to read \fIsize\fP bytes from
|
||||
address \fIsrc\fP and store the data in \fIdst\fP\&.
|
||||
kernel space address \fIunsafe_ptr\fP and store the data in \fIdst\fP\&.
|
||||
.sp
|
||||
Generally, use bpf_probe_read_user() or bpf_probe_read_kernel()
|
||||
instead.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
|
|
@ -432,7 +436,7 @@ A 64\-bit integer containing the current GID and UID, and
|
|||
created as such: \fIcurrent_gid\fP \fB<< 32 |\fP \fIcurrent_uid\fP\&.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_get_current_comm(char *\fP\fIbuf\fP\fB, u32\fP \fIsize_of_buf\fP\fB)\fP
|
||||
.B \fBint bpf_get_current_comm(void *\fP\fIbuf\fP\fB, u32\fP \fIsize_of_buf\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -672,9 +676,9 @@ is present, egress path otherwise). Currently, XDP only
|
|||
supports redirection to the egress interface, and accepts no
|
||||
flag at all.
|
||||
.sp
|
||||
The same effect can be attained with the more generic
|
||||
\fBbpf_redirect_map\fP(), which requires specific maps to be
|
||||
used but offers better performance.
|
||||
The same effect can also be attained with the more generic
|
||||
\fBbpf_redirect_map\fP(), which uses a BPF map to store the
|
||||
redirect target instead of providing it directly to the helper.
|
||||
.TP
|
||||
.B Return
|
||||
For XDP, the helper returns \fBXDP_REDIRECT\fP on success or
|
||||
|
|
@ -711,7 +715,7 @@ The realm of the route for the packet associated to \fIskb\fP, or 0
|
|||
if none was found.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_perf_event_output(struct pt_regs *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP
|
||||
.B \fBint bpf_perf_event_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -764,7 +768,7 @@ A combination of both.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_load_bytes(const struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB)\fP
|
||||
.B \fBint bpf_skb_load_bytes(const void *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -785,7 +789,7 @@ at once from a packet into the eBPF stack.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_get_stackid(struct pt_regs *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_get_stackid(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -876,7 +880,7 @@ The checksum result, or a negative error code in case of
|
|||
failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_get_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, u8 *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP
|
||||
.B \fBint bpf_skb_get_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -898,7 +902,7 @@ headers.
|
|||
The size of the option data retrieved.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_set_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, u8 *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP
|
||||
.B \fBint bpf_skb_set_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1220,52 +1224,16 @@ direct packet access.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read_str(void *\fP\fIdst\fP\fB, int\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.B \fBint bpf_probe_read_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Copy a NUL terminated string from an unsafe address
|
||||
\fIunsafe_ptr\fP to \fIdst\fP\&. The \fIsize\fP should include the
|
||||
terminating NUL byte. In case the string length is smaller than
|
||||
\fIsize\fP, the target is not padded with further NUL bytes. If the
|
||||
string length is larger than \fIsize\fP, just \fIsize\fP\-1 bytes are
|
||||
copied and the last byte is set to NUL.
|
||||
Copy a NUL terminated string from an unsafe kernel address
|
||||
\fIunsafe_ptr\fP to \fIdst\fP\&. See bpf_probe_read_kernel_str() for
|
||||
more details.
|
||||
.sp
|
||||
On success, the length of the copied string is returned. This
|
||||
makes this helper useful in tracing programs for reading
|
||||
strings, and more importantly to get its length at runtime. See
|
||||
the following snippet:
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
SEC("kprobe/sys_open")
|
||||
void bpf_sys_open(struct pt_regs *ctx)
|
||||
{
|
||||
char buf[PATHLEN]; // PATHLEN is defined to 256
|
||||
int res = bpf_probe_read_str(buf, sizeof(buf),
|
||||
ctx\->di);
|
||||
|
||||
// Consume buf, for example push it to
|
||||
// userspace via bpf_perf_event_output(); we
|
||||
// can use res (the string length) as event
|
||||
// size, after checking its boundaries.
|
||||
}
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
In comparison, using \fBbpf_probe_read()\fP helper here instead
|
||||
to read the string would require to estimate the length at
|
||||
compile time, and would often result in copying more memory
|
||||
than necessary.
|
||||
.sp
|
||||
Another useful use case is when parsing individual process
|
||||
arguments or individual environment variables navigating
|
||||
\fIcurrent\fP\fB\->mm\->arg_start\fP and \fIcurrent\fP\fB\->mm\->env_start\fP: using this helper and the return value,
|
||||
one can quickly iterate at the right offset of the memory area.
|
||||
Generally, use bpf_probe_read_user_str() or bpf_probe_read_kernel_str()
|
||||
instead.
|
||||
.TP
|
||||
.B Return
|
||||
On success, the strictly positive length of the string,
|
||||
|
|
@ -1334,7 +1302,7 @@ to value \fIhash\fP\&.
|
|||
0
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_setsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, char *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP
|
||||
.B \fBint bpf_setsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1429,16 +1397,21 @@ one of the XDP program return codes up to XDP_TX, as chosen by
|
|||
the caller. Any higher bits in the \fIflags\fP argument must be
|
||||
unset.
|
||||
.sp
|
||||
When used to redirect packets to net devices, this helper
|
||||
provides a high performance increase over \fBbpf_redirect\fP().
|
||||
This is due to various implementation details of the underlying
|
||||
mechanisms, one of which is the fact that \fBbpf_redirect_map\fP() tries to send packet as a "bulk" to the device.
|
||||
See also bpf_redirect(), which only supports redirecting to an
|
||||
ifindex, but doesn\(aqt require a map to do so.
|
||||
.TP
|
||||
.B Return
|
||||
\fBXDP_REDIRECT\fP on success, or \fBXDP_ABORTED\fP on error.
|
||||
\fBXDP_REDIRECT\fP on success, or the value of the two lower bits
|
||||
of the
|
||||
.nf
|
||||
**
|
||||
.fi
|
||||
flags* argument on error.
|
||||
.IP "System Message: WARNING/2 (/tmp/bpf-helpers.rst:, line 1105)"
|
||||
Inline strong start\-string without end\-string.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_sk_redirect_map(struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_sk_redirect_map(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1587,7 +1560,7 @@ more details).
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_getsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, char *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP
|
||||
.B \fBint bpf_getsockopt(struct bpf_sock_ops *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1878,7 +1851,7 @@ This helper is available only if the kernel was compiled with
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_get_stack(struct pt_regs *\fP\fIregs\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_get_stack(void *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1924,7 +1897,7 @@ A non\-negative value equal to or less than \fIsize\fP on success,
|
|||
or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_load_bytes_relative(const struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB, u32\fP \fIstart_header\fP\fB)\fP
|
||||
.B \fBint bpf_skb_load_bytes_relative(const void *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB, u32\fP \fIstart_header\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -1996,7 +1969,7 @@ packet is not forwarded or needs assist from full stack
|
|||
.UNINDENT
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_sock_hash_update(struct bpf_sock_ops_kern *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_sock_hash_update(struct bpf_sock_ops *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -2455,7 +2428,7 @@ Get an element from \fImap\fP without removing it.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_msg_push_data(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_msg_push_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -2475,11 +2448,11 @@ error and BPF programs will need to handle them.
|
|||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_msg_pop_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIpop\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.B \fBint bpf_msg_pop_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Will remove \fIpop\fP bytes from a \fImsg\fP starting at byte \fIstart\fP\&.
|
||||
Will remove \fIlen\fP bytes from a \fImsg\fP starting at byte \fIstart\fP\&.
|
||||
This may result in \fBENOMEM\fP errors under certain situations if
|
||||
an allocation and copy are required due to a full ring buffer.
|
||||
However, the helper will try to avoid doing the allocation
|
||||
|
|
@ -2613,7 +2586,7 @@ A \fBstruct bpf_tcp_sock\fP pointer on success, or \fBNULL\fP in
|
|||
case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_ecn_set_ce(struct sk_buf *\fP\fIskb\fP\fB)\fP
|
||||
.B \fBint bpf_skb_ecn_set_ce(struct sk_buff *\fP\fIskb\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
|
|
@ -2869,7 +2842,8 @@ Delete a bpf\-local\-storage from a \fIsk\fP\&.
|
|||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Send signal \fIsig\fP to the current task.
|
||||
Send signal \fIsig\fP to the process of the current task.
|
||||
The signal may be delivered to any of this process\(aqs threads.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success or successfully queued.
|
||||
|
|
@ -2912,6 +2886,300 @@ On failure, the returned value is one of the following:
|
|||
.sp
|
||||
\fB\-EPROTONOSUPPORT\fP IP packet version is not 4 or 6
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_skb_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Write raw \fIdata\fP blob into a special BPF perf event held by
|
||||
\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf
|
||||
event must have the following attributes: \fBPERF_SAMPLE_RAW\fP
|
||||
as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and
|
||||
\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&.
|
||||
.sp
|
||||
The \fIflags\fP are used to indicate the index in \fImap\fP for which
|
||||
the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&.
|
||||
Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP
|
||||
to indicate that the index of the current CPU core should be
|
||||
used.
|
||||
.sp
|
||||
The value to write, of \fIsize\fP, is passed through eBPF stack and
|
||||
pointed by \fIdata\fP\&.
|
||||
.sp
|
||||
\fIctx\fP is a pointer to in\-kernel struct sk_buff.
|
||||
.sp
|
||||
This helper is similar to \fBbpf_perf_event_output\fP() but
|
||||
restricted to raw_tracepoint bpf programs.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read_user(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Safely attempt to read \fIsize\fP bytes from user space address
|
||||
\fIunsafe_ptr\fP and store the data in \fIdst\fP\&.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read_kernel(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Safely attempt to read \fIsize\fP bytes from kernel space address
|
||||
\fIunsafe_ptr\fP and store the data in \fIdst\fP\&.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read_user_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Copy a NUL terminated string from an unsafe user address
|
||||
\fIunsafe_ptr\fP to \fIdst\fP\&. The \fIsize\fP should include the
|
||||
terminating NUL byte. In case the string length is smaller than
|
||||
\fIsize\fP, the target is not padded with further NUL bytes. If the
|
||||
string length is larger than \fIsize\fP, just \fIsize\fP\-1 bytes are
|
||||
copied and the last byte is set to NUL.
|
||||
.sp
|
||||
On success, the length of the copied string is returned. This
|
||||
makes this helper useful in tracing programs for reading
|
||||
strings, and more importantly to get its length at runtime. See
|
||||
the following snippet:
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
SEC("kprobe/sys_open")
|
||||
void bpf_sys_open(struct pt_regs *ctx)
|
||||
{
|
||||
char buf[PATHLEN]; // PATHLEN is defined to 256
|
||||
int res = bpf_probe_read_user_str(buf, sizeof(buf),
|
||||
ctx\->di);
|
||||
|
||||
// Consume buf, for example push it to
|
||||
// userspace via bpf_perf_event_output(); we
|
||||
// can use res (the string length) as event
|
||||
// size, after checking its boundaries.
|
||||
}
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
In comparison, using \fBbpf_probe_read_user()\fP helper here
|
||||
instead to read the string would require to estimate the length
|
||||
at compile time, and would often result in copying more memory
|
||||
than necessary.
|
||||
.sp
|
||||
Another useful use case is when parsing individual process
|
||||
arguments or individual environment variables navigating
|
||||
\fIcurrent\fP\fB\->mm\->arg_start\fP and \fIcurrent\fP\fB\->mm\->env_start\fP: using this helper and the return value,
|
||||
one can quickly iterate at the right offset of the memory area.
|
||||
.TP
|
||||
.B Return
|
||||
On success, the strictly positive length of the string,
|
||||
including the trailing NUL character. On error, a negative
|
||||
value.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_probe_read_kernel_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Copy a NUL terminated string from an unsafe kernel address \fIunsafe_ptr\fP
|
||||
to \fIdst\fP\&. Same semantics as with bpf_probe_read_user_str() apply.
|
||||
.TP
|
||||
.B Return
|
||||
On success, the strictly positive length of the string, including
|
||||
the trailing NUL character. On error, a negative value.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_tcp_send_ack(void *\fP\fItp\fP\fB, u32\fP \fIrcv_nxt\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Send out a tcp\-ack. \fItp\fP is the in\-kernel struct tcp_sock.
|
||||
\fIrcv_nxt\fP is the ack_seq to be sent out.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_send_signal_thread(u32\fP \fIsig\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Send signal \fIsig\fP to the thread corresponding to the current task.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success or successfully queued.
|
||||
.sp
|
||||
\fB\-EBUSY\fP if work queue under nmi is full.
|
||||
.sp
|
||||
\fB\-EINVAL\fP if \fIsig\fP is invalid.
|
||||
.sp
|
||||
\fB\-EPERM\fP if no permission to send the \fIsig\fP\&.
|
||||
.sp
|
||||
\fB\-EAGAIN\fP if bpf program can try again.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBu64 bpf_jiffies64(void)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Obtain the 64bit jiffies
|
||||
.TP
|
||||
.B Return
|
||||
The 64 bit jiffies
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_read_branch_records(struct bpf_perf_event_data *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
For an eBPF program attached to a perf event, retrieve the
|
||||
branch records (struct perf_branch_entry) associated to \fIctx\fP
|
||||
and store it in the buffer pointed by \fIbuf\fP up to size
|
||||
\fIsize\fP bytes.
|
||||
.TP
|
||||
.B Return
|
||||
On success, number of bytes written to \fIbuf\fP\&. On error, a
|
||||
negative value.
|
||||
.sp
|
||||
The \fIflags\fP can be set to \fBBPF_F_GET_BRANCH_RECORDS_SIZE\fP to
|
||||
instead return the number of bytes required to store all the
|
||||
branch entries. If this flag is set, \fIbuf\fP may be NULL.
|
||||
.sp
|
||||
\fB\-EINVAL\fP if arguments invalid or \fBsize\fP not a multiple
|
||||
of sizeof(struct perf_branch_entry).
|
||||
.sp
|
||||
\fB\-ENOENT\fP if architecture does not support branch records.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_get_ns_current_pid_tgid(u64\fP \fIdev\fP\fB, u64\fP \fIino\fP\fB, struct bpf_pidns_info *\fP\fInsdata\fP\fB, u32\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Returns 0 on success, values for \fIpid\fP and \fItgid\fP as seen from the current
|
||||
\fInamespace\fP will be returned in \fInsdata\fP\&.
|
||||
.sp
|
||||
On failure, the returned value is one of the following:
|
||||
.sp
|
||||
\fB\-EINVAL\fP if dev and inum supplied don\(aqt match dev_t and inode number
|
||||
with nsfs of current task, or if dev conversion to dev_t lost high bits.
|
||||
.sp
|
||||
\fB\-ENOENT\fP if pidns does not exists for the current task.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_xdp_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Write raw \fIdata\fP blob into a special BPF perf event held by
|
||||
\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf
|
||||
event must have the following attributes: \fBPERF_SAMPLE_RAW\fP
|
||||
as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and
|
||||
\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&.
|
||||
.sp
|
||||
The \fIflags\fP are used to indicate the index in \fImap\fP for which
|
||||
the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&.
|
||||
Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP
|
||||
to indicate that the index of the current CPU core should be
|
||||
used.
|
||||
.sp
|
||||
The value to write, of \fIsize\fP, is passed through eBPF stack and
|
||||
pointed by \fIdata\fP\&.
|
||||
.sp
|
||||
\fIctx\fP is a pointer to in\-kernel struct xdp_buff.
|
||||
.sp
|
||||
This helper is similar to \fBbpf_perf_eventoutput\fP() but
|
||||
restricted to raw_tracepoint bpf programs.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative error in case of failure.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBu64 bpf_get_netns_cookie(void *\fP\fIctx\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Retrieve the cookie (generated by the kernel) of the network
|
||||
namespace the input \fIctx\fP is associated with. The network
|
||||
namespace cookie remains stable for its lifetime and provides
|
||||
a global identifier that can be assumed unique. If \fIctx\fP is
|
||||
NULL, then the helper returns the cookie for the initial
|
||||
network namespace. The cookie itself is very similar to that
|
||||
of bpf_get_socket_cookie() helper, but for network namespaces
|
||||
instead of sockets.
|
||||
.TP
|
||||
.B Return
|
||||
A 8\-byte long opaque number.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBu64 bpf_get_current_ancestor_cgroup_id(int\fP \fIancestor_level\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Return id of cgroup v2 that is ancestor of the cgroup associated
|
||||
with the current task at the \fIancestor_level\fP\&. The root cgroup
|
||||
is at \fIancestor_level\fP zero and each step down the hierarchy
|
||||
increments the level. If \fIancestor_level\fP == level of cgroup
|
||||
associated with the current task, then return value will be the
|
||||
same as that of \fBbpf_get_current_cgroup_id\fP().
|
||||
.sp
|
||||
The helper is useful to implement policies based on cgroups
|
||||
that are upper in hierarchy than immediate cgroup associated
|
||||
with the current task.
|
||||
.sp
|
||||
The format of returned id and helper limitations are same as in
|
||||
\fBbpf_get_current_cgroup_id\fP().
|
||||
.TP
|
||||
.B Return
|
||||
The id is returned or 0 in case the id could not be retrieved.
|
||||
.UNINDENT
|
||||
.TP
|
||||
.B \fBint bpf_sk_assign(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP
|
||||
.INDENT 7.0
|
||||
.TP
|
||||
.B Description
|
||||
Assign the \fIsk\fP to the \fIskb\fP\&. When combined with appropriate
|
||||
routing configuration to receive the packet towards the socket,
|
||||
will cause \fIskb\fP to be delivered to the specified socket.
|
||||
Subsequent redirection of \fIskb\fP via \fBbpf_redirect\fP(),
|
||||
\fBbpf_clone_redirect\fP() or other methods outside of BPF may
|
||||
interfere with successful delivery to the socket.
|
||||
.sp
|
||||
This operation is only valid from TC ingress path.
|
||||
.sp
|
||||
The \fIflags\fP argument must be zero.
|
||||
.TP
|
||||
.B Return
|
||||
0 on success, or a negative errno in case of failure.
|
||||
.INDENT 7.0
|
||||
.IP \(bu 2
|
||||
\fB\-EINVAL\fP Unsupported flags specified.
|
||||
.IP \(bu 2
|
||||
\fB\-ENOENT\fP Socket is unavailable for assignment.
|
||||
.IP \(bu 2
|
||||
\fB\-ENETUNREACH\fP Socket is unreachable (wrong netns).
|
||||
.IP \(bu 2
|
||||
.INDENT 2.0
|
||||
.TP
|
||||
.B \fB\-EOPNOTSUPP\fP Unsupported operation, for example a
|
||||
call from outside of TC ingress.
|
||||
.UNINDENT
|
||||
.IP \(bu 2
|
||||
\fB\-ESOCKTNOSUPPORT\fP Socket type not supported (reuseport).
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.SH EXAMPLES
|
||||
.sp
|
||||
|
|
|
|||
Loading…
Reference in New Issue