.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * 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
.br
.BI "char *curl_mvaprintf(const char *" format ", va_list " args ");"
.SH DESCRIPTION
-These are all functions that produce output according to a format string and
-given arguments. These are mostly clones of the well-known C-style functions
-and there will be no detailed explanation of all available formatting rules
-and usage here.
+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.
-See this table for notable exceptions.
-.RS
+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 curl_mprintf()
-Normal printf() clone.
+.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 curl_mfprintf()
-Normal fprintf() clone.
+.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 curl_msprintf()
-Normal sprintf() clone.
+.B e, E
+The double argument is rounded and output in the style "[-]d.ddde±dd"
.TP
-.B curl_msnprintf()
-snprintf() clone. Many systems don't have this. It is just like \fBsprintf\fP
-but with an extra argument after the buffer that specifies the length of the
-target buffer.
+.B f, F
+The double argument is rounded and output to decimal notiation in the style
+[-]ddd.ddd.
.TP
-.B curl_mvprintf()
-Normal vprintf() clone.
+.B g, G
+The double argument is converted in style f or e.
.TP
-.B curl_mvfprintf()
-Normal vfprintf() clone.
+.B c
+The int argument is converted to an unsigned char, and the resulting character
+is written.
.TP
-.B curl_mvsprintf()
-Normal vsprintf() clone.
+.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 curl_mvsnprintf()
-vsnprintf() clone. Many systems don't have this. It is just like
-\fBvsprintf\fP but with an extra argument after the buffer that specifies the
-length of the target buffer.
+.B p
+The \fIvoid *\fP pointer argument is printed in hexadecimal.
.TP
-.B curl_maprintf()
-Like printf() but returns the output string as a malloc()ed string. The
-returned string must be free()ed by the receiver.
+.B n
+The number of characters written so far is stored into the integer pointed to
+by the corresponding argument.
.TP
-.B curl_mvaprintf()
-Like curl_maprintf() but takes a va_list pointer argument instead of a
-variable amount of arguments.
-.RE
+.B %
+A '%' is written. No argument is converted.
.SH AVAILABILITY
These functions will be removed from the public libcurl API in the future. Do
-not use them in any new programs or projects.
+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 they actually outputted.
+All other functions return the number of characters they actually
+outputted. Note that this differs from how the POSIX versions of these
+functions work.
.SH "SEE ALSO"
.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "
projects / thirdparty / curl.git / commitdiff
