{"id":13611871,"url":"https://github.com/tw4452852/zbpf","last_synced_at":"2026-01-26T07:16:03.569Z","repository":{"id":154085820,"uuid":"626195411","full_name":"tw4452852/zbpf","owner":"tw4452852","description":"Writing eBPF in Zig","archived":false,"fork":false,"pushed_at":"2025-12-17T10:03:04.000Z","size":5095,"stargazers_count":214,"open_issues_count":2,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-20T22:46:40.657Z","etag":null,"topics":["bpf","ebpf","tracing","zig"],"latest_commit_sha":null,"homepage":"https://tw4452852.github.io/zbpf/","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tw4452852.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-04-11T01:46:45.000Z","updated_at":"2025-12-17T10:03:08.000Z","dependencies_parsed_at":"2024-04-22T07:24:36.350Z","dependency_job_id":"99b4840e-1583-4b98-b865-a73004f15934","html_url":"https://github.com/tw4452852/zbpf","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tw4452852/zbpf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tw4452852%2Fzbpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tw4452852%2Fzbpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tw4452852%2Fzbpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tw4452852%2Fzbpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tw4452852","download_url":"https://codeload.github.com/tw4452852/zbpf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tw4452852%2Fzbpf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28769538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T06:37:25.426Z","status":"ssl_error","status_checked_at":"2026-01-26T06:37:23.039Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","ebpf","tracing","zig"],"created_at":"2024-08-01T19:02:16.637Z","updated_at":"2026-01-26T07:16:03.559Z","avatar_url":"https://github.com/tw4452852.png","language":"Zig","funding_links":[],"categories":["eBPF Workflow: Tools and Utilities","Zig","eBPF 工作流：工具和实用程序","Systems Programming"],"sub_categories":["zbpf","Kernel and Containers"],"readme":"# zbpf\nWriting eBPF in Zig. Thanks to Zig's comptime and BTF, we can equip eBPF with strong type system both at comptime and runtime!\n\n## Notable advantages when writing eBPF program with `zbpf`\n\n### Different available methods based on the type of program's context\n\nSuppose you want to trace the kernel function [path_listxattr](https://github.com/torvalds/linux/blob/7475e51b87969e01a6812eac713a1c8310372e8a/fs/xattr.c#L856-L857),\nand here's its prototype:\n\n```\nstatic ssize_t path_listxattr(const char __user *pathname, char __user *list,\n\t\t\t      size_t size, unsigned int lookup_flags)\n```\nAs you can see, it has 4 input parameters and return type is `ssize_t`.\nWith `ctx = bpf.Kprobe{.name = \"path_listxattr\"}.Ctx()`, you could retrieve\nthe input parameter with `ctx.arg0()`, `ctx.arg1()`, `ctx.arg2()` and `ctx.arg3()` respectively,\nand return value with `ctx.ret()`.\nthe type will be consistent with the above prototype. If you try to access a non-existing\nparameter, e.g. `ctx.arg4()`, you will get a compilation error.\n\nThis also applies to `syscall` with `bpf.Ksyscall`, `tracepoint` with `bpf.Tracepoint` and\n`fentry` with `bpf.Fentry`.\n\n### No more tedious error handling\n\nWhen writing in C, you always have to check the error conditions\n(the return value of the helper function, pointer validation, ...)\nWith `zbpf`, you won't care about the these cases, we handle it under the hood for you,\njust focus on the business logic.\n\nThe following are some examples:\n\n- `bpf.Map` takes care BPF map's `update` and `delete` error.\n- `bpf.PerfEventArray` handles event output failure.\n- `bpf.RingBuffer` also handles space reservation.\n- `bpf.Xdp` validates the pointer for you.\n\nIf some error happens, you could get all the information (file, line number, return value ...)\nyou need to debug in the kernel trace buffer:\n\n```\n~\u003e sudo bpftool prog tracelog\ntest-11717   [005] d..21 10990692.273976: bpf_trace_printk: error occur at src/bpf/map.zig:110 return -2\n```\n\n## How to use\n\n## Prerequisite\n\n- Make sure the linux kernel is built with `CONFIG_DEBUG_INFO_BTF=y`.\n\n## Build\n\n- Download the [lastest Zig](https://ziglang.org/download/).\n- Clone this repostory.\n- Build with `zig build zbpf -Dbpf=/path/to/your/bpf/prog.zig -Dmain=/path/to/your/main.zig`.\n\nFor cross-compiling, you could specify the target with `-Dtarget=\u003ctarget\u003e`,\nthe list of all supported targets could be retrieved by `zig targets`.\n\nMoreover, you could specify the target kernel with `-Dvmlinux=/path/to/vmlinux`\nto extract BTF from it, otherwise, current kernel's BTF will be used.\n\nThat's all! The generated binary is located at `./zig-out/bin/zbpf`,\nfeel free to run it on your target machine.\n\nHere's the [Documentations generated by Zig's AutoDoc](https://tw4452852.github.io/zbpf)\nfor you reference.\n\n## Tools/trace\n\n`trace` is a tool built on top of `zbpf` framework to trace kernel functions, syscalls and userspace functions.\nIt's heavily inspired by [retsnoop](https://github.com/anakryiko/retsnoop).\nOne improvement I made (which is also what I feel when using retsnoop) is that `trace` support\nshow parameters according its type (thanks to the Zig type system).\nThis is very helpful when debugging linux kernel and userspace program.\nFor more details, you could check the implementation: [BPF side](https://github.com/tw4452852/zbpf/blob/main/src/tools/trace/trace.bpf.zig)\nand [Host side](https://github.com/tw4452852/zbpf/blob/main/src/tools/trace/trace.zig).\n\nYou could specify the kernel functions you want to trace with: `zig build trace -Dkprobe=\u003ckernel_function_name\u003e -Dkprobe=...`\nAnd for system calls: `zig build trace -Dsyscall=\u003csyscall_name\u003e -Dsyscall=...`.\nOr userspace function: `zig build trace -Duprobe=/path/to/binary[function_name]`.\nMoreover, if you also want to capture the function's arguments, append the argument specifier, something like this:\n`-Dkprobe=\u003ckernel_function_name\u003e:arg0,arg1...`, it also supports access to the deeper field if the argument is a pointer to a struct:\n`-Dkprobe=\u003ckernel_function_name\u003e:arg0.field1.field0`.\nYou could even control how the argument is shown by using all the supported specifier by Zig's `std.fmt`, something like this:\n`-Dkprobe=\u003ckernel_function_name\u003e:arg0.field1.field0/x` will show `arg0.field1.field0` in hexadecimal notation.\nCapturing call stack is also supported, append keyword `stack`, for example `-Dkprobe=\u003ckernel_function_name\u003e:arg0,stack`.\n\nAnd here's a quick demo:\n\n[![asciicast](https://asciinema.org/a/675689.svg)](https://asciinema.org/a/675689)\n\nFor reference:\n- Syscalls: https://tw4452852.github.io/zbpf/#vmlinux.kernel_syscalls\n- Kernel functions: https://tw4452852.github.io/zbpf/#vmlinux.kernel_funcs\n\nWant to use your local specific linux kernel? No problem, you could set up the documentation locally with:\n```\nzig build docs [-Dvmlinux=/path/your/vmlinux]\n```\nThen browse the generated page which is located at `./zig-out/docs/index.html`.\nSearch for `vmlinux.kernel_syscalls` and `vmlinux.kernel_funcs` for syscalls and kernel functions respectively.\n\n## Samples\n\nFor each supported feature, we have the corresponding unit test.\nYou could find them under `samples/` (BPF side) and `src/tests` (Host side).\nBuild it with `zig build test -Dtest=\u003cname\u003e` and run it with `sudo zig-out/bin/test`.\n\nName | BPF side | Host side\n--- | --- | ---\nexit | [source](samples/exit.zig) | [source](src/tests/exit.zig)\npanic | [source](samples/panic.zig) | [source](src/tests/panic.zig)\ntrace_printk | [source](samples/trace_printk.zig) | [source](src/tests/trace_printk.zig)\narray | [source](samples/array.zig) | [source](src/tests/array.zig)\nhash | [source](samples/hash.zig) | [source](src/tests/hash.zig)\nperf_event | [source](samples/perf_event.zig) | [source](src/tests/perf_event.zig)\nringbuf | [source](samples/ringbuf.zig) | [source](src/tests/ringbuf.zig)\ntracepoint | [source](samples/tracepoint.zig) | [source](src/tests/tracepoint.zig)\niterator | [source](samples/iterator.zig) | [source](src/tests/iterator.zig)\nfentry | [source](samples/fentry.zig) | [source](src/tests/fentry.zig)\nkprobe | [source](samples/kprobe.zig) | [source](src/tests/kprobe.zig)\nkmulprobe | [source](samples/kmulprobe.zig) | [source](src/tests/kmulprobe.zig)\nxdp ping | [source](samples/xdp_ping.zig) | [source](src/tests/xdp_ping.zig)\nkfunc | [source](samples/kfunc.zig) | [source](src/tests/kfunc.zig)\nstack_trace | [source](samples/stacktrace.zig) | [source](src/tests/stacktrace.zig)\nuprobe | [source](samples/uprobe.zig) | [source](src/tests/uprobe.zig)\ntc_ingress | [source](samples/tc_ingress.zig) | [source](src/tests/tc_ingress.zig)\nlpm_trie | [source](samples/lpm_trie.zig) | [source](src/tests/lpm_trie.zig)\n\n**Have fun!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftw4452852%2Fzbpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftw4452852%2Fzbpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftw4452852%2Fzbpf/lists"}