[PATCH 2/2] manual: Document dprintf and vdprintf

[Carlos O'Donell]

On 8/5/24 7:03 AM, Florian Weimer wrote:

LGTM.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> ---
>  manual/stdio.texi | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
> 
> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index 83478460f8..dd9ee58642 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -2532,6 +2532,26 @@ store the result in which case @code{-1} is returned.  This was
>  changed in order to comply with the @w{ISO C99} standard.
>  @end deftypefun
>  
> +@deftypefun dprintf (int @var{fd}, @var{template}, ...)
> +@standards{POSIX, stdio.h}
> +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> +This function formats its arguments according to @var{template} and
> +writes the result to the file descriptor @var{fd}, using the
> +@code{write} function.  It returns the number of bytes written, or a
> +negative value if there was an error.  In the error case, @code{errno}
> +is set appropriately.  The possible @code{errno} values depend on the
> +type of the file descriptor @var{fd}, in addition to the general
> +@code{printf} error codes.
> +
> +The number of calls to @code{write} is unspecified, and some @code{write}
> +calls may have happened even if @code{dprintf} returns with an error.
> +
> +@strong{Portability Note:} POSIX does not require that this function is
> +async-signal-safe, and @theglibc{} implementation is not.  However, some
> +other systems offer this function as an async-signal-safe alternative to
> +@code{fprintf}.  @xref{POSIX Safety Concepts}.
> +@end deftypefun

OK.

> +
>  @node Dynamic Output
>  @subsection Dynamically Allocating Formatted Output
>  
> @@ -2745,6 +2765,13 @@ The @code{obstack_vprintf} function is the equivalent of
>  as for @code{vprintf}.
>  @end deftypefun
>  
> +@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap})
> +@standards{POSIX, stdio.h}
> +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> +The @code{vdprintf} is the equivalent of @code{dprintf}, but processes
> +an argument list.
> +@end deftypefun

OK.

> +
>  Here's an example showing how you might use @code{vfprintf}.  This is a
>  function that prints error messages to the stream @code{stderr}, along
>  with a prefix indicating the name of the program

-- 
Cheers,
Carlos.