[PATCH 1/2] document __hurd_fail ()

[address@hidden]

* 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.
---
 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..eefa3e5c
--- /dev/null
+++ b/glibc/error-reporting.mdwn
@@ -0,0 +1,57 @@
+[[!meta copyright="Copyright © 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
+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 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.
+
+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.
+
+
+       `_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_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`.
+
+
+       `__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;
-- 
2.45.2