August 11, 2025 at 2:41 PM, jbra...@dismail.de mailto:jbra...@dismail.de wrote:
>
> * glibc.mdwn: link to glibc/error-reporting.md
> * glibc/error-reporting.mdwn: new file. Document, __hurd_fail () and
> friends. And throw in a reference to __COLD.
The commit message here is wrong. __COLD is not documented. I'm happy to
send v4 of this. I thought I had fixed most issues, but I guess not.
> ---
> glibc.mdwn | 15 ++++++----
> glibc/error-reporting.mdwn | 57 ++++++++++++++++++++++++++++++++++++++
> 2 files changed, 66 insertions(+), 6 deletions(-)
> create mode 100644 glibc/error-reporting.mdwn
>
> diff --git a/glibc.mdwn b/glibc.mdwn
> index 9dc66c89..3e432aac 100644
> --- a/glibc.mdwn
> +++ b/glibc.mdwn
> @@ -1,5 +1,5 @@
> -[[!meta copyright="Copyright © 2007, 2008, 2010, 2011, 2012, 2013, 2015 Free
> -Software Foundation, Inc."]]
> +[[!meta copyright="Copyright © 2007, 2008, 2010, 2011, 2012, 2013,
> +2015, 2024 Free Software Foundation, Inc."]]
>
> [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
> id="license" text="Permission is granted to copy, distribute and/or modify
> this
> @@ -28,9 +28,11 @@ repository|source_repositories/glibc]].
>
> Porting glibc to a specific architecture is non-trivial.
>
> -The main port is x86, which is somewhat complete and is maintained. There
> were
> -incomplete ports for Alpha, MIPS, and PowerPC, but they were unmaintained and
> -have been removed.
> +The main port is x86, which is somewhat complete and is maintained.
> +We are actively stabilizing the [[X86_64
> +port|open_issues/64-bit_port]]. There were incomplete ports for
> +Alpha, MIPS, and PowerPC, but they were unmaintained and have been
> +removed.
>
>
> ## [[Hurd-specific Port|hurd/glibc]]
> @@ -54,6 +56,8 @@ fact simply forwarded to/implemented as [[system_call]]s.
>
> * [[startup]]
>
> + * [[glibc/error-reporting]]
> +
>
> ## Concepts
>
> @@ -80,7 +84,6 @@ Some of these are well-known as [[UNIX]] [[system call]]s.
>
> * [[poll]]
>
> -
> # Debugging
>
> Some hints for [[debugging]].
> diff --git a/glibc/error-reporting.mdwn b/glibc/error-reporting.mdwn
> new file mode 100644
> index 00000000..78482558
> --- /dev/null
> +++ b/glibc/error-reporting.mdwn
> @@ -0,0 +1,57 @@
> +[[!meta copyright="Copyright © 2025 Free Software Foundation, Inc."]]
> +
> +[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
> +id="license" text="Permission is granted to copy, distribute and/or modify
> this
> +document under the terms of the GNU Free Documentation License, Version 1.2
> or
> +any later version published by the Free Software Foundation; with no
> Invariant
> +Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the
> license
> +is included in the section entitled [[GNU Free Documentation
> +License|/fdl]]."]]"""]]
> +
> +[[!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 recommended way of
> +reporting errors in the Hurd part of glibc. It is more concise than `{
> +errno = err; return -1; }`, and it translates some MIG and Mach 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.
> +This function converts some errors into signals as expressed by
> +POSIX. It sets `errno` to the appropriate error code and always return
> +-1. Most developers will rarely use this function, since `__hurd_fail
> +()` handles most usecases.
> +
> +
> + `_hurd_fd_error (error_t err)`
> +
> +Handle an error from an RPC on a file descriptor's port. This
> +function is almost the same as `__hurd_dfail ()`. `_hurd_fd_error ()`
> +returns the error, while `__hurd_dfail ()` sets errno and returns
> +`-1`. You should always use this function to handle errors from RPCs
> +made on file descriptor ports. Some errors are translated into
> +signals.
> +
> +
> + `__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. It
> +differs from `__hurd_dfail ()` in that it does not raise `SIGPIPE` on
> +`EPIPE` if flags contain `MSG_NOSIGNAL`.
> +
> +
> + extern int _hurd_fd_error_signal (error_t err);
> +
> +Check if ERR should generate a signal. Returns the signal to take, or
> +zero if none.
> --
> 2.50.1
>
