Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ebpf-library/libbpf/userspace: Add pages maps and links #134

Merged
merged 1 commit into from
Mar 10, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .aspell.en.pws
Original file line number Diff line number Diff line change
Expand Up @@ -264,3 +264,4 @@ runqueue
dequeue
Dequeue
unregistration
unregister
53 changes: 53 additions & 0 deletions docs/ebpf-library/libbpf/userspace/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,59 @@
- [`bpf_program__set_log_buf`](bpf_program__set_log_buf.md)
- [`bpf_program__set_attach_target`](bpf_program__set_attach_target.md)
- [`bpf_program__expected_attach_type`](bpf_program__expected_attach_type.md)
- Link functions
- [`bpf_link__open`](bpf_link__open.md)
- [`bpf_link__fd`](bpf_link__fd.md)
- [`bpf_link__pin_path`](bpf_link__pin_path.md)
- [`bpf_link__pin`](bpf_link__pin.md)
- [`bpf_link__unpin`](bpf_link__unpin.md)
- [`bpf_link__update_program`](bpf_link__update_program.md)
- [`bpf_link__disconnect`](bpf_link__disconnect.md)
- [`bpf_link__detach`](bpf_link__detach.md)
- [`bpf_link__destroy`](bpf_link__destroy.md)
- [`bpf_link__update_map`](bpf_link__update_map.md)
- Map functions
- [`bpf_map__attach_struct_ops`](bpf_map__attach_struct_ops.md)
- [`bpf_map__set_autocreate`](bpf_map__set_autocreate.md)
- [`bpf_map__autocreate`](bpf_map__autocreate.md)
- [`bpf_map__set_autoattach`](bpf_map__set_autoattach.md)
- [`bpf_map__autoattach`](bpf_map__autoattach.md)
- [`bpf_map__fd`](bpf_map__fd.md)
- [`bpf_map__reuse_fd`](bpf_map__reuse_fd.md)
- [`bpf_map__name`](bpf_map__name.md)
- [`bpf_map__type`](bpf_map__type.md)
- [`bpf_map__set_type`](bpf_map__set_type.md)
- [`bpf_map__max_entries`](bpf_map__max_entries.md)
- [`bpf_map__set_max_entries`](bpf_map__set_max_entries.md)
- [`bpf_map__map_flags`](bpf_map__map_flags.md)
- [`bpf_map__set_map_flags`](bpf_map__set_map_flags.md)
- [`bpf_map__numa_node`](bpf_map__numa_node.md)
- [`bpf_map__set_numa_node`](bpf_map__set_numa_node.md)
- [`bpf_map__key_size`](bpf_map__key_size.md)
- [`bpf_map__set_key_size`](bpf_map__set_key_size.md)
- [`bpf_map__value_size`](bpf_map__value_size.md)
- [`bpf_map__set_value_size`](bpf_map__set_value_size.md)
- [`bpf_map__btf_key_type_id`](bpf_map__btf_key_type_id.md)
- [`bpf_map__btf_value_type_id`](bpf_map__btf_value_type_id.md)
- [`bpf_map__ifindex`](bpf_map__ifindex.md)
- [`bpf_map__set_ifindex`](bpf_map__set_ifindex.md)
- [`bpf_map__map_extra`](bpf_map__map_extra.md)
- [`bpf_map__set_map_extra`](bpf_map__set_map_extra.md)
- [`bpf_map__set_initial_value`](bpf_map__set_initial_value.md)
- [`bpf_map__initial_value`](bpf_map__initial_value.md)
- [`bpf_map__is_internal`](bpf_map__is_internal.md)
- [`bpf_map__set_pin_path`](bpf_map__set_pin_path.md)
- [`bpf_map__pin_path`](bpf_map__pin_path.md)
- [`bpf_map__is_pinned`](bpf_map__is_pinned.md)
- [`bpf_map__pin`](bpf_map__pin.md)
- [`bpf_map__unpin`](bpf_map__unpin.md)
- [`bpf_map__set_inner_map_fd`](bpf_map__set_inner_map_fd.md)
- [`bpf_map__inner_map`](bpf_map__inner_map.md)
- [`bpf_map__lookup_elem`](bpf_map__lookup_elem.md)
- [`bpf_map__update_elem`](bpf_map__update_elem.md)
- [`bpf_map__delete_elem`](bpf_map__delete_elem.md)
- [`bpf_map__lookup_and_delete_elem`](bpf_map__lookup_and_delete_elem.md)
- [`bpf_map__get_next_key`](bpf_map__get_next_key.md)
- Misc libbpf functions
- [`libbpf_major_version`](libbpf_major_version.md)
- [`libbpf_minor_version`](libbpf_minor_version.md)
Expand Down
32 changes: 32 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__destroy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: "Libbpf userspace function 'bpf_link__destroy'"
description: "This page documents the 'bpf_link__destroy' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__destroy`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.4](https://github.com/libbpf/libbpf/releases/tag/v0.0.4)
<!-- [/LIBBPF_TAG] -->

Destroy a BPF link.

## Definition

`#!c int bpf_link__destroy(struct bpf_link *link);`

**Parameters**

- `link`: Pointer to the BPF link.

**Return**

`0` on success, `-1` on error.

## Usage

