Skip to content

Libbpf userspace function bpf_program__attach_ksyscall

1.0.0

Attaches a BPF program to kernel syscall handler of a specified syscall. Optionally it's possible to request to install retprobe that will be triggered at syscall exit. It's also possible to associate BPF cookie (though options).

Definition

struct bpf_link * bpf_program__attach_ksyscall(const struct bpf_program *prog, const char *syscall_name, const struct bpf_ksyscall_opts *opts);

Parameters

  • prog: BPF program to attach
  • syscall_name: Symbolic name of the syscall (e.g., "bpf")
  • opts: Additional options (see struct bpf_ksyscall_opts)

Return

Reference to the newly created BPF link; or NULL is returned on error, error code is stored in errno

struct bpf_ksyscall_opts

struct bpf_ksyscall_opts {
    /* size of this struct, for forward/backward compatibility */
    size_t sz;
    __u64 bpf_cookie;
    bool retprobe;
    size_t :0;
};

1.0.0

Custom user-provided value fetchable through bpf_get_attach_cookie. This allows you to write one program, load it once, and then attach it to multiple perf events with different bpf_cookie values, allowing the program to detect which event it is attached to.

retprobe

1.0.0

Attach as return probe. If set to true, the BPF program will be triggered at syscall exit.

Usage

Libbpf automatically will determine correct full kernel function name, which depending on system architecture and kernel version/configuration could be of the form __<arch>_sys_<syscall> or __se_sys_<syscall>, and will attach specified program using kprobe/kretprobe mechanism.

bpf_program__attach_ksyscall is an API counterpart of declarative SEC("ksyscall/<syscall>") annotation of BPF programs.

At the moment SEC("ksyscall") and bpf_program__attach_ksyscall() do not handle all the calling convention quirks for mmap(), clone() and compat syscalls. It also only attaches to "native" syscall interfaces. If host system supports compat syscalls or defines 32-bit syscalls in 64-bit kernel, such syscall interfaces won't be attached to by libbpf.

These limitations may or may not change in the future. Therefore it is recommended to use SEC("kprobe") for these syscalls or if working with compat and 32-bit interfaces is required.

Example

Docs could be improved

This part of the docs is incomplete, contributions are very welcome