Skip to content

Commit

Permalink
docs: document error codes
Browse files Browse the repository at this point in the history
  • Loading branch information
@gdamore
gdamore committed Oct 24, 2024
1 parent 4de579a commit 133c849
Show file tree
Hide file tree
Showing 4 changed files with 110 additions and 35 deletions.
3 changes: 2 additions & 1 deletion docs/ref/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,15 @@

- [Statistics](./api/stats.md)

- [Errors](./api/errors.md)

- [Miscellaneous](./api/misc.md)

- [ID Map](./api/id_map.md)

- [Utility Functions](./api/util/index.md)

- [nng_opts_parse](./api/util/nng_opts_parse.md)
- [nng_strerror](./api/util/nng_strerror.md)

- [Protocols](./proto/index.md)

Expand Down
76 changes: 76 additions & 0 deletions docs/ref/api/errors.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Errors

Many _NNG_ functions can fail for a variety of reasons.
These functions tend to return either zero on success,
or a non-zero error code to indicate failure.
{{footnote: This convention goes back to UNIX system calls,
which behave the same way, but _NNG_ does not use a separate
_errno_ variable.}}

All these error codes are `int`.

Not every possible error code is defined here, as sometimes
an underlying system or library error code is "wrapped".

## Human Readable Error Message

```c
const char *nng_strerror(int err);
```
The {{i:`nng_strerror`}} returns the human-readable description of the
given error in `err`.
The error message returned is a fixed `NUL`-terminated string and may be located in
read-only memory.
The returned {{i:error message}} is provided in US English, but in the
future locale-specific strings may be presented instead.
> [!NOTE]
> The specific strings associated with specific error messages are
> subject to change.
> Therefore applications must not depend on the message,
> but may use them verbatim when supplying information to end-users, such
> as in diagnostic messages or log entries.
## List of Errors
| Error | Value | Description |
| ------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NNG_EINTR`<a name="NNG_EINTR"></a> | 1 | Operation interrupted. |
| `NNG_ENOMEM`<a name="NNG_ENOMEM"></a> | 2 | Out of memory, or other resource exahusted. |
| `NNG_EINVAL`<a name="NNG_EINVAL"></a> | 3 | Invalid argument. The arguments are invalid or malformed somehow. |
| `NNG_EBUSY`<a name="NNG_EBUSY"></a> | 4 | Resource busy. |
| `NNG_ETIMEDOUT`<a name="NNG_ETIMEDOUT"></a> | 5 | Timed out. The operation took longer than the allotted time. |
| `NNG_ECONNREFUSED`<a name="NNG_ECONNREFUSED"></a> | 6 | Connection refused. Usually indicates the wrong address or a server is running. |
| `NNG_ECLOSED`<a name="NNG_ECLOSED"></a> | 7 | Object closed. Typically the [socket] is closed. |
| `NNG_EAGAIN`<a name="NNG_EAGAIN"></a> | 8 | Try again. Typcally for a non-blocking operation that might succeed later. |
| `NNG_ENOTSUP`<a name="NNG_ENOTSUP"></a> | 9 | Not supported. Perhaps the protocol or transport is not supported, or the operation is not not supported with the transport or protocol. |
| `NNG_EADDRINUSE`<a name="NNG_EADDRINUSE"></a> | 10 | Address in use. The network address is already used by another process. Most often this is seen for [listeners][listener]. |
| `NNG_ESTATE`<a name="NNG_ESTATE"></a> | 11 | Incorrect state. The operation cannot be performed in the current state, such as trying to send a response when no request has yet been received. |
| `NNG_ENOENT`<a name="NNG_ENOENT"></a> | 12 | Entry not found (no such object.) Can also indicate that a file does not exist. |
| `NNG_EPROTO`<a name="NNG_EPROTO"></a> | 13 | Protocol error. Typically this indicates incorrect messages over a network. |
| `NNG_EUNREACHABLE`<a name="NNG_EUNREACHABLE"></a> | 14 | Destination unreachable. |
| `NNG_EADDRINVAL`<a name="NNG_EADDRINVAL"></a> | 15 | Address invalid. Like [`NNG_EINVAL`], but only for network addresses. |
| `NNG_EPERM`<a name="NNG_EPERM"></a> | 16 | Permission denied. |
| `NNG_EMSGSIZE`<a name="NNG_EMSGSIZE"></a> | 17 | Message too large. |
| `NNG_ECONNABORTED`<a name="NNG_ECONNABORTED"></a> | 18 | Connection aborted. A connection attempt was aborted locally. |
| `NNG_ECONNRESET`<a name="NNG_ECONNRESET"></a> | 19 | Connection reset. The remote peer reset the connection unexpectedly. |
| `NNG_ECANCELED`<a name="NNG_ECANCELED"></a> | 20 | Operation canceled. Typically as a result of [`nng_aio_cancel`] or similar. |
| `NNG_ENOFILES`<a name="NNG_ENOFILES"></a> | 21 | Out of files. Either the destination file system cannot store files, or all available file handles are used. |
| `NNG_ENOSPC`<a name="NNG_ENOSPC"></a> | 22 | Out of space. Destination table or filesystem is full. |
| `NNG_EEXIST`<a name="NNG_EEXIST"></a> | 23 | Resource already exists. |
| `NNG_EREADONLY`<a name="NNG_EREADONLY"></a> | 24 | Read only resource. An attempt to modify a read-only file or other object. |
| `NNG_EWRITEONLY`<a name="NNG_EWRITEONLY"></a> | 25 | Write only resource. A read operation failed because the object only supports writes. |
| `NNG_ECRYPTO`<a name="NNG_ECRYPTO"></a> | 26 | Cryptographic error. Usually indicates an invalid key was used for TLS. |
| `NNG_EPEERAUTH`<a name="NNG_EPEERAUTH"></a> | 27 | Peer could not be authenticated. |
| `NNG_ENOARG`<a name="NNG_ENOARG"></a> | 28 | Option requires argument. A command-line option was supplied without an argument. Only used with [`nng_opts_parse`]. |
| `NNG_EAMBIGUOUS`<a name="NNG_EAMBIGUOUS"></a> | 29 | Ambiguous option. The command line option could not be unambiguously resolved. Only used with [`nng_opts_parse`]. |
| `NNG_EBADTYPE`<a name="NNG_EBADTYPE"></a> | 30 | Incorrect type. A type-specific function was used for an object of the wrong type. |
| `NNG_ECONNSHUT`<a name="NNG_ECONNSHUT"></a> | 31 | Connection shutdown. The connection was shut down and cannot be used. |
| `NNG_EINTERNAL`<a name="NNG_EINTERNAL"></a> | 1000 | An unidentifier internal error occurred. |
| `NNG_ESYSERR`<a name="NNG_ESYSERR"></a> | 0x10000000 - 0x1FFFFFFF | An unidentified system error occurred. These are errors reported by the operating system. |
| `NNG_ETRANERR`<a name="NNG_ETRANERR"></a> | 0x20000000 - 0x2FFFFFFF | An unidentified transport error occurred. |
{{#include ../xref.md}}
33 changes: 0 additions & 33 deletions docs/ref/api/util/nng_strerror.md
View file

This file was deleted.

33 changes: 32 additions & 1 deletion docs/ref/xref.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,18 +52,49 @@
[`nng_stat_string`]: /api/stats.md#statistic-value
[`nng_stat_unit`]: /api/stats.md#statistic-units
[`nng_id_set`]: /api/id_map.md#store-a-value
[`nng_strerror`]: /api/errors.md#human-readable-error-message
[`nng_send`]: /TODO.md
[`nng_recv`]: /TODO.md
[`nng_aio`]: /TODO.md
[`nng_sleep_aio`]: /TODO.md
[`nng_aio_cancel`]: /TODO.md
[`nng_opts_parse`]: /TODO.md

<!-- Macros -->

[`NNG_EINTR`]: /api/errors.md#NNG_EINTR
[`NNG_ENOMEM`]: /api/errors.md#NNG_ENOMEM
[`NNG_EINVAL`]: /api/errors.md#NNG_EINVAL
[`NNG_EBUSY`]: /api/errors.md#NNG_EBUSY
[`NNG_ETIMEDOUT`]: /api/errors.md#NNG_ETIMEDOUT
[`NNG_ENOSPC`]: /api/errors.md#NNG_ENOSPC
[`NNG_ECONNREFUSED`]: /api/errors.md#NNG_ECONNREFUSED
[`NNG_ECLOSED`]: /api/errors.md#NNG_ECLOSED
[`NNG_EAGAIN`]: /api/errors.md#NNG_EAGAIN
[`NNG_ENOTSUP`]: /api/errors.md#NNG_ENOTSUP
[`NNG_EADDRINUSE`]: /api/errors.md#NNG_EADDRINUSE
[`NNG_ESTATE`]: /api/errors.md#NNG_ESTATE
[`NNG_ENOENT`]: /api/errors.md#NNG_ENOENT
[`NNG_EUNREACHABLE`]: /api/errors.md#NNG_EUNREACHABLE
[`NNG_EADDRINVAL`]: /api/errors.md#NNG_EADDRINVAL
[`NNG_EPERM`]: /api/errors.md#NNG_EPERM
[`NNG_EMSGSIZE`]: /api/errors.md#NNG_EMSGSIZE
[`NNG_ECONNABORTED`]: /api/errors.md#NNG_ECONNABORTED
[`NNG_ECONNRESET`]: /api/errors.md#NNG_ECONNRESET
[`NNG_ECANCELED`]: /api/errors.md#NNG_ECANCELED
[`NNG_ENOFILES`]: /api/errors.md#NNG_ENOFILES
[`NNG_ENOSPC`]: /api/errors.md#NNG_ENOSPC
[`NNG_EEXIST`]: /api/errors.md#NNG_EEXIST
[`NNG_EREADONLY`]: /api/errors.md#NNG_EREADONLY
[`NNG_EWRITEONLY`]: /api/errors.md#NNG_EWRITEONLY
[`NNG_ECRYPTO`]: /api/errors.md#NNG_ECRYPTO
[`NNG_EPEERAUTH`]: /api/errors.md#NNG_EPEERAUTH
[`NNG_ENOARG`]: /api/errors.md#NNG_ENOARG
[`NNG_EAMBIGUOUS`]: /api/errors.md#NNG_EAMBIGUOUS
[`NNG_EBADTYPE`]: /api/errors.md#NNG_EBADTYPE
[`NNG_ECONNSHUT`]: /api/errors.md#NNG_ECONNSHUT
[`NNG_EINTERNAL`]: /api/errors.md#NNG_EINTERNAL
[`NNG_ESYSERR`]: /api/errors.md#NNG_ESYSERR
[`NNG_ETRANERR`]: /api/errors.md#NNG_ETRANERR
[`NNG_DURATION_INFINITE`]: /api/time.md#duration-type
[`NNG_DURATION_DEFAULT`]: /api/time.md#duration-type
[`NNG_DURATION_ZERO`]: /api/time.md#duration-type
Expand Down

0 comments on commit 133c849

Please sign in to comment.