Re: [PATCH] man3/*printf.3: Add errors section
From: Tobias Stoeckmann <hidden>
Date: 2025-05-18 13:42:17
Subsystem:
the rest · Maintainer:
Linus Torvalds
The printf family of functions set errno if a negative value is returned. Souce is POSIX.1-2024, see <https://pubs.opengroup.org/onlinepubs/9799919799/functions/fprintf.html> <https://pubs.opengroup.org/onlinepubs/9799919799/functions/fwprintf.html> Also see manual pages of FreeBSD and OpenBSD. Signed-off-by: Tobias Stoeckmann <redacted> --- On Sun, May 18, 2025 at 10:15:54AM +0200, Alejandro Colomar wrote:
So, how about this? ERRORS See sprintf(3) and malloc(3).
Adjusted.
quoted
+.B EILSEQ +A wide-character code that does not correspond to a valid character +has been detected.I think this is because of "as-if" putwc(3). If so, I prefer deferring to it. Also, I see that POSIX documents this error, but why is that? These APIs don't handle wide-characters, do they?
Shortened here and in wprintf.3 as well.
The EILSEQ can occur with %ls or %S modifier, e.g.
printf("%ls\n", "\xFF")
or any other invalid sequence.
---
man/man3/asprintf.3 | 7 ++++++-
man/man3/printf.3 | 22 +++++++++++++++++++++-
man/man3/wprintf.3 | 21 ++++++++++++++++++++-
3 files changed, 47 insertions(+), 3 deletions(-)
diff --git a/man/man3/asprintf.3 b/man/man3/asprintf.3
index 319382c3a..e175306f6 100644
--- a/man/man3/asprintf.3
+++ b/man/man3/asprintf.3@@ -38,9 +38,14 @@ When successful, these functions return the number of bytes printed, just like .BR sprintf (3). If memory allocation wasn't possible, or some other error occurs, -these functions will return \-1, and the contents of +these functions will return \-1, set errno, and the contents of .I strp are undefined. +.SH ERRORS +See +.BR sprintf (3) +and +.BR malloc (3). .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
diff --git a/man/man3/printf.3 b/man/man3/printf.3
index b6e4f38b9..09737fd23 100644
--- a/man/man3/printf.3
+++ b/man/man3/printf.3@@ -904,7 +904,27 @@ Thus, a return value of or more means that the output was truncated. (See also below under CAVEATS.) .P -If an output error is encountered, a negative value is returned. +If an output error is encountered, a negative value is returned and +errno is set. +.SH ERRORS +See +.BR write (2) +and +.BR putwc (3). +In addition, the following error may occur: +.TP 10 +.B EOVERFLOW +The value to be returned is greater than +.BR INT_MAX . +.P +The +.BR dprintf () +function may fail additionally if: +.TP +.B EBADF +The +.IR fd +argument is not a valid file descriptor. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
diff --git a/man/man3/wprintf.3 b/man/man3/wprintf.3
index 59a6cfe07..583089e94 100644
--- a/man/man3/wprintf.3
+++ b/man/man3/wprintf.3@@ -198,7 +198,26 @@ case of the functions .BR swprintf () and .BR vswprintf (). -They return \-1 when an error occurs. +They return \-1 when an error occurs and set errno. +.SH ERRORS +See +.BR write (2) +and +.BR putwc (3). +In addition, the following error may occur: +.TP 10 +.B EOVERFLOW +The value to be returned is greater than +.BR INT_MAX . +.P +The +.BR fwprintf () +and +.BR wprintf () +functions may fail additionally if: +.TP +.B ENOMEM +Insufficient storage space is available. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
--
2.49.0