|
|
.\" **************************************************************************
|
|
|
.\" * _ _ ____ _
|
|
|
.\" * Project ___| | | | _ \| |
|
|
|
.\" * / __| | | | |_) | |
|
|
|
.\" * | (__| |_| | _ <| |___
|
|
|
.\" * \___|\___/|_| \_\_____|
|
|
|
.\" *
|
|
|
.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
|
.\" *
|
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
|
.\" * you should have received as part of this distribution. The terms
|
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
|
.\" *
|
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
|
.\" *
|
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
|
.\" * KIND, either express or implied.
|
|
|
.\" *
|
|
|
.\" **************************************************************************
|
|
|
.TH curl_printf 3 "November 26, 2021" "libcurl 7.83.1" "libcurl Manual"
|
|
|
|
|
|
.SH NAME
|
|
|
curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf
|
|
|
curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
|
|
|
curl_mvsprintf - formatted output conversion
|
|
|
.SH SYNOPSIS
|
|
|
.nf
|
|
|
#include <curl/mprintf.h>
|
|
|
|
|
|
int curl_mprintf(const char *format, ...);
|
|
|
int curl_mfprintf(FILE *fd, const char *format, ...);
|
|
|
int curl_msprintf(char *buffer, const char *format, ...);
|
|
|
int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...);
|
|
|
int curl_mvprintf(const char *format, va_list args);
|
|
|
int curl_mvfprintf(FILE *fd, const char *format, va_list args);
|
|
|
int curl_mvsprintf(char *buffer, const char *format, va_list args);
|
|
|
int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format,
|
|
|
va_list args);
|
|
|
char *curl_maprintf(const char *format , ...);
|
|
|
char *curl_mvaprintf(const char *format, va_list args);
|
|
|
.fi
|
|
|
.SH DESCRIPTION
|
|
|
These functions produce output according to the format string and given
|
|
|
arguments. They are mostly clones of the well-known C-style functions but
|
|
|
there are slight differences in behavior.
|
|
|
|
|
|
We discourage users from using any of these functions in new applications.
|
|
|
|
|
|
Functions in the curl_mprintf() family produce output according to a format as
|
|
|
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
|
|
|
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
|
|
|
\fBcurl_mvfprintf()\fP write output to the given output stream;
|
|
|
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
|
|
|
\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP.
|
|
|
|
|
|
The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most
|
|
|
\fImaxlength\fP bytes (including the terminating null byte ('\\0')) to
|
|
|
\fIbuffer\fP.
|
|
|
|
|
|
The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
|
|
|
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
|
|
|
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
|
|
|
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
|
|
|
va_list instead of a variable number of arguments. These functions do not
|
|
|
call the va_end macro. Because they invoke the va_arg macro, the value of ap
|
|
|
is undefined after the call.
|
|
|
|
|
|
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
|
|
|
output string as pointer to a newly allocated memory area. The returned string
|
|
|
must be \fIcurl_free(3)\fPed by the receiver.
|
|
|
|
|
|
All of these functions write the output under the control of a format string
|
|
|
that specifies how subsequent arguments are converted for output.
|
|
|
|
|
|
.SH FORMAT STRING
|
|
|
The format string is composed of zero or more directives: ordinary characters
|
|
|
(not %), which are copied unchanged to the output stream; and conversion
|
|
|
specifications, each of which results in fetching zero or more subsequent
|
|
|
arguments. Each conversion specification is introduced by the character %, and
|
|
|
ends with a conversion specifier. In between there may be (in this order) zero
|
|
|
or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
|
|
|
\fIprecision\fP and an optional \fIlength modifier\fP.
|
|
|
|
|
|
.SH "The $ modifier"
|
|
|
The arguments must correspond properly with the conversion specifier. By
|
|
|
default, the arguments are used in the order given, where each '*' (see Field
|
|
|
width and Precision below) and each conversion specifier asks for the next
|
|
|
argument (and it is an error if insufficiently many arguments are given). One
|
|
|
can also specify explicitly which argument is taken, at each place where an
|
|
|
argument is required, by writing "%m$" instead of '%' and "*m$" instead
|
|
|
of '*', where the decimal integer m denotes the position in the argument list
|
|
|
of the desired argument, indexed starting from 1. Thus,
|
|
|
|
|
|
curl_mprintf("%*d", width, num);
|
|
|
|
|
|
and
|
|
|
|
|
|
curl_mprintf("%2$*1$d", width, num);
|
|
|
|
|
|
are equivalent. The second style allows repeated references to the same
|
|
|
argument.
|
|
|
|
|
|
If the style using '$' is used, it must be used throughout for all conversions
|
|
|
taking an argument and all width and precision arguments, but it may be mixed
|
|
|
with "%%" formats, which do not consume an argument. There may be no gaps in
|
|
|
the numbers of argu‐ ments specified using '$'; for example, if arguments 1
|
|
|
and 3 are specified, argument 2 must also be specified somewhere in the format
|
|
|
string.
|
|
|
|
|
|
.SH "Flag characters"
|
|
|
The character % is followed by zero or more of the following flags:
|
|
|
.TP
|
|
|
.B #
|
|
|
The value should be converted to its "alternate form".
|
|
|
.TP
|
|
|
.B 0
|
|
|
The value should be zero padded.
|
|
|
.TP
|
|
|
.B -
|
|
|
The converted value is to be left adjusted on the field boundary. (The
|
|
|
default is right justification.) The converted value is padded on the right
|
|
|
with blanks, rather than on the left with blanks or zeros. A '-' overrides a
|
|
|
\&'0' if both are given.
|
|
|
.TP
|
|
|
.B ' '
|
|
|
(a space) A blank should be left before a positive number (or empty string)
|
|
|
produced by a signed conversion.
|
|
|
.TP
|
|
|
.B +
|
|
|
A sign (+ or -) should always be placed before a number produced by a signed
|
|
|
conversion. By default, a sign is used only for negative numbers. A '+'
|
|
|
overrides a space if both are used.
|
|
|
.SH "Field width"
|
|
|
An optional decimal digit string (with nonzero first digit) specifying a
|
|
|
minimum field width. If the converted value has fewer characters than the
|
|
|
field width, it will be padded with spaces on the left (or right, if the
|
|
|
left-adjustment flag has been given). Instead of a decimal digit string one
|
|
|
may write "*" or "*m$" (for some decimal integer m) to specify that the field
|
|
|
width is given in the next argument, or in the m-th argument, respec‐ tively,
|
|
|
which must be of type int. A negative field width is taken as a '-' flag
|
|
|
followed by a positive field width. In no case does a nonexistent or small
|
|
|
field width cause truncation of a field; if the result of a conversion is
|
|
|
wider than the field width, the field is expanded to contain the conversion
|
|
|
result.
|
|
|
.SH "Precision"
|
|
|
An optional precision in the form of a period ('.') followed by an optional
|
|
|
decimal digit string. Instead of a decimal digit string one may write "*" or
|
|
|
"*m$" (for some decimal integer m) to specify that the precision is given in
|
|
|
the next argument, or in the m-th argument, respectively, which must be of
|
|
|
type int. If the precision is given as just '.', the precision is taken to be
|
|
|
zero. A negative precision is taken as if the precision were omitted. This
|
|
|
gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP,
|
|
|
\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear
|
|
|
after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and
|
|
|
\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and
|
|
|
\fBG\fP conversions, or the maximum number of characters to be printed from a
|
|
|
string for \fBs\fP and \fBS\fP conversions.
|
|
|
.SH "Length modifier"
|
|
|
.TP
|
|
|
.B h
|
|
|
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
|
|
|
short\fP argument.
|
|
|
.TP
|
|
|
.B l
|
|
|
(ell) A following integer conversion corresponds to a \fIlong\fP or
|
|
|
\fIunsigned long\fP argument, or a following n conversion corresponds to a
|
|
|
pointer to a long argument
|
|
|
.TP
|
|
|
.B ll
|
|
|
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
|
|
|
\fIunsigned long long\fP argument, or a following n conversion corresponds to
|
|
|
a pointer to a long long argument.
|
|
|
.TP
|
|
|
.B q
|
|
|
A synonym for \fBll\fP.
|
|
|
.TP
|
|
|
.B L
|
|
|
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
|
|
|
argument.
|
|
|
.TP
|
|
|
.B z
|
|
|
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
|
|
|
argument.
|
|
|
.SH "Conversion specifiers"
|
|
|
A character that specifies the type of conversion to be applied. The
|
|
|
conversion specifiers and their meanings are:
|
|
|
.TP
|
|
|
.B d, i
|
|
|
The int argument is converted to signed decimal notation. The precision, if
|
|
|
any, gives the minimum number of digits that must appear; if the converted
|
|
|
value requires fewer digits, it is padded on the left with zeros. The default
|
|
|
precision is 1. When 0 is printed with an explicit precision 0, the output is
|
|
|
empty.
|
|
|
.TP
|
|
|
.B o, u, x, X
|
|
|
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
|
|
|
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
|
|
|
abcdef are used for \fBx\fP conversions; the letters ABCDEF are used for
|
|
|
\fBX\fP conversions. The precision, if any, gives the minimum number of digits
|
|
|
that must appear; if the converted value requires fewer digits, it is padded
|
|
|
on the left with zeros. The default precision is 1. When 0 is printed with
|
|
|
an explicit precision 0, the output is empty.
|
|
|
.TP
|
|
|
.B e, E
|
|
|
The double argument is rounded and output in the style "[-]d.ddde±dd"
|
|
|
.TP
|
|
|
.B f, F
|
|
|
The double argument is rounded and output to decimal notiation in the style
|
|
|
[-]ddd.ddd.
|
|
|
.TP
|
|
|
.B g, G
|
|
|
The double argument is converted in style f or e.
|
|
|
.TP
|
|
|
.B c
|
|
|
The int argument is converted to an unsigned char, and the resulting character
|
|
|
is written.
|
|
|
.TP
|
|
|
.B s
|
|
|
The const char * argument is expected to be a pointer to an array of character
|
|
|
type (pointer to a string). Characters from the array are written up to (but
|
|
|
not including) a terminating null byte. If a precision is specified, no more
|
|
|
than the number specified are written. If a precision is given, no null byte
|
|
|
need be present; if the precision is not specified, or is greater than the
|
|
|
size of the array, the array must contain a terminating null byte.
|
|
|
.TP
|
|
|
.B p
|
|
|
The \fIvoid *\fP pointer argument is printed in hexadecimal.
|
|
|
.TP
|
|
|
.B n
|
|
|
The number of characters written so far is stored into the integer pointed to
|
|
|
by the corresponding argument.
|
|
|
.TP
|
|
|
.B %
|
|
|
A '%' is written. No argument is converted.
|
|
|
.SH EXAMPLE
|
|
|
.nf
|
|
|
mprintf("My name is %s\\n", name);
|
|
|
mprintf("Pi is almost %f\\n", 25/8);
|
|
|
.fi
|
|
|
.SH AVAILABILITY
|
|
|
These functions will be removed from the public libcurl API in the future. Do
|
|
|
not use them in new programs or projects.
|
|
|
.SH RETURN VALUE
|
|
|
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
|
|
|
a newly allocated string, or NULL if it failed.
|
|
|
|
|
|
All other functions return the number of characters actually printed
|
|
|
(excluding the null byte used to end output to strings). Note that this
|
|
|
sometimes differ from how the POSIX versions of these functions work.
|
|
|
.SH "SEE ALSO"
|
|
|
.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "
|
