7e11886fff
Current sphinx/ contents are mostly WiP. Let's beat them into shape for publishing on ReadTheDocs. Integrate the API documentation generated with doxygen for the core C API and C++ bindings into sphinx using breathe. Update configure.ac to check for sphinx-build in addition to doxygen and make the main Makefile trigger a sphinx build on `make doc` (although the docs can also be generated without starting the build system by running: `sphinx-build ./docs/ docs/sphinx-output`). Move the introduction text from the main header into the relevant .rst file. Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where all the documentation now lives. Update .gitignore where needed. Reviewed-by: Vincent Fazio <vfazio@xes-inc.com> Link: https://lore.kernel.org/r/20250211-improve-docs-v4-12-dc56702c2ca8@linaro.org Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
2.3 KiB
libgpiod core API
This is the complete documentation of the public API made available to users of libgpiod.
The API is logically split into several sections. For each opaque data class, there's a set of functions for manipulating it. Together they can be thought of as objects and their methods in OOP parlance.
Note
General note on error handling: all functions exported by libgpiod
that can fail, set errno to one of the error values defined in errno.h
upon failure. The way of notifying the caller that an error occurred
varies between functions, but in general a function that returns an
int, returns -1 on error, while a function
returning a pointer indicates an error condition by returning a
NULL pointer. It's not practical to list all possible
error codes for every function as they propagate errors from the
underlying libc functions.
In general libgpiod functions are NULL-aware. For functions that are logically methods of data classes - ones that take a pointer to the object of that class as the first argument - passing a NULL-pointer will result in the program aborting the execution. For non-methods, init functions and methods that take a pointer as any of the subsequent arguments, the handling of a NULL-pointer depends on the implementation and may range from gracefully handling it, ignoring it or returning an error.
libgpiod is thread-aware but does not provide any further thread-safety guarantees. This requires the user to ensure that at most one thread may work with an object at any time. Sharing objects across threads is allowed if a suitable synchronization mechanism serializes the access. Different, standalone objects can safely be used concurrently.
Note
Most libgpiod objects are standalone. Exceptions - such as events allocated in buffers - exist and are noted in the documentation.
core_chips core_chip_info core_line_defs core_line_info core_line_watch core_line_settings core_line_config core_request_config core_line_request core_edge_event core_misc