| Message ID | xnplo6mp23.fsf@greed.delorie.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] manual: Document stdio.h functions that may be macros | expand |
On 10/11/24 3:12 PM, DJ Delorie wrote: > > Glibc has two gnu-extension functions that are implemented as > macros but not documented as such: fread_unlocked and > fwrite_unlocked. Document them as such. > > Additionally, putc_unlocked and getc_unlocked are documented in > POSIX as possibly being macros. Update the manual to add a warning > about those also, depite glibc not implementing them as macros. LGTM. Reviewed-by: Carlos O'Donell <carlos@redhat.com> > diff --git a/manual/stdio.texi b/manual/stdio.texi > index 75aee8ab08..83f4f92e3f 100644 > --- a/manual/stdio.texi > +++ b/manual/stdio.texi > @@ -929,6 +929,9 @@ Therefore, @var{stream} should never be an expression with side-effects. > @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} > The @code{putc_unlocked} function is equivalent to the @code{putc} > function except that it does not implicitly lock the stream. > +Like @code{putc}, it may be implemented as a macro and may evaluate > +the @var{stream} argument more than once. Therefore, @var{stream} > +should not be an expression with side-effects. OK. YEs, putc_unlocked. > @end deftypefun > > @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) > @@ -1132,6 +1135,9 @@ Therefore, @var{stream} should never be an expression with side-effects. > @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} > The @code{getc_unlocked} function is equivalent to the @code{getc} > function except that it does not implicitly lock the stream. > +Like @code{getc}, it may be implemented as a macro and may evaluate > +the @var{stream} argument more than once. Therefore, @var{stream} > +should not be an expression with side-effects. OK. Yes, getc_unlocked. > @end deftypefun > > @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) > @@ -1571,6 +1577,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} > function except that it does not implicitly lock the stream. > > This function is a GNU extension. > +This function may be implemented as a macro and may evaluate > +@var{stream} more than once. Therefore, @var{stream} should not be an > +expression with side-effects. OK. Yes, fread_unlocked. > @end deftypefun > > @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) > @@ -1589,6 +1598,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} > function except that it does not implicitly lock the stream. > > This function is a GNU extension. > +This function may be implemented as a macro and may evaluate > +@var{stream} more than once. Therefore, @var{stream} should not be an > +expression with side-effects. OK. Yes, frwrite_unlocked. > @end deftypefun > > @node Formatted Output >
diff --git a/manual/stdio.texi b/manual/stdio.texi index 75aee8ab08..83f4f92e3f 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -929,6 +929,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. +Like @code{putc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) @@ -1132,6 +1135,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. +Like @code{getc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) @@ -1571,6 +1577,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) @@ -1589,6 +1598,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @node Formatted Output