Commit 2172fb80 authored by Stanislav Fomichev's avatar Stanislav Fomichev Committed by Alexei Starovoitov
Browse files

bpf: update bpf_{g,s}et_retval documentation 



* replace 'syscall' with 'upper layers', still mention that it's being
  exported via syscall errno
* describe what happens in set_retval(-EPERM) + return 1
* describe what happens with bind's 'return 3'

Acked-by: default avatarMartin KaFai Lau <kafai@fb.com>
Signed-off-by: default avatarStanislav Fomichev <sdf@google.com>
Link: https://lore.kernel.org/r/20220823222555.523590-5-sdf@google.com


Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent 8a67f2de

include/uapi/linux/bpf.h

+17 −5
Original line number Diff line number Diff line
@@ -5085,17 +5085,29 @@ union bpf_attr { 
 *

 * int bpf_get_retval(void)

 *	Description

 *		Get the syscall's return value that will be returned to userspace.

 *		Get the BPF program's return value that will be returned to the upper layers.

 *

 *		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's return value is returned to the userspace via errno.

 *	Return

 *		The syscall's return value.

 *		The BPF program's return value.

 *

 * int bpf_set_retval(int retval)

 *	Description

 *		Set the syscall's return value that will be returned to userspace.

 *		Set the BPF program's return value that will be returned to the upper layers.

 *

 *		This helper is currently supported by cgroup programs and only by the hooks

 *		where BPF program's return value is returned to the userspace via errno.

 *

 *		Note that there is the following corner case where the program exports an error

 *		via bpf_set_retval but signals success via 'return 1':

 *

 *			bpf_set_retval(-EPERM);

 *			return 1;

 *

 *		In this case, the BPF program's return value will use helper's -EPERM. This

 *		still holds true for cgroup/bind{4,6} which supports extra 'return 3' success case.

 *

 *		This helper is currently supported by cgroup programs only.

 *	Return

 *		0 on success, or a negative error in case of failure.

 *

tools/include/uapi/linux/bpf.h

+17 −5
Original line number Diff line number Diff line
@@ -5085,17 +5085,29 @@ union bpf_attr { 
 *

 * int bpf_get_retval(void)

 *	Description

 *		Get the syscall's return value that will be returned to userspace.

 *		Get the BPF program's return value that will be returned to the upper layers.

 *

 *		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's return value is returned to the userspace via errno.

 *	Return

 *		The syscall's return value.

 *		The BPF program's return value.

 *

 * int bpf_set_retval(int retval)

 *	Description

 *		Set the syscall's return value that will be returned to userspace.

 *		Set the BPF program's return value that will be returned to the upper layers.

 *

 *		This helper is currently supported by cgroup programs and only by the hooks

 *		where BPF program's return value is returned to the userspace via errno.

 *

 *		Note that there is the following corner case where the program exports an error

 *		via bpf_set_retval but signals success via 'return 1':

 *

 *			bpf_set_retval(-EPERM);

 *			return 1;

 *

 *		In this case, the BPF program's return value will use helper's -EPERM. This

 *		still holds true for cgroup/bind{4,6} which supports extra 'return 3' success case.

 *

 *		This helper is currently supported by cgroup programs only.

 *	Return

 *		0 on success, or a negative error in case of failure.

 *