mirror of
https://codeberg.org/kiss-community/repo
synced 2024-11-20 05:30:11 -07:00
217 lines
10 KiB
Groff
217 lines
10 KiB
Groff
.\" generated by cd2nroff 0.1 from curl_mprintf.md
|
|
.TH curl_printf 3 "March 15 2024" libcurl
|
|
.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 (\(aq0\(aq)) 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
|
|
\fIva_list\fP instead of a variable number of arguments. These functions do
|
|
not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro,
|
|
the value of \fIap\fP 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 \(aq*\(aq (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 \(aq%\(aq and "*m$" instead
|
|
of \(aq*\(aq, where the decimal integer m denotes the position in the argument list
|
|
of the desired argument, indexed starting from 1. Thus,
|
|
.nf
|
|
curl_mprintf("%*d", width, num);
|
|
.fi
|
|
and
|
|
.nf
|
|
curl_mprintf("%2$*1$d", width, num);
|
|
.fi
|
|
are equivalent. The second style allows repeated references to the same
|
|
argument.
|
|
|
|
If the style using \(aq$\(aq 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 arguments specified using \(aq$\(aq; 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:
|
|
.IP #
|
|
The value should be converted to its "alternate form".
|
|
.IP 0
|
|
The value should be zero padded.
|
|
.IP -
|
|
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 \(aq\-\(aq overrides a &\(aq0\(aq
|
|
if both are given.
|
|
.IP (space)
|
|
(a space: \(aq \(aq) A blank should be left before a positive number (or empty
|
|
string) produced by a signed conversion.
|
|
.IP +
|
|
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 \(aq+\(aq
|
|
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 gets 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 "\fI" or "\fPm$" (for some decimal integer m) to specify that the field
|
|
width is given in the next argument, or in the \fIm\-th\fP argument,
|
|
respectively, which must be of type int. A negative field width is taken as
|
|
a \(aq\-\(aq 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 (\(aq.\(aq) 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 \fIm\-th\fP argument, respectively, which must be of
|
|
type int. If the precision is given as just \(aq.\(aq, 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
|
|
.IP h
|
|
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP
|
|
argument.
|
|
.IP 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
|
|
.IP 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.
|
|
.IP q
|
|
A synonym for \fBll\fP.
|
|
.IP L
|
|
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
|
|
argument.
|
|
.IP 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:
|
|
.IP "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.
|
|
.IP "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
|
|
\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP 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.
|
|
.IP "e, E"
|
|
The double argument is rounded and output in the style \fB"[\-]d.ddde±dd"\fP
|
|
.IP "f, F"
|
|
The double argument is rounded and output to decimal notation in the style
|
|
\fB"[\-]ddd.ddd"\fP.
|
|
.IP "g, G"
|
|
The double argument is converted in style f or e.
|
|
.IP c
|
|
The int argument is converted to an unsigned char, and the resulting character
|
|
is written.
|
|
.IP s
|
|
The \fIconst char \fP* 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.
|
|
.IP p
|
|
The \fIvoid \fP* pointer argument is printed in hexadecimal.
|
|
.IP n
|
|
The number of characters written so far is stored into the integer pointed to
|
|
by the corresponding argument.
|
|
.IP %
|
|
A \(aq%\(aq symbol is written. No argument is converted.
|
|
.SH EXAMPLE
|
|
.nf
|
|
const char *name = "John";
|
|
|
|
int main(void)
|
|
{
|
|
curl_mprintf("My name is %s\\n", name);
|
|
curl_mprintf("Pi is almost %f\\n", (double)25.0/8);
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
These functions might 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 fprintf (3),
|
|
.BR printf (3),
|
|
.BR sprintf (3),
|
|
.BR vprintf (3)
|