libbpf: Add doc comments in libbpf.h

	unsigned int map_flags;

};

/*

 * The 'struct bpf_map' in include/linux/bpf.h is internal to the kernel,

 * so no need to worry about a name clash.

/**

 * @brief **bpf_object__find_map_by_name()** returns BPF map of

 * the given name, if it exists within the passed BPF object

 * @param obj BPF object

 * @param name name of the BPF map

 * @return BPF map instance, if such map exists within the BPF object;

 * or NULL otherwise.

 */

LIBBPF_API struct bpf_map *

bpf_object__find_map_by_name(const struct bpf_object *obj, const char *name);

LIBBPF_API struct bpf_map *

bpf_map__prev(const struct bpf_map *map, const struct bpf_object *obj);

/* get/set map FD */

/**

 * @brief **bpf_map__fd()** gets the file descriptor of the passed

 * BPF map

 * @param map the BPF map instance

 * @return the file descriptor; or -EINVAL in case of an error

 */

LIBBPF_API int bpf_map__fd(const struct bpf_map *map);

LIBBPF_API int bpf_map__reuse_fd(struct bpf_map *map, int fd);

/* get map definition */

					  const void *data, size_t size);

LIBBPF_API const void *bpf_map__initial_value(struct bpf_map *map, size_t *psize);

LIBBPF_API bool bpf_map__is_offload_neutral(const struct bpf_map *map);

/**

 * @brief **bpf_map__is_internal()** tells the caller whether or not the

 * passed map is a special map created by libbpf automatically for things like

 * global variables, __ksym externs, Kconfig values, etc

 * @param map the bpf_map

 * @return true, if the map is an internal map; false, otherwise

 */

LIBBPF_API bool bpf_map__is_internal(const struct bpf_map *map);

LIBBPF_API int bpf_map__set_pin_path(struct bpf_map *map, const char *path);

LIBBPF_API const char *bpf_map__get_pin_path(const struct bpf_map *map);

LIBBPF_API int bpf_map__set_inner_map_fd(struct bpf_map *map, int fd);

LIBBPF_API struct bpf_map *bpf_map__inner_map(struct bpf_map *map);

/**

 * @brief **libbpf_get_error()** extracts the error code from the passed

 * pointer

 * @param ptr pointer returned from libbpf API function

 * @return error code; or 0 if no error occured

 *

 * Many libbpf API functions which return pointers have logic to encode error

 * codes as pointers, and do not return NULL. Meaning **libbpf_get_error()**

 * should be used on the return value from these functions immediately after

 * calling the API function, with no intervening calls that could clobber the

 * `errno` variable. Consult the individual functions documentation to verify

 * if this logic applies should be used.

 *

 * For these API functions, if `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)`

 * is enabled, NULL is returned on error instead.

 *

 * If ptr is NULL, then errno should be already set by the failing

 * API, because libbpf never returns NULL on success and it now always

 * sets errno on error.

 *

 * Example usage:

 *

 *   struct perf_buffer *pb;

 *

 *   pb = perf_buffer__new(bpf_map__fd(obj->maps.events), PERF_BUFFER_PAGES, &opts);

 *   err = libbpf_get_error(pb);

 *   if (err) {

 *	  pb = NULL;

 *	  fprintf(stderr, "failed to open perf buffer: %d\n", err);

 *	  goto cleanup;

 *   }

 */

LIBBPF_API long libbpf_get_error(const void *ptr);

struct bpf_prog_load_attr {

LIBBPF_API void

bpf_program__bpil_offs_to_addr(struct bpf_prog_info_linear *info_linear);

/*

 * A helper function to get the number of possible CPUs before looking up

 * per-CPU maps. Negative errno is returned on failure.

/**

 * @brief **libbpf_num_possible_cpus()** is a helper function to get the

 * number of possible CPUs that the host kernel supports and expects.

 * @return number of possible CPUs; or error code on failure

 *

 * Example usage:

 *

 *     }

 *     long values[ncpus];

 *     bpf_map_lookup_elem(per_cpu_map_fd, key, values);

 *

 */

LIBBPF_API int libbpf_num_possible_cpus(void);