commit 1137d466d4fb093b1f721e543230bc7a1cd71329
parent 73947d753087c015ceaaf953799617acfe730f5e
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 14 Aug 2026 17:47:02 +0200
disambiguate return values
Diffstat:
6 files changed, 40 insertions(+), 22 deletions(-)
diff --git a/manpages/challenger-send-email.1.rst b/manpages/challenger-send-email.1.rst
@@ -39,7 +39,7 @@ TAN is never passed on the command line.
Handing a message to a mail transfer agent establishes only that the agent
accepted it for delivery. Whether it reaches the recipient's mailbox is decided
later and asynchronously, and is never reported back. **This helper therefore
-never reports confirmed delivery**: a successful run exits with status 1,
+never reports confirmed delivery**: a successful run exits with status 201,
meaning accepted for delivery.
Delivery requires a working local mail transfer agent. The helper does not
@@ -57,10 +57,13 @@ environment of the invoking daemon.
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not.
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery.
-**1**
+**201**
The mail transfer agent accepted the message for delivery. This is the
success case; status 0 is never reported, as delivery to a mailbox cannot be
confirmed.
diff --git a/manpages/challenger-send-post.1.rst b/manpages/challenger-send-post.1.rst
@@ -49,7 +49,7 @@ with a truncated TAN.
Posting a letter establishes only that pingen accepted it for printing and
dispatch. **This helper therefore never reports confirmed delivery**: a
-successful run exits with status 1, meaning accepted for delivery. Physical
+successful run exits with status 201, meaning accepted for delivery. Physical
delivery takes days and is not reported back.
Address fields are passed to typst(1) as string inputs and are never
@@ -94,10 +94,13 @@ typst(1) must be installed and must support the ``--no-pdf-tags`` option.
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not.
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery.
-**1**
+**201**
pingen accepted the letter for printing and dispatch. This is the success
case; status 0 is never reported, as physical delivery cannot be confirmed.
diff --git a/manpages/challenger-send-sms-aspsms.1.rst b/manpages/challenger-send-sms-aspsms.1.rst
@@ -62,14 +62,17 @@ file.
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not. The subset below is what this helper can actually
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery. The subset below is what this helper can actually
report; see challenger-send-sms(1) for the full table.
**0**
Delivery to the handset was confirmed.
-**1**
+**201**
ASPSMS accepted the message but delivery was not confirmed within the polling
window, including the common case of a message still buffered for a handset
that is switched off.
diff --git a/manpages/challenger-send-sms-clicksend.1.rst b/manpages/challenger-send-sms-clicksend.1.rst
@@ -68,18 +68,21 @@ file.
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not. The subset below is what this helper can actually
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery. The subset below is what this helper can actually
report; see challenger-send-sms(1) for the full table.
**0**
Delivery to the handset was confirmed.
-**1**
+**201**
ClickSend queued the message but delivery was not confirmed within the
polling window.
-**2**
+**202**
The message was suppressed as a duplicate of one recently sent to the same
recipient. The earlier copy carries the same TAN and is in flight.
diff --git a/manpages/challenger-send-sms-telesign.1.rst b/manpages/challenger-send-sms-telesign.1.rst
@@ -58,14 +58,17 @@ configuration file.
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not. The subset below is what this helper can actually
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery. The subset below is what this helper can actually
report; see challenger-send-sms(1) for the full table.
**0**
Delivery to the handset was confirmed.
-**1**
+**201**
Telesign accepted the message but delivery was not confirmed within the
polling window, or Telesign reported that the final status is unknown.
diff --git a/manpages/challenger-send-sms.1.rst b/manpages/challenger-send-sms.1.rst
@@ -77,17 +77,20 @@ challenger-send-sms-clicksend(1) and challenger-send-sms-aspsms(1).
Exit Status
===========
-An exit status below 10 means the TAN was transmitted, or will be. Any other
-status means it was not.
+An exit status of 0, or in the 200 to 210 band, means the TAN was
+transmitted, or will be. Any other status means it was not. The success
+band starts at 200 rather than at 1 because GNUnet reports a helper it
+could not execute as exit status 1, which must not be mistaken for a
+delivery.
**0**
The TAN was delivered and receipt on the handset was confirmed.
-**1**
+**201**
A provider accepted the TAN for delivery, but delivery was not confirmed
within the polling window. This is a success: the message is in flight.
-**2**
+**202**
A provider suppressed the message as a duplicate, because an identical
message was recently accepted for the same recipient. The earlier copy is in
flight, so this too is a success.
