Hello,
jbra...@dismail.de, le dim. 01 déc. 2024 21:39:19 -0500, a ecrit:
> +[[!meta title="glibc error reporting"]]
> +
> +When reporting errors in the Hurd part of glibc, please use these
> +functions. They can be found in `$glibc-SRC/hurd/hurd/fd.h`.
> +
> + `__hurd_fail(error_t err)`
> +
> +The `__hurd_fail ()` inline function is the dedicated, idiomatic way
> +of reporting errors in the Hurd part of glibc. Not only is it more
> +concise than `{ errno = err; return -1; }`, it is since commit
> +`6639cc10029e24e06b34e169712b21c31b8cf213` "hurd: Mark error functions
> +as __COLD" marked with the cold attribute, telling the compiler that
> +this codepath is unlikely to be executed.
The main use of the function, beyond setting errno is rather that it
converts some mach and MIG errors into posix errors.
> +You can see some example uses of it from this
> +[[email|https://lists.gnu.org/archive/html/bug-hurd/2023-05/msg00369.html]]
> +to bug-hurd.
> +
> + extern int __hurd_dfail (int fd, error_t err);
> +
> +Handle error code `ERR` from an RPC on file descriptor FD's port. Set
> +`errno` to the appropriate error code, and always return -1. You
> +rarely will need to use this function. `__hurd_fail ()` covers most
> +usecases.
The main point of this is that it turns some of the errors into signals,
according to posix.
> + `_hurd_fd_error (error_t err)`
> +
> +Handle an error from an RPC on a file descriptor's port. You should
> +always use this function to handle errors from RPCs made on file
> +descriptor ports. Some errors are translated into signals.
_hurd_fd_error is extremely similar to __hurd_dfail, the only difference
is that _hurd_fd_error returns the error, while __hurd_dfail sets errno
and returns -1.
> + `__hurd_sockfail (int fd, int flags, error_t err)`
> +
> +Handle error code ERR from an RPC on file descriptor FD's port. Set
> +`errno` to the appropriate error code, and always return -1. But do
> +not raise `SIGPIPE` on `EPIPE` if flags contain `MSG_NOSIGNAL`.
The last part is really what matters compared to __hurd_dfail.
> + `__COLD`
> +
> +The `__COLD` attribute, lets you mark functions in glibc as not being
> +used often, which should help the compiler to optimize things. You
> +can see example uses of it in `$Glibc-src/hurd/hurd/fd.h`.
> +
> + extern int _hurd_fd_error_signal (error_t err) __COLD;
I don't think it is really useful to document, it's only a
side-optimization.
Samuel
