diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index ae82c4dd4..99f5236b8 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -47,57 +47,207 @@ curl_mvsprintf - formatted output conversion .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 curl_mprintf() -Normal printf() clone. +.B # +The value should be converted to its "alternate form". .TP -.B curl_mfprintf() -Normal fprintf() clone. +.B 0 +The value should be zero padded. .TP -.B curl_msprintf() -Normal sprintf() clone. +.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 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 ' ' +(a space) A blank should be left before a positive number (or empty string) +produced by a signed conversion. .TP -.B curl_mvprintf() -Normal vprintf() clone. +.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 curl_mvfprintf() -Normal vfprintf() clone. +.B h +A following integer conversion corresponds to a \fIshort\fP or \fIunsigned +short\fP argument. .TP -.B curl_mvsprintf() -Normal vsprintf() clone. +.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 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 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 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 q +A synonym for \fBll\fP. .TP -.B curl_mvaprintf() -Like curl_maprintf() but takes a va_list pointer argument instead of a -variable amount of arguments. -.RE +.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 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) "