| Message ID | ee9cf3da5de1061185fb267810b9bb8c45880a4a.1722855793.git.fweimer@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | [1/2] manual: Document generic printf error codes | expand |
On 8/5/24 7:03 AM, Florian Weimer wrote: LGTM. Reviewed-by: Carlos O'Donell <carlos@redhat.com> > --- > manual/stdio.texi | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/manual/stdio.texi b/manual/stdio.texi > index f9529a098d..83478460f8 100644 > --- a/manual/stdio.texi > +++ b/manual/stdio.texi > @@ -2363,6 +2363,29 @@ the easiest way to make sure you have all the right prototypes is to > just include @file{stdio.h}. > @pindex stdio.h > > +The @code{printf} family shares the error codes listed below. > +Individual functions may report additional @code{errno} values if they > +fail. > + > +@table @code > +@item EOVERFLOW > +The number of written bytes would have exceeded @code{INT_MAX}, and thus > +could not be represented in the return type @code{int}. OK. > + > +@item ENOMEM > +The function could not allocate memory during processing. Long argument > +lists and certain floating point conversions may require memory > +allocation, as does initialization of an output stream upon first use. OK. > + > +@item EILSEQ > +POSIX specifies this error code should be used if a wide character is > +encountered that does not have a matching valid character. @Theglibc{} > +always performs transliteration, using a replacement character if > +necessary, so this error condition cannot occur on output. However, > +@theglibc{} uses @code{EILSEQ} to indicate that an input character > +sequence (wide or multi-byte) could not be converted successfully. > +@end table OK. > + > @deftypefun int printf (const char *@var{template}, @dots{}) > @standards{ISO, stdio.h} > @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} > > base-commit: 7a630f7d3392ca391a399486ce2846f9e4b4ee63
On Mon, 12 Aug 2024, Carlos O'Donell wrote: > LGTM. > > Reviewed-by: Carlos O'Donell <carlos@redhat.com> Do our rules permit empty change descriptions? For the other change in this series there may be little to add there (though I'd strive anyway if I were the author), but I think here the change deserves at least listing the error codes documented, say: Document the use of EOVERFLOW, ENOMEM, and EILSEQ by the 'printf' family of formatted output functions. so that someone who does `git log' over the repo does not have to request `-p' as well to see what the change is all about. FWIW, Maciej
* Maciej W. Rozycki: > On Mon, 12 Aug 2024, Carlos O'Donell wrote: > >> LGTM. >> >> Reviewed-by: Carlos O'Donell <carlos@redhat.com> > > Do our rules permit empty change descriptions? For the other change in > this series there may be little to add there (though I'd strive anyway if > I were the author), but I think here the change deserves at least listing > the error codes documented, say: > > Document the use of EOVERFLOW, ENOMEM, and EILSEQ by the 'printf' family > of formatted output functions. I'll mention EOVERFLOW, ENOMEM, EILSEQ in the commit message. Thanks, Florian
diff --git a/manual/stdio.texi b/manual/stdio.texi index f9529a098d..83478460f8 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -2363,6 +2363,29 @@ the easiest way to make sure you have all the right prototypes is to just include @file{stdio.h}. @pindex stdio.h +The @code{printf} family shares the error codes listed below. +Individual functions may report additional @code{errno} values if they +fail. + +@table @code +@item EOVERFLOW +The number of written bytes would have exceeded @code{INT_MAX}, and thus +could not be represented in the return type @code{int}. + +@item ENOMEM +The function could not allocate memory during processing. Long argument +lists and certain floating point conversions may require memory +allocation, as does initialization of an output stream upon first use. + +@item EILSEQ +POSIX specifies this error code should be used if a wide character is +encountered that does not have a matching valid character. @Theglibc{} +always performs transliteration, using a replacement character if +necessary, so this error condition cannot occur on output. However, +@theglibc{} uses @code{EILSEQ} to indicate that an input character +sequence (wide or multi-byte) could not be converted successfully. +@end table + @deftypefun int printf (const char *@var{template}, @dots{}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}