Adding upstream version 1.3.1.upstream/1.3.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 93 insertions, 0 deletions

diff --git a/lib/libbpf/docs/api.rst b/lib/libbpf/docs/api.rst
new file mode 100644
index 0000000..7a8e709
--- /dev/null
+++ b/lib/libbpf/docs/api.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _api:
+
+.. toctree:: Table of Contents
+
+
+LIBBPF API
+==========
+
+Error Handling
+--------------
+
+When libbpf is used in "libbpf 1.0 mode", API functions can return errors in one of two ways.
+
+You can set "libbpf 1.0" mode with the following line:
+
+.. code-block::
+
+    libbpf_set_strict_mode(LIBBPF_STRICT_DIRECT_ERRS | LIBBPF_STRICT_CLEAN_PTRS);
+
+If the function returns an error code directly, it uses 0 to indicate success
+and a negative error code to indicate what caused the error. In this case the
+error code should be checked directly from the return, you do not need to check
+errno.
+
+For example:
+
+.. code-block::
+
+    err = some_libbpf_api_with_error_return(...);
+    if (err < 0) {
+        /* Handle error accordingly */
+    }
+
+If the function returns a pointer, it will return NULL to indicate there was
+an error. In this case errno should be checked for the error code.
+
+For example:
+
+.. code-block::
+
+    ptr = some_libbpf_api_returning_ptr();
+    if (!ptr) {
+        /* note no minus sign for EINVAL and E2BIG below */
+        if (errno == EINVAL) {
+           /* handle EINVAL error */
+        } else if (errno == E2BIG) {
+           /* handle E2BIG error */
+        }
+    }
+
+libbpf.h
+--------
+.. doxygenfile:: libbpf.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+bpf.h
+-----
+.. doxygenfile:: bpf.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+btf.h
+-----
+.. doxygenfile:: btf.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+xsk.h
+-----
+.. doxygenfile:: xsk.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+bpf_tracing.h
+-------------
+.. doxygenfile:: bpf_tracing.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+bpf_core_read.h
+---------------
+.. doxygenfile:: bpf_core_read.h
+   :project: libbpf
+   :sections: func define public-type enum
+
+bpf_endian.h
+------------
+.. doxygenfile:: bpf_endian.h
+   :project: libbpf
+   :sections: func define public-type enum