* 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
