go.mod: github.com/cilium/ebpf v0.5.0

full diff: https://github.com/cilium/ebpf/compare/v0.4.0...v0.5.0 Breaking changes ------------------------------------------ All LoadPinned*() functions now take LoadPinOptions to control loader behaviour. Simply pass nil to load with default options. - LoadPinnedMap() - LoadPinnedProgram() - LoadPinnedCgroup() - LoadPinnedIter() - LoadPinnedRawLink() - LoadPinnedNetNs() Bug fixes ------------------------------------------ - Program.IsPinned() now behaves correctly on maps loaded from bpffs - Map.Pin() no longer clobbers the destination file if it already exists Features ------------------------------------------ - Attaching to k(ret)probes and tracepoints can now be done with link.Kprobe(), link.Kretprobe() and link.Tracepoint() - Programs of type Kprobe automatically get their KernelVersion fields populated by detecting the kernel version at runtime - MapOptions now contains a LoadPinOptions - ProgSpec now contains a Flags field, adding support for BPF_F_SLEEPABLE - Made BTF map loader more flexible by looping over Vars in a BTF data section - Pinned Maps and Programs can now be loaded from bpffs in read-or write-only mode - Added golangci-lint project configuration, running in CI Examples ------------------------------------------ kprobe and tracepoint examples updated to use the new link.Kprobe() and link.Tracepoint() API There is now an example for how to attach eBPF programs to uprobes Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2026-07-11 06:03:57 +08:00 · 2021-04-13 12:54:47 +02:00
parent 2d38476c96
commit d15c7bb0f2
22 changed files with 465 additions and 164 deletions
@@ -0,0 +1,29 @@
+---
+issues:
+  exclude-rules:
+    # syscall param structs will have unused fields in Go code.
+    - path: syscall.*.go
+      linters:
+        - structcheck
+
+linters:
+  disable-all: true
+  enable:
+    - deadcode
+    - errcheck
+    - goimports
+    - gosimple
+    - govet
+    - ineffassign
+    - misspell
+    - staticcheck
+    - structcheck
+    - typecheck
+    - unused
+    - varcheck
+
+    # Could be enabled later:
+    # - gocyclo
+    # - prealloc
+    # - maligned
+    # - gosec
@@ -13,7 +13,7 @@ be used in long running processes.
 * [perf](https://pkg.go.dev/github.com/cilium/ebpf/perf) allows reading from a
  `PERF_EVENT_ARRAY`
 * [cmd/bpf2go](https://pkg.go.dev/github.com/cilium/ebpf/cmd/bpf2go) allows
-  embedding eBPF in Go
+  compiling and embedding eBPF programs in Go code

 The library is maintained by [Cloudflare](https://www.cloudflare.com) and
 [Cilium](https://www.cilium.io). Feel free to
@@ -25,6 +25,14 @@ The library is maintained by [Cloudflare](https://www.cloudflare.com) and
 The package is production ready, but **the API is explicitly unstable right
 now**. Expect to update your code if you want to follow along.

+## Getting Started
+
+A small collection of Go and eBPF programs that serve as examples for building
+your own tools can be found under [examples/](examples/).
+
+Contributions are highly encouraged, as they highlight certain use cases of
+eBPF and the library, and help shape the future of the project.
+
 ## Requirements

 * A version of Go that is [supported by
@@ -7,7 +7,7 @@ type BuiltinFunc int32

 // eBPF built-in functions
 //
-// You can renegerate this list using the following gawk script:
+// You can regenerate this list using the following gawk script:
 //
 //    /FN\(.+\),/ {
 //      match($1, /\((.+)\)/, r)
@@ -337,7 +337,7 @@ func (insns Instructions) ReferenceOffsets() map[string][]int {
 // You can control indentation of symbols by
 // specifying a width. Setting a precision controls the indentation of
 // instructions.
-// The default character is a tab, which can be overriden by specifying
+// The default character is a tab, which can be overridden by specifying
 // the ' ' space flag.
 func (insns Instructions) Format(f fmt.State, c rune) {
 	if c != 's' && c != 'v' {
@@ -382,8 +382,6 @@ func (insns Instructions) Format(f fmt.State, c rune) {
 		}
 		fmt.Fprintf(f, "%s%*d: %v\n", indent, offsetWidth, iter.Offset, iter.Ins)
 	}
-
-	return
 }

 // Marshal encodes a BPF program into the kernel format.
@@ -272,11 +272,12 @@ func (ec *elfCode) loadPrograms() (map[string]*ProgramSpec, error) {
 			return nil, fmt.Errorf("program %s: %w", funcSym.Name, err)
 		}

-		progType, attachType, attachTo := getProgType(sec.Name)
+		progType, attachType, progFlags, attachTo := getProgType(sec.Name)

 		spec := &ProgramSpec{
 			Name:          funcSym.Name,
 			Type:          progType,
+			Flags:         progFlags,
 			AttachType:    attachType,
 			AttachTo:      attachTo,
 			License:       ec.license,
@@ -533,28 +534,25 @@ func (ec *elfCode) loadBTFMaps(maps map[string]*MapSpec) error {
 			return fmt.Errorf("missing BTF")
 		}

-		if len(sec.symbols) == 0 {
-			return fmt.Errorf("section %v: no symbols", sec.Name)
-		}
-
 		_, err := io.Copy(internal.DiscardZeroes{}, bufio.NewReader(sec.Open()))
 		if err != nil {
 			return fmt.Errorf("section %v: initializing BTF map definitions: %w", sec.Name, internal.ErrNotSupported)
 		}

-		for _, sym := range sec.symbols {
-			name := sym.Name
-			if maps[name] != nil {
-				return fmt.Errorf("section %v: map %v already exists", sec.Name, sym)
-			}
+		var ds btf.Datasec
+		if err := ec.btf.FindType(sec.Name, &ds); err != nil {
+			return fmt.Errorf("cannot find section '%s' in BTF: %w", sec.Name, err)
+		}

-			// A global Var is created by declaring a struct with a 'structure variable',
-			// as is common in eBPF C to declare eBPF maps. For example,
-			// `struct { ... } map_name ...;` emits a global variable `map_name`
-			// with the type of said struct (which can be anonymous).
-			var v btf.Var
-			if err := ec.btf.FindType(name, &v); err != nil {
-				return fmt.Errorf("cannot find global variable '%s' in BTF: %w", name, err)
+		for _, vs := range ds.Vars {
+			v, ok := vs.Type.(*btf.Var)
+			if !ok {
+				return fmt.Errorf("section %v: unexpected type %s", sec.Name, vs.Type)
+			}
+			name := string(v.Name)
+
+			if maps[name] != nil {
+				return fmt.Errorf("section %v: map %s already exists", sec.Name, name)
 			}

 			mapStruct, ok := v.Type.(*btf.Struct)
@@ -834,56 +832,61 @@ func (ec *elfCode) loadDataSections(maps map[string]*MapSpec) error {
 	return nil
 }

-func getProgType(sectionName string) (ProgramType, AttachType, string) {
+func getProgType(sectionName string) (ProgramType, AttachType, uint32, string) {
 	types := map[string]struct {
 		progType   ProgramType
 		attachType AttachType
+		progFlags  uint32
 	}{
 		// From https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/bpf/libbpf.c
-		"socket":                {SocketFilter, AttachNone},
-		"seccomp":               {SocketFilter, AttachNone},
-		"kprobe/":               {Kprobe, AttachNone},
-		"uprobe/":               {Kprobe, AttachNone},
-		"kretprobe/":            {Kprobe, AttachNone},
-		"uretprobe/":            {Kprobe, AttachNone},
-		"tracepoint/":           {TracePoint, AttachNone},
-		"raw_tracepoint/":       {RawTracepoint, AttachNone},
-		"xdp":                   {XDP, AttachNone},
-		"perf_event":            {PerfEvent, AttachNone},
-		"lwt_in":                {LWTIn, AttachNone},
-		"lwt_out":               {LWTOut, AttachNone},
-		"lwt_xmit":              {LWTXmit, AttachNone},
-		"lwt_seg6local":         {LWTSeg6Local, AttachNone},
-		"sockops":               {SockOps, AttachCGroupSockOps},
-		"sk_skb/stream_parser":  {SkSKB, AttachSkSKBStreamParser},
-		"sk_skb/stream_verdict": {SkSKB, AttachSkSKBStreamParser},
-		"sk_msg":                {SkMsg, AttachSkSKBStreamVerdict},
-		"lirc_mode2":            {LircMode2, AttachLircMode2},
-		"flow_dissector":        {FlowDissector, AttachFlowDissector},
-		"iter/":                 {Tracing, AttachTraceIter},
-		"sk_lookup/":            {SkLookup, AttachSkLookup},
-		"lsm/":                  {LSM, AttachLSMMac},
+		"socket":                {SocketFilter, AttachNone, 0},
+		"seccomp":               {SocketFilter, AttachNone, 0},
+		"kprobe/":               {Kprobe, AttachNone, 0},
+		"uprobe/":               {Kprobe, AttachNone, 0},
+		"kretprobe/":            {Kprobe, AttachNone, 0},
+		"uretprobe/":            {Kprobe, AttachNone, 0},
+		"tracepoint/":           {TracePoint, AttachNone, 0},
+		"raw_tracepoint/":       {RawTracepoint, AttachNone, 0},
+		"xdp":                   {XDP, AttachNone, 0},
+		"perf_event":            {PerfEvent, AttachNone, 0},
+		"lwt_in":                {LWTIn, AttachNone, 0},
+		"lwt_out":               {LWTOut, AttachNone, 0},
+		"lwt_xmit":              {LWTXmit, AttachNone, 0},
+		"lwt_seg6local":         {LWTSeg6Local, AttachNone, 0},
+		"sockops":               {SockOps, AttachCGroupSockOps, 0},
+		"sk_skb/stream_parser":  {SkSKB, AttachSkSKBStreamParser, 0},
+		"sk_skb/stream_verdict": {SkSKB, AttachSkSKBStreamParser, 0},
+		"sk_msg":                {SkMsg, AttachSkSKBStreamVerdict, 0},
+		"lirc_mode2":            {LircMode2, AttachLircMode2, 0},
+		"flow_dissector":        {FlowDissector, AttachFlowDissector, 0},
+		"iter/":                 {Tracing, AttachTraceIter, 0},
+		"fentry.s/":             {Tracing, AttachTraceFEntry, unix.BPF_F_SLEEPABLE},
+		"fmod_ret.s/":           {Tracing, AttachModifyReturn, unix.BPF_F_SLEEPABLE},
+		"fexit.s/":              {Tracing, AttachTraceFExit, unix.BPF_F_SLEEPABLE},
+		"sk_lookup/":            {SkLookup, AttachSkLookup, 0},
+		"lsm/":                  {LSM, AttachLSMMac, 0},
+		"lsm.s/":                {LSM, AttachLSMMac, unix.BPF_F_SLEEPABLE},

-		"cgroup_skb/ingress": {CGroupSKB, AttachCGroupInetIngress},
-		"cgroup_skb/egress":  {CGroupSKB, AttachCGroupInetEgress},
-		"cgroup/dev":         {CGroupDevice, AttachCGroupDevice},
-		"cgroup/skb":         {CGroupSKB, AttachNone},
-		"cgroup/sock":        {CGroupSock, AttachCGroupInetSockCreate},
-		"cgroup/post_bind4":  {CGroupSock, AttachCGroupInet4PostBind},
-		"cgroup/post_bind6":  {CGroupSock, AttachCGroupInet6PostBind},
-		"cgroup/bind4":       {CGroupSockAddr, AttachCGroupInet4Bind},
-		"cgroup/bind6":       {CGroupSockAddr, AttachCGroupInet6Bind},
-		"cgroup/connect4":    {CGroupSockAddr, AttachCGroupInet4Connect},
-		"cgroup/connect6":    {CGroupSockAddr, AttachCGroupInet6Connect},
-		"cgroup/sendmsg4":    {CGroupSockAddr, AttachCGroupUDP4Sendmsg},
-		"cgroup/sendmsg6":    {CGroupSockAddr, AttachCGroupUDP6Sendmsg},
-		"cgroup/recvmsg4":    {CGroupSockAddr, AttachCGroupUDP4Recvmsg},
-		"cgroup/recvmsg6":    {CGroupSockAddr, AttachCGroupUDP6Recvmsg},
-		"cgroup/sysctl":      {CGroupSysctl, AttachCGroupSysctl},
-		"cgroup/getsockopt":  {CGroupSockopt, AttachCGroupGetsockopt},
-		"cgroup/setsockopt":  {CGroupSockopt, AttachCGroupSetsockopt},
-		"classifier":         {SchedCLS, AttachNone},
-		"action":             {SchedACT, AttachNone},
+		"cgroup_skb/ingress": {CGroupSKB, AttachCGroupInetIngress, 0},
+		"cgroup_skb/egress":  {CGroupSKB, AttachCGroupInetEgress, 0},
+		"cgroup/dev":         {CGroupDevice, AttachCGroupDevice, 0},
+		"cgroup/skb":         {CGroupSKB, AttachNone, 0},
+		"cgroup/sock":        {CGroupSock, AttachCGroupInetSockCreate, 0},
+		"cgroup/post_bind4":  {CGroupSock, AttachCGroupInet4PostBind, 0},
+		"cgroup/post_bind6":  {CGroupSock, AttachCGroupInet6PostBind, 0},
+		"cgroup/bind4":       {CGroupSockAddr, AttachCGroupInet4Bind, 0},
+		"cgroup/bind6":       {CGroupSockAddr, AttachCGroupInet6Bind, 0},
+		"cgroup/connect4":    {CGroupSockAddr, AttachCGroupInet4Connect, 0},
+		"cgroup/connect6":    {CGroupSockAddr, AttachCGroupInet6Connect, 0},
+		"cgroup/sendmsg4":    {CGroupSockAddr, AttachCGroupUDP4Sendmsg, 0},
+		"cgroup/sendmsg6":    {CGroupSockAddr, AttachCGroupUDP6Sendmsg, 0},
+		"cgroup/recvmsg4":    {CGroupSockAddr, AttachCGroupUDP4Recvmsg, 0},
+		"cgroup/recvmsg6":    {CGroupSockAddr, AttachCGroupUDP6Recvmsg, 0},
+		"cgroup/sysctl":      {CGroupSysctl, AttachCGroupSysctl, 0},
+		"cgroup/getsockopt":  {CGroupSockopt, AttachCGroupGetsockopt, 0},
+		"cgroup/setsockopt":  {CGroupSockopt, AttachCGroupSetsockopt, 0},
+		"classifier":         {SchedCLS, AttachNone, 0},
+		"action":             {SchedACT, AttachNone, 0},
 	}

 	for prefix, t := range types {
@@ -892,13 +895,13 @@ func getProgType(sectionName string) (ProgramType, AttachType, string) {
 		}

 		if !strings.HasSuffix(prefix, "/") {
-			return t.progType, t.attachType, ""
+			return t.progType, t.attachType, t.progFlags, ""
 		}

-		return t.progType, t.attachType, sectionName[len(prefix):]
+		return t.progType, t.attachType, t.progFlags, sectionName[len(prefix):]
 	}

-	return UnspecifiedProgram, AttachNone, ""
+	return UnspecifiedProgram, AttachNone, 0, ""
 }

 func (ec *elfCode) loadRelocations(sec *elf.Section, symbols []elf.Symbol) (map[uint64]elf.Symbol, error) {
@@ -31,12 +31,14 @@ const (
 	kindDatasec
 )

+// btfFuncLinkage describes BTF function linkage metadata.
 type btfFuncLinkage uint8

+// Equivalent of enum btf_func_linkage.
 const (
 	linkageStatic btfFuncLinkage = iota
 	linkageGlobal
-	linkageExtern
+	// linkageExtern // Currently unused in libbpf.
 )

 const (
@@ -98,41 +98,3 @@ func FeatureTest(name, version string, fn FeatureTestFn) func() error {
 		return ft.result
 	}
 }
-
-// A Version in the form Major.Minor.Patch.
-type Version [3]uint16
-
-// NewVersion creates a version from a string like "Major.Minor.Patch".
-//
-// Patch is optional.
-func NewVersion(ver string) (Version, error) {
-	var major, minor, patch uint16
-	n, _ := fmt.Sscanf(ver, "%d.%d.%d", &major, &minor, &patch)
-	if n < 2 {
-		return Version{}, fmt.Errorf("invalid version: %s", ver)
-	}
-	return Version{major, minor, patch}, nil
-}
-
-func (v Version) String() string {
-	if v[2] == 0 {
-		return fmt.Sprintf("v%d.%d", v[0], v[1])
-	}
-	return fmt.Sprintf("v%d.%d.%d", v[0], v[1], v[2])
-}
-
-// Less returns true if the version is less than another version.
-func (v Version) Less(other Version) bool {
-	for i, a := range v {
-		if a == other[i] {
-			continue
-		}
-		return a < other[i]
-	}
-	return false
-}
-
-// Unspecified returns true if the version is all zero.
-func (v Version) Unspecified() bool {
-	return v[0] == 0 && v[1] == 0 && v[2] == 0
-}
@@ -1,36 +1,38 @@
-package ebpf
+package internal

 import (
 	"errors"
 	"fmt"
 	"os"

-	"github.com/cilium/ebpf/internal"
+	"github.com/cilium/ebpf/internal/unix"
 )

-func pin(currentPath, newPath string, fd *internal.FD) error {
+func Pin(currentPath, newPath string, fd *FD) error {
 	if newPath == "" {
 		return errors.New("given pinning path cannot be empty")
 	}
-	if currentPath == "" {
-		return internal.BPFObjPin(newPath, fd)
-	}
 	if currentPath == newPath {
 		return nil
 	}
+	if currentPath == "" {
+		return BPFObjPin(newPath, fd)
+	}
 	var err error
-	// Object is now moved to the new pinning path.
-	if err = os.Rename(currentPath, newPath); err == nil {
+	// Renameat2 is used instead of os.Rename to disallow the new path replacing
+	// an existing path.
+	if err = unix.Renameat2(unix.AT_FDCWD, currentPath, unix.AT_FDCWD, newPath, unix.RENAME_NOREPLACE); err == nil {
+		// Object is now moved to the new pinning path.
 		return nil
 	}
 	if !os.IsNotExist(err) {
 		return fmt.Errorf("unable to move pinned object to new path %v: %w", newPath, err)
 	}
 	// Internal state not in sync with the file system so let's fix it.
-	return internal.BPFObjPin(newPath, fd)
+	return BPFObjPin(newPath, fd)
 }

-func unpin(pinnedPath string) error {
+func Unpin(pinnedPath string) error {
 	if pinnedPath == "" {
 		return nil
 	}
@@ -1,6 +1,10 @@
 package internal

-import "unsafe"
+import (
+	"unsafe"
+
+	"github.com/cilium/ebpf/internal/unix"
+)

 // NewPointer creates a 64-bit pointer from an unsafe Pointer.
 func NewPointer(ptr unsafe.Pointer) Pointer {
@@ -22,9 +26,10 @@ func NewStringPointer(str string) Pointer {
 		return Pointer{}
 	}

-	// The kernel expects strings to be zero terminated
-	buf := make([]byte, len(str)+1)
-	copy(buf, str)
+	p, err := unix.BytePtrFromString(str)
+	if err != nil {
+		return Pointer{}
+	}

-	return Pointer{ptr: unsafe.Pointer(&buf[0])}
+	return Pointer{ptr: unsafe.Pointer(p)}
 }
@@ -140,9 +140,10 @@ func BPFObjPin(fileName string, fd *FD) error {
 }

 // BPFObjGet wraps BPF_OBJ_GET.
-func BPFObjGet(fileName string) (*FD, error) {
+func BPFObjGet(fileName string, flags uint32) (*FD, error) {
 	attr := bpfObjAttr{
-		fileName: NewStringPointer(fileName),
+		fileName:  NewStringPointer(fileName),
+		fileFlags: flags,
 	}
 	ptr, err := BPF(BPF_OBJ_GET, unsafe.Pointer(&attr), unsafe.Sizeof(attr))
 	if err != nil {
@@ -26,8 +26,11 @@ const (
 	EBADF                    = linux.EBADF
 	BPF_F_NO_PREALLOC        = linux.BPF_F_NO_PREALLOC
 	BPF_F_NUMA_NODE          = linux.BPF_F_NUMA_NODE
+	BPF_F_RDONLY             = linux.BPF_F_RDONLY
+	BPF_F_WRONLY             = linux.BPF_F_WRONLY
 	BPF_F_RDONLY_PROG        = linux.BPF_F_RDONLY_PROG
 	BPF_F_WRONLY_PROG        = linux.BPF_F_WRONLY_PROG
+	BPF_F_SLEEPABLE          = linux.BPF_F_SLEEPABLE
 	BPF_OBJ_NAME_LEN         = linux.BPF_OBJ_NAME_LEN
 	BPF_TAG_SIZE             = linux.BPF_TAG_SIZE
 	SYS_BPF                  = linux.SYS_BPF
@@ -40,13 +43,21 @@ const (
 	PROT_WRITE               = linux.PROT_WRITE
 	MAP_SHARED               = linux.MAP_SHARED
 	PERF_TYPE_SOFTWARE       = linux.PERF_TYPE_SOFTWARE
+	PERF_TYPE_TRACEPOINT     = linux.PERF_TYPE_TRACEPOINT
 	PERF_COUNT_SW_BPF_OUTPUT = linux.PERF_COUNT_SW_BPF_OUTPUT
+	PERF_EVENT_IOC_DISABLE   = linux.PERF_EVENT_IOC_DISABLE
+	PERF_EVENT_IOC_ENABLE    = linux.PERF_EVENT_IOC_ENABLE
+	PERF_EVENT_IOC_SET_BPF   = linux.PERF_EVENT_IOC_SET_BPF
 	PerfBitWatermark         = linux.PerfBitWatermark
 	PERF_SAMPLE_RAW          = linux.PERF_SAMPLE_RAW
 	PERF_FLAG_FD_CLOEXEC     = linux.PERF_FLAG_FD_CLOEXEC
 	RLIM_INFINITY            = linux.RLIM_INFINITY
 	RLIMIT_MEMLOCK           = linux.RLIMIT_MEMLOCK
 	BPF_STATS_RUN_TIME       = linux.BPF_STATS_RUN_TIME
+	PERF_RECORD_LOST         = linux.PERF_RECORD_LOST
+	PERF_RECORD_SAMPLE       = linux.PERF_RECORD_SAMPLE
+	AT_FDCWD                 = linux.AT_FDCWD
+	RENAME_NOREPLACE         = linux.RENAME_NOREPLACE
 )

 // Statfs_t is a wrapper
@@ -70,6 +81,11 @@ func FcntlInt(fd uintptr, cmd, arg int) (int, error) {
 	return linux.FcntlInt(fd, cmd, arg)
 }

+// IoctlSetInt is a wrapper
+func IoctlSetInt(fd int, req uint, value int) error {
+	return linux.IoctlSetInt(fd, req, value)
+}
+
 // Statfs is a wrapper
 func Statfs(path string, buf *Statfs_t) (err error) {
 	return linux.Statfs(path, buf)
@@ -157,6 +173,21 @@ func Tgkill(tgid int, tid int, sig syscall.Signal) (err error) {
 	return linux.Tgkill(tgid, tid, sig)
 }

+// BytePtrFromString is a wrapper
+func BytePtrFromString(s string) (*byte, error) {
+	return linux.BytePtrFromString(s)
+}
+
+// ByteSliceToString is a wrapper
+func ByteSliceToString(s []byte) string {
+	return linux.ByteSliceToString(s)
+}
+
+// Renameat2 is a wrapper
+func Renameat2(olddirfd int, oldpath string, newdirfd int, newpath string, flags uint) error {
+	return linux.Renameat2(olddirfd, oldpath, newdirfd, newpath, flags)
+}
+
 func KernelRelease() (string, error) {
 	var uname Utsname
 	err := Uname(&uname)
@@ -26,8 +26,11 @@ const (

 	BPF_F_NO_PREALLOC        = 0
 	BPF_F_NUMA_NODE          = 0
+	BPF_F_RDONLY             = 0
+	BPF_F_WRONLY             = 0
 	BPF_F_RDONLY_PROG        = 0
 	BPF_F_WRONLY_PROG        = 0
+	BPF_F_SLEEPABLE          = 0
 	BPF_OBJ_NAME_LEN         = 0x10
 	BPF_TAG_SIZE             = 0x8
 	SYS_BPF                  = 321
@@ -41,13 +44,21 @@ const (
 	PROT_WRITE               = 0x2
 	MAP_SHARED               = 0x1
 	PERF_TYPE_SOFTWARE       = 0x1
+	PERF_TYPE_TRACEPOINT     = 0
 	PERF_COUNT_SW_BPF_OUTPUT = 0xa
+	PERF_EVENT_IOC_DISABLE   = 0
+	PERF_EVENT_IOC_ENABLE    = 0
+	PERF_EVENT_IOC_SET_BPF   = 0
 	PerfBitWatermark         = 0x4000
 	PERF_SAMPLE_RAW          = 0x400
 	PERF_FLAG_FD_CLOEXEC     = 0x8
 	RLIM_INFINITY            = 0x7fffffffffffffff
 	RLIMIT_MEMLOCK           = 8
 	BPF_STATS_RUN_TIME       = 0
+	PERF_RECORD_LOST         = 2
+	PERF_RECORD_SAMPLE       = 9
+	AT_FDCWD                 = -0x2
+	RENAME_NOREPLACE         = 0x1
 )

 // Statfs_t is a wrapper
@@ -87,6 +98,11 @@ func FcntlInt(fd uintptr, cmd, arg int) (int, error) {
 	return -1, errNonLinux
 }

+// IoctlSetInt is a wrapper
+func IoctlSetInt(fd int, req uint, value int) error {
+	return errNonLinux
+}
+
 // Statfs is a wrapper
 func Statfs(path string, buf *Statfs_t) error {
 	return errNonLinux
@@ -201,6 +217,7 @@ func PerfEventOpen(attr *PerfEventAttr, pid int, cpu int, groupFd int, flags int
 // Utsname is a wrapper
 type Utsname struct {
 	Release [65]byte
+	Version [65]byte
 }

 // Uname is a wrapper
@@ -223,6 +240,21 @@ func Tgkill(tgid int, tid int, sig syscall.Signal) (err error) {
 	return errNonLinux
 }

+// BytePtrFromString is a wrapper
+func BytePtrFromString(s string) (*byte, error) {
+	return nil, errNonLinux
+}
+
+// ByteSliceToString is a wrapper
+func ByteSliceToString(s []byte) string {
+	return ""
+}
+
+// Renameat2 is a wrapper
+func Renameat2(olddirfd int, oldpath string, newdirfd int, newpath string, flags uint) error {
+	return errNonLinux
+}
+
 func KernelRelease() (string, error) {
 	return "", errNonLinux
 }
@@ -0,0 +1,163 @@
+package internal
+
+import (
+	"fmt"
+	"io/ioutil"
+	"regexp"
+	"sync"
+
+	"github.com/cilium/ebpf/internal/unix"
+)
+
+const (
+	// Version constant used in ELF binaries indicating that the loader needs to
+	// substitute the eBPF program's version with the value of the kernel's
+	// KERNEL_VERSION compile-time macro. Used for compatibility with BCC, gobpf
+	// and RedSift.
+	MagicKernelVersion = 0xFFFFFFFE
+)
+
+var (
+	// Match between one and three decimals separated by dots, with the last
+	// segment (patch level) being optional on some kernels.
+	// The x.y.z string must appear at the start of a string or right after
+	// whitespace to prevent sequences like 'x.y.z-a.b.c' from matching 'a.b.c'.
+	rgxKernelVersion = regexp.MustCompile(`(?:\A|\s)\d{1,3}\.\d{1,3}(?:\.\d{1,3})?`)
+
+	kernelVersion = struct {
+		once    sync.Once
+		version Version
+		err     error
+	}{}
+)
+
+// A Version in the form Major.Minor.Patch.
+type Version [3]uint16
+
+// NewVersion creates a version from a string like "Major.Minor.Patch".
+//
+// Patch is optional.
+func NewVersion(ver string) (Version, error) {
+	var major, minor, patch uint16
+	n, _ := fmt.Sscanf(ver, "%d.%d.%d", &major, &minor, &patch)
+	if n < 2 {
+		return Version{}, fmt.Errorf("invalid version: %s", ver)
+	}
+	return Version{major, minor, patch}, nil
+}
+
+func (v Version) String() string {
+	if v[2] == 0 {
+		return fmt.Sprintf("v%d.%d", v[0], v[1])
+	}
+	return fmt.Sprintf("v%d.%d.%d", v[0], v[1], v[2])
+}
+
+// Less returns true if the version is less than another version.
+func (v Version) Less(other Version) bool {
+	for i, a := range v {
+		if a == other[i] {
+			continue
+		}
+		return a < other[i]
+	}
+	return false
+}
+
+// Unspecified returns true if the version is all zero.
+func (v Version) Unspecified() bool {
+	return v[0] == 0 && v[1] == 0 && v[2] == 0
+}
+
+// Kernel implements the kernel's KERNEL_VERSION macro from linux/version.h.
+// It represents the kernel version and patch level as a single value.
+func (v Version) Kernel() uint32 {
+
+	// Kernels 4.4 and 4.9 have their SUBLEVEL clamped to 255 to avoid
+	// overflowing into PATCHLEVEL.
+	// See kernel commit 9b82f13e7ef3 ("kbuild: clamp SUBLEVEL to 255").
+	s := v[2]
+	if s > 255 {
+		s = 255
+	}
+
+	// Truncate members to uint8 to prevent them from spilling over into
+	// each other when overflowing 8 bits.
+	return uint32(uint8(v[0]))<<16 | uint32(uint8(v[1]))<<8 | uint32(uint8(s))
+}
+
+// KernelVersion returns the version of the currently running kernel.
+func KernelVersion() (Version, error) {
+	kernelVersion.once.Do(func() {
+		kernelVersion.version, kernelVersion.err = detectKernelVersion()
+	})
+
+	if kernelVersion.err != nil {
+		return Version{}, kernelVersion.err
+	}
+	return kernelVersion.version, nil
+}
+
+// detectKernelVersion returns the version of the running kernel. It scans the
+// following sources in order: /proc/version_signature, uname -v, uname -r.
+// In each of those locations, the last-appearing x.y(.z) value is selected
+// for parsing. The first location that yields a usable version number is
+// returned.
+func detectKernelVersion() (Version, error) {
+
+	// Try reading /proc/version_signature for Ubuntu compatibility.
+	// Example format: Ubuntu 4.15.0-91.92-generic 4.15.18
+	// This method exists in the kernel itself, see d18acd15c
+	// ("perf tools: Fix kernel version error in ubuntu").
+	if pvs, err := ioutil.ReadFile("/proc/version_signature"); err == nil {
+		// If /proc/version_signature exists, failing to parse it is an error.
+		// It only exists on Ubuntu, where the real patch level is not obtainable
+		// through any other method.
+		v, err := findKernelVersion(string(pvs))
+		if err != nil {
+			return Version{}, err
+		}
+		return v, nil
+	}
+
+	var uname unix.Utsname
+	if err := unix.Uname(&uname); err != nil {
+		return Version{}, fmt.Errorf("calling uname: %w", err)
+	}
+
+	// Debian puts the version including the patch level in uname.Version.
+	// It is not an error if there's no version number in uname.Version,
+	// as most distributions don't use it. Parsing can continue on uname.Release.
+	// Example format: #1 SMP Debian 4.19.37-5+deb10u2 (2019-08-08)
+	if v, err := findKernelVersion(unix.ByteSliceToString(uname.Version[:])); err == nil {
+		return v, nil
+	}
+
+	// Most other distributions have the full kernel version including patch
+	// level in uname.Release.
+	// Example format: 4.19.0-5-amd64, 5.5.10-arch1-1
+	v, err := findKernelVersion(unix.ByteSliceToString(uname.Release[:]))
+	if err != nil {
+		return Version{}, err
+	}
+
+	return v, nil
+}
+
+// findKernelVersion matches s against rgxKernelVersion and parses the result
+// into a Version. If s contains multiple matches, the last entry is selected.
+func findKernelVersion(s string) (Version, error) {
+	m := rgxKernelVersion.FindAllString(s, -1)
+	if m == nil {
+		return Version{}, fmt.Errorf("no kernel version in string: %s", s)
+	}
+	// Pick the last match of the string in case there are multiple.
+	s = m[len(m)-1]
+
+	v, err := NewVersion(s)
+	if err != nil {
+		return Version{}, fmt.Errorf("parsing version string %s: %w", s, err)
+	}
+
+	return v, nil
+}
@@ -25,7 +25,8 @@ type MapOptions struct {
 	// The base path to pin maps in if requested via PinByName.
 	// Existing maps will be re-used if they are compatible, otherwise an
 	// error is returned.
-	PinPath string
+	PinPath        string
+	LoadPinOptions LoadPinOptions
 }

 // MapID represents the unique ID of an eBPF map
@@ -40,7 +41,10 @@ type MapSpec struct {
 	KeySize    uint32
 	ValueSize  uint32
 	MaxEntries uint32
-	Flags      uint32
+
+	// Flags is passed to the kernel and specifies additional map
+	// creation attributes.
+	Flags uint32

 	// Automatically pin and load a map from MapOptions.PinPath.
 	// Generates an error if an existing pinned map is incompatible with the MapSpec.
@@ -174,23 +178,30 @@ func NewMapWithOptions(spec *MapSpec, opts MapOptions) (*Map, error) {
 	return newMapWithOptions(spec, opts, btfs)
 }

-func newMapWithOptions(spec *MapSpec, opts MapOptions, btfs btfHandleCache) (*Map, error) {
+func newMapWithOptions(spec *MapSpec, opts MapOptions, btfs btfHandleCache) (_ *Map, err error) {
+	closeOnError := func(c io.Closer) {
+		if err != nil {
+			c.Close()
+		}
+	}
+
 	switch spec.Pinning {
 	case PinByName:
 		if spec.Name == "" || opts.PinPath == "" {
 			return nil, fmt.Errorf("pin by name: missing Name or PinPath")
 		}

-		m, err := LoadPinnedMap(filepath.Join(opts.PinPath, spec.Name))
+		path := filepath.Join(opts.PinPath, spec.Name)
+		m, err := LoadPinnedMap(path, &opts.LoadPinOptions)
 		if errors.Is(err, unix.ENOENT) {
 			break
 		}
 		if err != nil {
-			return nil, fmt.Errorf("load pinned map: %s", err)
+			return nil, fmt.Errorf("load pinned map: %w", err)
 		}
+		defer closeOnError(m)

 		if err := spec.checkCompatibility(m); err != nil {
-			m.Close()
 			return nil, fmt.Errorf("use pinned map %s: %s", spec.Name, err)
 		}

@@ -226,10 +237,11 @@ func newMapWithOptions(spec *MapSpec, opts MapOptions, btfs btfHandleCache) (*Ma
 	if err != nil {
 		return nil, err
 	}
+	defer closeOnError(m)

 	if spec.Pinning == PinByName {
-		if err := m.Pin(filepath.Join(opts.PinPath, spec.Name)); err != nil {
-			m.Close()
+		path := filepath.Join(opts.PinPath, spec.Name)
+		if err := m.Pin(path); err != nil {
 			return nil, fmt.Errorf("pin map: %s", err)
 		}
 	}
@@ -805,12 +817,13 @@ func (m *Map) Clone() (*Map, error) {
 // Pin persists the map on the BPF virtual file system past the lifetime of
 // the process that created it .
 //
-// Calling Pin on a previously pinned map will override the path.
+// Calling Pin on a previously pinned map will overwrite the path, except when
+// the new path already exists. Re-pinning across filesystems is not supported.
 // You can Clone a map to pin it to a different path.
 //
 // This requires bpffs to be mounted above fileName. See https://docs.cilium.io/en/k8s-doc/admin/#admin-mount-bpffs
 func (m *Map) Pin(fileName string) error {
-	if err := pin(m.pinnedPath, fileName, m.fd); err != nil {
+	if err := internal.Pin(m.pinnedPath, fileName, m.fd); err != nil {
 		return err
 	}
 	m.pinnedPath = fileName
@@ -823,7 +836,7 @@ func (m *Map) Pin(fileName string) error {
 //
 // Unpinning an unpinned Map returns nil.
 func (m *Map) Unpin() error {
-	if err := unpin(m.pinnedPath); err != nil {
+	if err := internal.Unpin(m.pinnedPath); err != nil {
 		return err
 	}
 	m.pinnedPath = ""
@@ -832,10 +845,7 @@ func (m *Map) Unpin() error {

 // IsPinned returns true if the map has a non-empty pinned path.
 func (m *Map) IsPinned() bool {
-	if m.pinnedPath == "" {
-		return false
-	}
-	return true
+	return m.pinnedPath != ""
 }

 // Freeze prevents a map to be modified from user space.
@@ -937,7 +947,9 @@ func (m *Map) unmarshalValue(value interface{}, buf []byte) error {
 			return err
 		}

-		(*value).Close()
+		// The caller might close the map externally, so ignore errors.
+		_ = (*value).Close()
+
 		*value = other
 		return nil

@@ -957,7 +969,9 @@ func (m *Map) unmarshalValue(value interface{}, buf []byte) error {
 			return err
 		}

-		(*value).Close()
+		// The caller might close the program externally, so ignore errors.
+		_ = (*value).Close()
+
 		*value = other
 		return nil

@@ -971,9 +985,9 @@ func (m *Map) unmarshalValue(value interface{}, buf []byte) error {
 	return unmarshalBytes(value, buf)
 }

-// LoadPinnedMap load a Map from a BPF file.
-func LoadPinnedMap(fileName string) (*Map, error) {
-	fd, err := internal.BPFObjGet(fileName)
+// LoadPinnedMap loads a Map from a BPF file.
+func LoadPinnedMap(fileName string, opts *LoadPinOptions) (*Map, error) {
+	fd, err := internal.BPFObjGet(fileName, opts.Marshal())
 	if err != nil {
 		return nil, err
 	}
@@ -84,7 +84,9 @@ func makeBuffer(dst interface{}, length int) (internal.Pointer, []byte) {
 func unmarshalBytes(data interface{}, buf []byte) error {
 	switch value := data.(type) {
 	case unsafe.Pointer:
-		sh := &reflect.SliceHeader{
+		// This could be solved in Go 1.17 by unsafe.Slice instead. (https://github.com/golang/go/issues/19367)
+		// We could opt for removing unsafe.Pointer support in the lib as well.
+		sh := &reflect.SliceHeader{ //nolint:govet
 			Data: uintptr(value),
 			Len:  len(buf),
 			Cap:  len(buf),
@@ -55,16 +55,19 @@ type ProgramSpec struct {
 	// depends on Type and AttachType.
 	AttachTo     string
 	Instructions asm.Instructions
-
+	// Flags is passed to the kernel and specifies additional program
+	// load attributes.
+	Flags uint32
 	// License of the program. Some helpers are only available if
 	// the license is deemed compatible with the GPL.
 	//
 	// See https://www.kernel.org/doc/html/latest/process/license-rules.html#id1
 	License string

-	// Version used by tracing programs.
+	// Version used by Kprobe programs.
 	//
-	// Deprecated: superseded by BTF.
+	// Deprecated on kernels 5.0 and later. Leave empty to let the library
+	// detect this value automatically.
 	KernelVersion uint32

 	// The BTF associated with this program. Changing Instructions
@@ -141,6 +144,19 @@ func newProgramWithOptions(spec *ProgramSpec, opts ProgramOptions, btfs btfHandl
 		return nil, fmt.Errorf("can't load %s program on %s", spec.ByteOrder, internal.NativeEndian)
 	}

+	// Kernels before 5.0 (6c4fc209fcf9 "bpf: remove useless version check for prog load")
+	// require the version field to be set to the value of the KERNEL_VERSION
+	// macro for kprobe-type programs.
+	// Overwrite Kprobe program version if set to zero or the magic version constant.
+	kv := spec.KernelVersion
+	if spec.Type == Kprobe && (kv == 0 || kv == internal.MagicKernelVersion) {
+		v, err := internal.KernelVersion()
+		if err != nil {
+			return nil, fmt.Errorf("detecting kernel version: %w", err)
+		}
+		kv = v.Kernel()
+	}
+
 	insns := make(asm.Instructions, len(spec.Instructions))
 	copy(insns, spec.Instructions)

@@ -158,11 +174,12 @@ func newProgramWithOptions(spec *ProgramSpec, opts ProgramOptions, btfs btfHandl
 	insCount := uint32(len(bytecode) / asm.InstructionSize)
 	attr := &bpfProgLoadAttr{
 		progType:           spec.Type,
+		progFlags:          spec.Flags,
 		expectedAttachType: spec.AttachType,
 		insCount:           insCount,
 		instructions:       internal.NewSlicePointer(bytecode),
 		license:            internal.NewStringPointer(spec.License),
-		kernelVersion:      spec.KernelVersion,
+		kernelVersion:      kv,
 	}

 	if haveObjName() == nil {
@@ -345,9 +362,12 @@ func (p *Program) Clone() (*Program, error) {
 // Pin persists the Program on the BPF virtual file system past the lifetime of
 // the process that created it
 //
+// Calling Pin on a previously pinned program will overwrite the path, except when
+// the new path already exists. Re-pinning across filesystems is not supported.
+//
 // This requires bpffs to be mounted above fileName. See https://docs.cilium.io/en/k8s-doc/admin/#admin-mount-bpffs
 func (p *Program) Pin(fileName string) error {
-	if err := pin(p.pinnedPath, fileName, p.fd); err != nil {
+	if err := internal.Pin(p.pinnedPath, fileName, p.fd); err != nil {
 		return err
 	}
 	p.pinnedPath = fileName
@@ -360,7 +380,7 @@ func (p *Program) Pin(fileName string) error {
 //
 // Unpinning an unpinned Program returns nil.
 func (p *Program) Unpin() error {
-	if err := unpin(p.pinnedPath); err != nil {
+	if err := internal.Unpin(p.pinnedPath); err != nil {
 		return err
 	}
 	p.pinnedPath = ""
@@ -369,10 +389,7 @@ func (p *Program) Unpin() error {

 // IsPinned returns true if the Program has a non-empty pinned path.
 func (p *Program) IsPinned() bool {
-	if p.pinnedPath == "" {
-		return false
-	}
-	return true
+	return p.pinnedPath != ""
 }

 // Close unloads the program from the kernel.
@@ -597,8 +614,8 @@ func (p *Program) Detach(fd int, typ AttachType, flags AttachFlags) error {
 // LoadPinnedProgram loads a Program from a BPF file.
 //
 // Requires at least Linux 4.11.
-func LoadPinnedProgram(fileName string) (*Program, error) {
-	fd, err := internal.BPFObjGet(fileName)
+func LoadPinnedProgram(fileName string, opts *LoadPinOptions) (*Program, error) {
+	fd, err := internal.BPFObjGet(fileName, opts.Marshal())
 	if err != nil {
 		return nil, err
 	}
@@ -609,7 +626,7 @@ func LoadPinnedProgram(fileName string) (*Program, error) {
 		return nil, fmt.Errorf("info for %s: %w", fileName, err)
 	}

-	return &Program{"", fd, filepath.Base(fileName), "", info.Type}, nil
+	return &Program{"", fd, filepath.Base(fileName), fileName, info.Type}, nil
 }

 // SanitizeName replaces all invalid characters in name with replacement.
@@ -9,6 +9,7 @@ if [[ "${1:-}" = "--in-vm" ]]; then
  shift

  mount -t bpf bpf /sys/fs/bpf
+  mount -t tracefs tracefs /sys/kernel/debug/tracing
  export CGO_ENABLED=0
  export GOFLAGS=-mod=readonly
  export GOPATH=/run/go-path
@@ -383,7 +383,7 @@ func wrapMapError(err error) error {
 		return ErrNotSupported
 	}

-	return errors.New(err.Error())
+	return err
 }

 func bpfMapFreeze(m *internal.FD) error {
@@ -1,5 +1,9 @@
 package ebpf

+import (
+	"github.com/cilium/ebpf/internal/unix"
+)
+
 //go:generate stringer -output types_string.go -type=MapType,ProgramType,AttachType,PinType

 // MapType indicates the type map structure
@@ -202,6 +206,33 @@ const (
 	PinByName
 )

+// LoadPinOptions control how a pinned object is loaded.
+type LoadPinOptions struct {
+	// Request a read-only or write-only object. The default is a read-write
+	// object. Only one of the flags may be set.
+	ReadOnly  bool
+	WriteOnly bool
+
+	// Raw flags for the syscall. Other fields of this struct take precedence.
+	Flags uint32
+}
+
+// Marshal returns a value suitable for BPF_OBJ_GET syscall file_flags parameter.
+func (lpo *LoadPinOptions) Marshal() uint32 {
+	if lpo == nil {
+		return 0
+	}
+
+	flags := lpo.Flags
+	if lpo.ReadOnly {
+		flags |= unix.BPF_F_RDONLY
+	}
+	if lpo.WriteOnly {
+		flags |= unix.BPF_F_WRONLY
+	}
+	return flags
+}
+
 // BatchOptions batch map operations options
 //
 // Mirrors libbpf struct bpf_map_batch_opts