Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: document uv.errno #620

Merged
merged 2 commits into from
Oct 14, 2022
Merged

docs: document uv.errno #620

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27d66be
docs: document uv.errno
Bilal2453 Oct 13, 2022
7d4916e
add a reference to libuv's error constants
Bilal2453 Oct 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 89 additions & 4 deletions docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ uv.run() -- an explicit run call is necessary outside of luvit
The luv library contains a single Lua module referred to hereafter as `uv` for
simplicity. This module consists mostly of functions with names corresponding to
their original libuv versions. For example, the libuv function `uv_tcp_bind` has
a luv version at `uv.tcp_bind`. Currently, only one non-function field exists:
`uv.constants`, which is a table.
a luv version at `uv.tcp_bind`. Currently, only two non-function fields exists:
`uv.constants` and `uv.errno`, which are tables.

### Functions vs Methods

Expand Down Expand Up @@ -113,8 +113,8 @@ are relevant to behavior seen in the Lua module.

[Error handling]: #error-handling

In libuv, errors are negative numbered constants; however, these errors and the
functions used to handle them are not exposed to luv users. Instead, if an
In libuv, errors are negative numbered constants; however, while those errors are exposed through `uv.errno`,
the functions used to handle them are not exposed to luv users. Instead, if an
internal error is encountered, the luv function will return to the caller an
assertable `nil, err, name` tuple.

Expand All @@ -130,6 +130,91 @@ When a function is called successfully, it will return either a value that is
relevant to the operation of the function, or the integer `0` to indicate
success, or sometimes nothing at all. These cases are documented below.

### `uv.errno`

A table value which exposes error constants as a map, where the key is the error name (without the `UV_` prefix) and its value is a negative number.

- `E2BIG`: argument list too long.
- `EACCES`: permission denied.
- `EADDRINUSE`: address already in use.
- `EADDRNOTAVAIL`: address not available.
- `EAFNOSUPPORT`: address family not supported.
- `EAGAIN`: resource temporarily unavailable.
- `EAI_ADDRFAMILY`: address family not supported.
- `EAI_AGAIN`: temporary failure.
- `EAI_BADFLAGS`: bad ai_flags value.
- `EAI_BADHINTS`: invalid value for hints.
- `EAI_CANCELED`: request canceled.
- `EAI_FAIL`: permanent failure.
- `EAI_FAMILY`: ai_family not supported.
- `EAI_MEMORY`: out of memory.
- `EAI_NODATA`: no address.
- `EAI_NONAME`: unknown node or service.
- `EAI_OVERFLOW`: argument buffer overflow.
- `EAI_PROTOCOL`: resolved protocol is unknown.
- `EAI_SERVICE`: service not available for socket type.
- `EAI_SOCKTYPE`: socket type not supported.
- `EALREADY`: connection already in progress.
- `EBADF`: bad file descriptor.
- `EBUSY`: resource busy or locked.
- `ECANCELED`: operation canceled.
- `ECHARSET`: invalid Unicode character.
- `ECONNABORTED`: software caused connection abort.
- `ECONNREFUSED`: connection refused.
- `ECONNRESET`: connection reset by peer.
- `EDESTADDRREQ`: destination address required.
- `EEXIST`: file already exists.
- `EFAULT`: bad address in system call argument.
- `EFBIG`: file too large.
- `EHOSTUNREACH`: host is unreachable.
- `EINTR`: interrupted system call.
- `EINVAL`: invalid argument.
- `EIO`: i/o error.
- `EISCONN`: socket is already connected.
- `EISDIR`: illegal operation on a directory.
- `ELOOP`: too many symbolic links encountered.
- `EMFILE`: too many open files.
- `EMSGSIZE`: message too long.
- `ENAMETOOLONG`: name too long.
- `ENETDOWN`: network is down.
- `ENETUNREACH`: network is unreachable.
- `ENFILE`: file table overflow.
- `ENOBUFS`: no buffer space available.
- `ENODEV`: no such device.
- `ENOENT`: no such file or directory.
- `ENOMEM`: not enough memory.
- `ENONET`: machine is not on the network.
- `ENOPROTOOPT`: protocol not available.
- `ENOSPC`: no space left on device.
- `ENOSYS`: function not implemented.
- `ENOTCONN`: socket is not connected.
- `ENOTDIR`: not a directory.
- `ENOTEMPTY`: directory not empty.
- `ENOTSOCK`: socket operation on non-socket.
- `ENOTSUP`: operation not supported on socket.
- `EOVERFLOW`: value too large for defined data type.
- `EPERM`: operation not permitted.
- `EPIPE`: broken pipe.
- `EPROTO`: protocol error.
- `EPROTONOSUPPORT`: protocol not supported.
- `EPROTOTYPE`: protocol wrong type for socket.
- `ERANGE`: result too large.
- `EROFS`: read-only file system.
- `ESHUTDOWN`: cannot send after transport endpoint shutdown.
- `ESPIPE`: invalid seek.
- `ESRCH`: no such process.
- `ETIMEDOUT`: connection timed out.
- `ETXTBSY`: text file is busy.
- `EXDEV`: cross-device link not permitted.
- `UNKNOWN`: unknown error.
- `EOF`: end of file.
- `ENXIO`: no such device or address.
- `EMLINK`: too many links.
- `ENOTTY`: inappropriate ioctl for device.
- `EFTYPE`: inappropriate file type or format.
- `EILSEQ`: illegal byte sequence.
- `ESOCKTNOSUPPORT`: socket type not supported.
Copy link
Member

@squeek502 squeek502 Oct 13, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be better to just link out to https://docs.libuv.org/en/v1.x/errors.html#error-constants instead of enumerating them here? It would ensure that we wouldn't have to keep this list in sync.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Possibly, if it's autogenerated. It's nice to see the list here though too.

Copy link
Member

@squeek502 squeek502 Oct 13, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The errno table is populated using libuv's UV_ERRNO_MAP macro, so it'll always match the errors of version being built against.

Copy link
Contributor Author

@Bilal2453 Bilal2453 Oct 14, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was -and still am- debating whether we should just link that page or not. What I thought was "enumerating them here ain't gonna hurt", I guess we could do both, a link to the libuv docs page, while also listing them here (kinda nice to have em here in my opinion).

Does mean we will need to pay some attention to those values being updated, but to be honest that won't be happening that often, if at all.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, I think adding the link would be good.


## Version Checking

[Version checking]: #version-checking
Expand Down