diff mbox series

[v1] manual: Document stdio.h functions that may be macros

Message ID xny12vmz3x.fsf@greed.delorie.com
State New
Headers show
Series [v1] manual: Document stdio.h functions that may be macros | expand

Commit Message

DJ Delorie Oct. 10, 2024, 9:23 p.m. UTC 
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.

The entry for putc looked like it was copied from getc and only
mentioned one of the two arguments; update it.

Comments

Florian Weimer Oct. 10, 2024, 9:56 p.m. UTC | #1 
* DJ Delorie:

> 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.

We should use __extern_inline instead of a macro, given that these two
functions are outliers.  Or even better, optimize the libc.so
implementation to use memcpy, and remove the inline stuff altogether.

> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index c7a2b4a9a1..fb27dfc6e9 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -911,9 +911,10 @@ This function is a GNU extension.
>  @deftypefun int putc (int @var{c}, FILE *@var{stream})
>  @standards{ISO, stdio.h}
>  @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
> -This is just like @code{fputc}, except that it may be implemented as
> -a macro and may evaluate the @var{stream} argument more than once.
> -Therefore, @var{stream} should never be an expression with side-effects.
> +This is just like @code{fputc}, except that it may be implemented as a
> +macro and may evaluate its arguments more than once.  Therefore,
> +@var{c} and @var{stream} should never be expressions with
> +side-effects.
>  @end deftypefun

Why do you mention @var{c} here?  I think the standards only allow it
to be evaluated once.
diff mbox series

Patch

diff --git a/manual/stdio.texi b/manual/stdio.texi
index c7a2b4a9a1..fb27dfc6e9 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -911,9 +911,10 @@  This function is a GNU extension.
 @deftypefun int putc (int @var{c}, FILE *@var{stream})
 @standards{ISO, stdio.h}
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
-This is just like @code{fputc}, except that it may be implemented as
-a macro and may evaluate the @var{stream} argument more than once.
-Therefore, @var{stream} should never be an expression with side-effects.
+This is just like @code{fputc}, except that it may be implemented as a
+macro and may evaluate its arguments more than once.  Therefore,
+@var{c} and @var{stream} should never be expressions with
+side-effects.
 @end deftypefun
 
 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
@@ -929,6 +930,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
+its arguments more than once.  Therefore, @var{c} and @var{stream}
+should never be expressions with side-effects.
 @end deftypefun
 
 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
@@ -1132,6 +1136,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 never be an expression with side-effects.
 @end deftypefun
 
 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
@@ -1571,6 +1578,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 its
+arguments more than once.  Therefore, these arguments should never be
+expressions 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 +1599,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 its
+arguments more than once.  Therefore, these arguments should never be
+expressions with side-effects.
 @end deftypefun
 
 @node Formatted Output