Stop bolding function signatures in the documentation
A signature containing char** argv closed its own bold emphasis early, which garbled the dpm_execute and dpm_module_execute entries and the text following them. Signatures are plain code spans now, so a signature carrying a double asterisk renders like every other one.
This commit is contained in:
@@ -51,64 +51,64 @@ All functions are extern "C". All returned strings are owned by the library (or
|
||||
|
||||
### Context Lifecycle
|
||||
|
||||
**`dpm_ctx* dpm_open(const dpm_open_overrides* overrides)`**
|
||||
`dpm_ctx* dpm_open(const dpm_open_overrides* overrides)`
|
||||
Creates a context. Reads configuration from `/etc/dpm/conf.d/` (or the config directory named in overrides), resolves the module path (overrides take precedence over config, config over the built-in default), and initializes logging per configuration. Performs no module loading. Returns NULL only on allocation failure or an unreadable/invalid explicit override; a missing config directory is not an error — defaults apply. `overrides` may be NULL, and may specify: config directory, module path, target root (for chroot/image/sysroot operation), and log level. Multiple simultaneous contexts with different roots are legal.
|
||||
|
||||
**`void dpm_close(dpm_ctx* ctx)`**
|
||||
`void dpm_close(dpm_ctx* ctx)`
|
||||
Releases the context: unloads every module handle it issued, closes log targets, frees all memory owned by the context. All handles and strings obtained through the context are invalid after this call. NULL is a no-op.
|
||||
|
||||
### Module Acquisition
|
||||
|
||||
**`dpm_module* dpm_require(dpm_ctx* ctx, const char* name)`**
|
||||
`dpm_module* dpm_require(dpm_ctx* ctx, const char* name)`
|
||||
Resolves the module `name` in the module path and runs the full load-time validation sequence (see Load-Time Enforcement) if the module is not already loaded in this context. On success returns a module handle owned by the context (repeated calls return the same handle — modules are loaded at most once per context). On failure returns NULL and records the precise reason: not found, or validation step failed with the step and detail. No version criterion is applied here; compatibility is the caller's to determine from the reported version.
|
||||
|
||||
**`int dpm_module_info_of(dpm_ctx* ctx, dpm_module* mod, dpm_module_info* out)`**
|
||||
`int dpm_module_info_of(dpm_ctx* ctx, dpm_module* mod, dpm_module_info* out)`
|
||||
Fills `out` with the loaded module's name, version, and description exactly as they were read at load (string pointers valid until context close). This is how a consumer obtains the version it will judge. The library attaches no meaning to the values. Returns 0 on success, nonzero if the module cannot be reported on.
|
||||
|
||||
**`int dpm_execute(dpm_ctx* ctx, dpm_module* mod, const char* command, int argc, char** argv)`**
|
||||
`int dpm_execute(dpm_ctx* ctx, dpm_module* mod, const char* command, int argc, char** argv)`
|
||||
Dispatch: invokes the module's `dpm_module_execute` with the context, `command`, and the argument vector. Returns the module's return value verbatim (0 = success). The library adds nothing to the call besides delivery; argument semantics beyond "argv[0] is the command" are the module's to define.
|
||||
|
||||
This is the entire path into module code. A caller addresses a module by name and a capability by command string, so it holds no compile-time knowledge of the module it is calling — no headers, no struct layouts, no symbols. That is what allows a module to be developed, built, and tested with no peer present.
|
||||
|
||||
### Enumeration
|
||||
|
||||
**`dpm_cursor* dpm_list_modules(dpm_ctx* ctx)`**
|
||||
`dpm_cursor* dpm_list_modules(dpm_ctx* ctx)`
|
||||
Scans the module path and returns a cursor over all *valid* modules (each candidate .so is validated on first scan; failures are logged and excluded). Returns NULL on an unreadable module path.
|
||||
|
||||
**`int dpm_cursor_next(dpm_cursor* cur, dpm_module_info* out)`**
|
||||
`int dpm_cursor_next(dpm_cursor* cur, dpm_module_info* out)`
|
||||
Advances the cursor. Fills `out` with the next module's name, version, and description (string pointers valid until context close). Returns 0 and fills `out` while entries remain; returns nonzero at end.
|
||||
|
||||
**`void dpm_cursor_free(dpm_cursor* cur)`**
|
||||
`void dpm_cursor_free(dpm_cursor* cur)`
|
||||
Releases the cursor. NULL is a no-op.
|
||||
|
||||
### Services (Available to Modules and External Consumers Alike)
|
||||
|
||||
**`const char* dpm_core_version(void)`**
|
||||
`const char* dpm_core_version(void)`
|
||||
Returns the library version as a static X.Y.Z string. Callable without a context.
|
||||
|
||||
**`const char* dpm_config_get(dpm_ctx* ctx, const char* module, const char* section, const char* key)`**
|
||||
`const char* dpm_config_get(dpm_ctx* ctx, const char* module, const char* section, const char* key)`
|
||||
Returns the configured value for `key` in `section` of the named module's config namespace (`/etc/dpm/conf.d/`<module>.conf; the namespace "core", from `core.conf`, is the library's own). Returns NULL if unset. String valid until context close.
|
||||
|
||||
**`void dpm_log(dpm_ctx* ctx, int level, const char* message)`**
|
||||
`void dpm_log(dpm_ctx* ctx, int level, const char* message)`
|
||||
Writes `message` at `level` (FATAL=0, ERROR=1, WARN=2, INFO=3, DEBUG=4) to the context's configured log targets (console and/or file). Messages above the configured level are dropped. NULL message is a no-op.
|
||||
|
||||
**`const char* dpm_module_path(dpm_ctx* ctx)`**
|
||||
`const char* dpm_module_path(dpm_ctx* ctx)`
|
||||
Returns the resolved module directory path for this context.
|
||||
|
||||
**`const char* dpm_last_error(dpm_ctx* ctx)`**
|
||||
`const char* dpm_last_error(dpm_ctx* ctx)`
|
||||
Returns a human-readable description of the most recent failure recorded on this context, or NULL if none. Overwritten by the next failing call on the same context.
|
||||
|
||||
## Module Contract
|
||||
|
||||
A module is one .so in the module directory. It includes `<dpm/core.h>`, links `-ldpm-core`, and exports the following reserved symbols as extern "C". Returned strings are static or module-owned, non-NULL, and valid for the lifetime of the loaded module; the library and consumers never free them.
|
||||
|
||||
**`int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`**
|
||||
`int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`
|
||||
The module's command entry point, and the only entry through which it performs work. `ctx` is the host context that dispatched the call — the module reaches every service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it, and reaches peer modules through it as well. `command` is the subcommand name (equal to argv[0] when argc > 0); argc/argv are the remaining CLI-style arguments. NULL or empty `command` must behave as the module's help command. Returns 0 on success, nonzero on failure. It must be callable immediately after load with no other setup.
|
||||
|
||||
**`const char* dpm_module_version(void)`**
|
||||
`const char* dpm_module_version(void)`
|
||||
Returns the module's own version as an X.Y.Z string. Must be constant for the life of the module. This is the value the library reports to consumers, and the value they judge compatibility against.
|
||||
|
||||
**`const char* dpm_module_description(void)`**
|
||||
`const char* dpm_module_description(void)`
|
||||
Returns a one-line human-readable description, used in module listings.
|
||||
|
||||
**Version compatibility with the library is the module's own to determine.** A module is built against the system-installed `libdpm-core.so` and is responsible for being correct against it. Where it needs to act on what it is running under, `dpm_core_version()` reports the running version and the module decides what to do with that.
|
||||
|
||||
Reference in New Issue
Block a user