Destroying a BPF link will detach it from the kernel and free all resources associated with it.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
28 changes: 28 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__detach.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "Libbpf userspace function 'bpf_link__detach'"
description: "This page documents the 'bpf_link__detach' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__detach`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.1.0](https://github.com/libbpf/libbpf/releases/tag/v0.1.0)
<!-- [/LIBBPF_TAG] -->

Detach a BPF link from the kernel.

## Definition

`#!c int bpf_link__detach(struct bpf_link *link);`

**Parameters**

- `link`: BPF link to detach

## Usage

This detaches the BPF link from the kernel but does delete the pin or free resources associated.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
28 changes: 28 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__disconnect.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "Libbpf userspace function 'bpf_link__disconnect'"
description: "This page documents the 'bpf_link__disconnect' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__disconnect`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.7](https://github.com/libbpf/libbpf/releases/tag/v0.0.7)
<!-- [/LIBBPF_TAG] -->

Release "ownership" of underlying BPF resource

## Definition

`#!c void bpf_link__disconnect(struct bpf_link *link);`

**Parameters**

- `link`: BPF link to disconnect

## Usage

Disconnected link, when destructed through [`bpf_link__destroy`](bpf_link__destroy.md) call won't attempt to detach/unregister that BPF resource. This is useful in situations where, say, attached BPF program has to outlive userspace program that attached it in the system. Depending on type of BPF program, though, there might be additional steps (like pinning BPF program in BPFFS) necessary to ensure exit of userspace program doesn't trigger automatic detachment and clean up inside the kernel.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__fd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__fd'"
description: "This page documents the 'bpf_link__fd' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__fd`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Get the file descriptor of a BPF link.

## Definition

`#!c int bpf_link__fd(const struct bpf_link *link);`

**Parameters**

- `link`: Pointer to the BPF link.

**Return**

File descriptor of the BPF link. `-1` on error.

## Usage

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__open.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__open'"
description: "This page documents the 'bpf_link__open' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__open`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Open a BPF link from a pin path.

## Definition

`#!c struct bpf_link *bpf_link__open(const char *path);`

**Parameters**

- `path`: Path to the BPF link pin.

**Return**

- `struct bpf_link *`: Pointer to the opened BPF link. `NULL` on error.

## Usage

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__pin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__pin'"
description: "This page documents the 'bpf_link__pin' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__pin`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Pins the BPF link to a file in the BPFFS specified by a path.

## Definition

`#!c int bpf_link__pin(struct bpf_link *link, const char *path);`

**Parameters**

- `link`: BPF link to pin, must already be loaded
- `path`: file path in a BPF file system

**Return**

`0`, on success; negative error code, otherwise

## Usage

This increments the links reference count, allowing it to stay loaded after the process which loaded it has exited.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__pin_path.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__pin_path'"
description: "This page documents the 'bpf_link__pin_path' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__pin_path`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Get the pin path of a BPF link.

## Definition

`#!c const char *bpf_link__pin_path(const struct bpf_link *link);`

**Parameters**

- `link`: Pointer to the BPF link.

**Return**

Pin path of the BPF link. `NULL` on error.

## Usage

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__unpin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__unpin'"
description: "This page documents the 'bpf_link__unpin' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__unpin`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Unpins the BPF link from a file in the BPFFS specified by a path. This decrements the links reference count.

## Definition

`#!c int bpf_link__unpin(struct bpf_link *link);`

**Parameters**

- `prog`: BPF program to unpin
- `path`: file path to the pin in a BPF file system

**Return**

`0`, on success; negative error code, otherwise

## Usage

The file pinning the BPF link can also be unlinked by a different process in which case this function will return an error.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
28 changes: 28 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__update_map.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "Libbpf userspace function 'bpf_link__update_map'"
description: "This page documents the 'bpf_link__update_map' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__update_map`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 1.2.0](https://github.com/libbpf/libbpf/releases/tag/v1.2.0)
<!-- [/LIBBPF_TAG] -->

Swap out the struct ops map of the link.

## Definition

`#!c int bpf_link__update_map(struct bpf_link *link, const struct bpf_map *map);`

**Parameters**

- `link`: Pointer to the BPF link.

## Usage

This function swaps out the [`BPF_MAP_TYPE_STRUCT_OPS`](../../../linux/map-type/BPF_MAP_TYPE_STRUCT_OPS.md) map that is linked to the kernel.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
33 changes: 33 additions & 0 deletions docs/ebpf-library/libbpf/userspace/bpf_link__update_program.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
title: "Libbpf userspace function 'bpf_link__update_program'"
description: "This page documents the 'bpf_link__update_program' libbpf userspace function, including its definition, usage, and examples."
---
# Libbpf userspace function `bpf_link__update_program`

<!-- [LIBBPF_TAG] -->
[:octicons-tag-24: 0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
<!-- [/LIBBPF_TAG] -->

Updates the BPF program associated with a BPF link.

## Definition

`#!c int bpf_link__update_program(struct bpf_link *link, struct bpf_program *prog);`

**Parameters**

- `link`: BPF link to update
- `prog`: BPF program to associate with the link

**Return**

`0`, on success; negative error code, otherwise

## Usage

This functions allows you to swap out the existing program associated with a BPF link with a new one. For cases where you do not want to miss any events that might occur between removing and re-creating a link.

### Example

!!! example "Docs could be improved"
This part of the docs is incomplete, contributions are very welcome
Loading