From 133c849048ba44e964b3bc4f356a31f347316cd9 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 23 Oct 2024 17:13:02 -0700 Subject: docs: document error codes --- docs/ref/api/errors.md | 76 +++++++++++++++++++++++++++++++++++++++ docs/ref/api/util/nng_strerror.md | 33 ----------------- 2 files changed, 76 insertions(+), 33 deletions(-) create mode 100644 docs/ref/api/errors.md delete mode 100644 docs/ref/api/util/nng_strerror.md (limited to 'docs/ref/api') diff --git a/docs/ref/api/errors.md b/docs/ref/api/errors.md new file mode 100644 index 00000000..6548c263 --- /dev/null +++ b/docs/ref/api/errors.md @@ -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` | 1 | Operation interrupted. | +| `NNG_ENOMEM` | 2 | Out of memory, or other resource exahusted. | +| `NNG_EINVAL` | 3 | Invalid argument. The arguments are invalid or malformed somehow. | +| `NNG_EBUSY` | 4 | Resource busy. | +| `NNG_ETIMEDOUT` | 5 | Timed out. The operation took longer than the allotted time. | +| `NNG_ECONNREFUSED` | 6 | Connection refused. Usually indicates the wrong address or a server is running. | +| `NNG_ECLOSED` | 7 | Object closed. Typically the [socket] is closed. | +| `NNG_EAGAIN` | 8 | Try again. Typcally for a non-blocking operation that might succeed later. | +| `NNG_ENOTSUP` | 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` | 10 | Address in use. The network address is already used by another process. Most often this is seen for [listeners][listener]. | +| `NNG_ESTATE` | 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` | 12 | Entry not found (no such object.) Can also indicate that a file does not exist. | +| `NNG_EPROTO` | 13 | Protocol error. Typically this indicates incorrect messages over a network. | +| `NNG_EUNREACHABLE` | 14 | Destination unreachable. | +| `NNG_EADDRINVAL` | 15 | Address invalid. Like [`NNG_EINVAL`], but only for network addresses. | +| `NNG_EPERM` | 16 | Permission denied. | +| `NNG_EMSGSIZE` | 17 | Message too large. | +| `NNG_ECONNABORTED` | 18 | Connection aborted. A connection attempt was aborted locally. | +| `NNG_ECONNRESET` | 19 | Connection reset. The remote peer reset the connection unexpectedly. | +| `NNG_ECANCELED` | 20 | Operation canceled. Typically as a result of [`nng_aio_cancel`] or similar. | +| `NNG_ENOFILES` | 21 | Out of files. Either the destination file system cannot store files, or all available file handles are used. | +| `NNG_ENOSPC` | 22 | Out of space. Destination table or filesystem is full. | +| `NNG_EEXIST` | 23 | Resource already exists. | +| `NNG_EREADONLY` | 24 | Read only resource. An attempt to modify a read-only file or other object. | +| `NNG_EWRITEONLY` | 25 | Write only resource. A read operation failed because the object only supports writes. | +| `NNG_ECRYPTO` | 26 | Cryptographic error. Usually indicates an invalid key was used for TLS. | +| `NNG_EPEERAUTH` | 27 | Peer could not be authenticated. | +| `NNG_ENOARG` | 28 | Option requires argument. A command-line option was supplied without an argument. Only used with [`nng_opts_parse`]. | +| `NNG_EAMBIGUOUS` | 29 | Ambiguous option. The command line option could not be unambiguously resolved. Only used with [`nng_opts_parse`]. | +| `NNG_EBADTYPE` | 30 | Incorrect type. A type-specific function was used for an object of the wrong type. | +| `NNG_ECONNSHUT` | 31 | Connection shutdown. The connection was shut down and cannot be used. | +| `NNG_EINTERNAL` | 1000 | An unidentifier internal error occurred. | +| `NNG_ESYSERR` | 0x10000000 - 0x1FFFFFFF | An unidentified system error occurred. These are errors reported by the operating system. | +| `NNG_ETRANERR` | 0x20000000 - 0x2FFFFFFF | An unidentified transport error occurred. | + +{{#include ../xref.md}} diff --git a/docs/ref/api/util/nng_strerror.md b/docs/ref/api/util/nng_strerror.md deleted file mode 100644 index a48f9f54..00000000 --- a/docs/ref/api/util/nng_strerror.md +++ /dev/null @@ -1,33 +0,0 @@ -# nng_strerror - -## NAME - -nng_strerror --- return an error description - -## SYNOPSIS - -```c -#include - -const char *nng_strerror(int err); -``` - -## DESCRIPTION - -The {{i:`nng_strerror`}} returns the human-readable description of the -given error in `err`. - -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. - -## RETURN VALUES - -This function returns the human-readable error message, terminated -by a `NUL` byte. -- cgit v1.2.3-70-g09d2