KFunc bpf_ksock_acquire
Acquire a reference to a BPF kernel socket.
Definition
Acquires a reference to a BPF kernel socket context. The context returned by this function must either be stored in a map as a kptr, or freed with bpf_ksock_release.
ks: The BPF kernel socket context to acquire. Must be a trusted or RCU protected pointer, for example a kptr loaded from a map value while holding the RCU read lock (see KF_RCU).
Returns
Returns ks on success, or NULL if a reference could not be acquired because the last reference to the context has already been released.
Signature
struct bpf_ksock *bpf_ksock_acquire(struct bpf_ksock *ks)
Note
This kfunc returns a pointer to a refcounted object. The verifier will then ensure that the pointer to the object
is eventually released using a release kfunc, or transferred to a map using a referenced kptr
(by invoking bpf_kptr_xchg). If not, the verifier fails the
loading of the BPF program until no lingering references remain in all possible explored states of the program.
Note
The pointer returned by the kfunc may be NULL. Hence, it forces the user to do a NULL check on the pointer returned from the kfunc before making use of it (dereferencing or passing to another helper).
Usage
This kfunc is used to acquire a reference to a BPF kernel socket context that was previously created with bpf_ksock_create and stored in a map as a kptr. This allows programs to use the socket stored in the map, for example to send data with bpf_ksock_send, without removing it from the map. It also allows you to add the same context to multiple values in the same map or to multiple maps.
A typical pattern is to take the RCU read lock with bpf_rcu_read_lock, read the kptr from the map value, acquire a reference with this kfunc and then release the RCU read lock with bpf_rcu_read_unlock. The acquired reference remains valid after the RCU read lock is released.
Warning
This kfunc can't be used by LSM programs attached to the socket_sendmsg hook. Since bpf_ksock_send invokes this hook, such programs could cause infinite recursion. The verifier rejects such programs with the message calling kernel function bpf_ksock_acquire is not allowed.
Program types
The following program types can make use of this kfunc:
Example
See bpf_ksock_create for an example.