47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
|
# Error codes
|
||
|
|
|
||
|
|
The library uses integer values to specify error codes inside of its context. These integer return codes are defined in `akerror.h` in the form of `AKERR_xxxxx` where `xxxxx` is the name of the error code in question. See `akerror.h` for a list of defined errors and their descriptions.
|
||
|
|
|
||
|
|
You can define additional error types as integer constants. Values 0 through 255
|
||
|
|
are reserved by libakerror (the host's errno values plus the `AKERR_*` codes);
|
||
|
|
consumers allocate codes starting at `AKERR_FIRST_CONSUMER_STATUS` (256). Status
|
||
|
|
names are stored sparsely, so any `int` is a legal status and no compile
|
||
|
|
definition is needed to use large values. Note that no consumer status can be a
|
||
|
|
process exit code — see [Exit status](exit-status.md).
|
||
|
|
|
||
|
|
Every library that may coexist in one process must reserve its range during
|
||
|
|
initialization. `akerr_reserve_status_range()` and
|
||
|
|
`akerr_register_status_name()` report failure the way everything else in this
|
||
|
|
library does — they return `akerr_ErrorContext *`, and they are marked
|
||
|
|
`AKERR_NOIGNORE` — so a collision is an exception you can `CATCH`, `HANDLE`, or
|
||
|
|
`PASS` up out of your initialization:
|
||
|
|
|
||
|
|
```c
|
||
|
|
#define MYLIB_OWNER "my-library"
|
||
|
|
|
||
|
|
akerr_ErrorContext AKERR_NOIGNORE *mylib_init(void)
|
||
|
|
{
|
||
|
|
PREPARE_ERROR(errctx);
|
||
|
|
|
||
|
|
/* Another component owning part of the range propagates to our caller. */
|
||
|
|
PASS(errctx, akerr_reserve_status_range(256, 16, MYLIB_OWNER));
|
||
|
|
|
||
|
|
/* Then name each code, quoting the owner you reserved with. */
|
||
|
|
PASS(errctx, akerr_register_status_name(MYLIB_OWNER, 256,
|
||
|
|
"Some Error Code Description"));
|
||
|
|
SUCCEED_RETURN(errctx);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Reservations are process-local, fixed-capacity, and idempotent when the same
|
||
|
|
owner repeats the exact same range. They preserve compile-time integer constants
|
||
|
|
so `HANDLE` still works, since `case` labels require them.
|
||
|
|
|
||
|
|
Naming a status outside your reservation raises `AKERR_STATUS_NAME_FOREIGN`, and
|
||
|
|
naming one nobody reserved raises `AKERR_STATUS_NAME_UNRESERVED`; a colliding
|
||
|
|
reservation raises `AKERR_STATUS_RANGE_OVERLAP`, with a message naming the real
|
||
|
|
owner. See [UPGRADING.md](../UPGRADING.md) for the full list of statuses these two
|
||
|
|
functions raise, the capacity limits and how to raise them, and thread-safety
|
||
|
|
rules.
|
||
|
|
|