* 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 | 58 ++++++++++++++++++++++++++++++++++++++
2 files changed, 67 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..e58916a0
--- /dev/null
+++ b/glibc/error-reporting.mdwn
@@ -0,0 +1,58 @@
+[[!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 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) __COLD;
+
+Check if ERR should generate a signal. Returns the signal to take, or
+zero if none. The `__COLD` attribute tells gccc that this function
+will rarely be used.
--
2.50.1
