From 287d0d097b05c18e6aec86ecf8d89dd816a9dd31 Mon Sep 17 00:00:00 2001
From: grantseltzer <grantseltzer@gmail.com>
Date: Mon, 20 Dec 2021 11:59:56 -0500
Subject: [PATCH] Add documentation for error checking in API

Signed-off-by: grantseltzer <grantseltzer@gmail.com>
---
 docs/api.rst | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/docs/api.rst b/docs/api.rst
index 4ad9f34..ea181af 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -6,7 +6,49 @@
 
 
 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
 --------