curl_mprintf.md (10122B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: curl_printf 5 Section: 3 6 Source: libcurl 7 See-also: 8 - fprintf (3) 9 - printf (3) 10 - sprintf (3) 11 - vprintf (3) 12 Protocol: 13 - All 14 Added-in: 7.1 15 --- 16 17 # NAME 18 19 curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf, 20 curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, 21 curl_mvsprintf - formatted output conversion 22 23 # SYNOPSIS 24 25 ~~~c 26 #include <curl/mprintf.h> 27 28 int curl_mprintf(const char *format, ...); 29 int curl_mfprintf(FILE *fd, const char *format, ...); 30 int curl_msprintf(char *buffer, const char *format, ...); 31 int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...); 32 int curl_mvprintf(const char *format, va_list args); 33 int curl_mvfprintf(FILE *fd, const char *format, va_list args); 34 int curl_mvsprintf(char *buffer, const char *format, va_list args); 35 int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format, 36 va_list args); 37 char *curl_maprintf(const char *format , ...); 38 char *curl_mvaprintf(const char *format, va_list args); 39 ~~~ 40 41 # DESCRIPTION 42 43 These functions produce output according to the format string and given 44 arguments. They are mostly clones of the well-known C-style functions but 45 there are slight differences in behavior. 46 47 We discourage users from using any of these functions in new applications. 48 49 Functions in the curl_mprintf() family produce output according to a format as 50 described below. The functions **curl_mprintf()** and **curl_mvprintf()** 51 write output to stdout, the standard output stream; **curl_mfprintf()** and 52 **curl_mvfprintf()** write output to the given output stream; 53 **curl_msprintf()**, **curl_msnprintf()**, **curl_mvsprintf()**, and 54 **curl_mvsnprintf()** write to the character string **buffer**. 55 56 The functions **curl_msnprintf()** and **curl_mvsnprintf()** write at most 57 *maxlength* bytes (including the terminating null byte ('0')) to 58 *buffer*. 59 60 The functions **curl_mvprintf()**, **curl_mvfprintf()**, 61 **curl_mvsprintf()**, **curl_mvsnprintf()** are equivalent to the 62 functions **curl_mprintf()**, **curl_mfprintf()**, **curl_msprintf()**, 63 **curl_msnprintf()**, respectively, except that they are called with a 64 *va_list* instead of a variable number of arguments. These functions do 65 not call the *va_end* macro. Because they invoke the *va_arg* macro, 66 the value of *ap* is undefined after the call. 67 68 The functions **curl_maprintf()** and **curl_mvaprintf()** return the 69 output string as pointer to a newly allocated memory area. The returned string 70 must be curl_free(3)ed by the receiver. 71 72 All of these functions write the output under the control of a format string 73 that specifies how subsequent arguments are converted for output. 74 75 # FORMAT STRING 76 77 The format string is composed of zero or more directives: ordinary characters 78 (not %), which are copied unchanged to the output stream; and conversion 79 specifications, each of which results in fetching zero or more subsequent 80 arguments. Each conversion specification is introduced by the character %, and 81 ends with a conversion specifier. In between there may be (in this order) zero 82 or more *flags*, an optional minimum *field width*, an optional 83 *precision* and an optional *length modifier*. 84 85 # The $ modifier 86 87 The arguments must correspond properly with the conversion specifier. By 88 default, the arguments are used in the order given, where each '*' (see Field 89 width and Precision below) and each conversion specifier asks for the next 90 argument (and it is an error if insufficiently many arguments are given). One 91 can also specify explicitly which argument is taken, at each place where an 92 argument is required, by writing "%m$" instead of '%' and "*m$" instead 93 of '*', where the decimal integer m denotes the position in the argument list 94 of the desired argument, indexed starting from 1. Thus, 95 ~~~c 96 curl_mprintf("%*d", width, num); 97 ~~~ 98 and 99 ~~~c 100 curl_mprintf("%2$*1$d", width, num); 101 ~~~ 102 are equivalent. The second style allows repeated references to the same 103 argument. 104 105 If the style using '$' is used, it must be used throughout for all conversions 106 taking an argument and all width and precision arguments, but it may be mixed 107 with "%%" formats, which do not consume an argument. There may be no gaps in 108 the numbers of arguments specified using '$'; for example, if arguments 1 and 109 3 are specified, argument 2 must also be specified somewhere in the format 110 string. 111 112 # Flag characters 113 114 The character % is followed by zero or more of the following flags: 115 116 ## # 117 118 The value should be converted to its "alternate form". 119 120 ## 0 121 122 The value should be zero padded. 123 124 ## - 125 126 The converted value is to be left adjusted on the field boundary. (The default 127 is right justification.) The converted value is padded on the right with 128 blanks, rather than on the left with blanks or zeros. A '-' overrides a &'0' 129 if both are given. 130 131 ## (space) 132 133 (a space: ' ') A blank should be left before a positive number (or empty 134 string) produced by a signed conversion. 135 136 ## + 137 138 A sign (+ or -) should always be placed before a number produced by a signed 139 conversion. By default, a sign is used only for negative numbers. A '+' 140 overrides a space if both are used. 141 142 # Field width 143 144 An optional decimal digit string (with nonzero first digit) specifying a 145 minimum field width. If the converted value has fewer characters than the 146 field width, it gets padded with spaces on the left (or right, if the 147 left-adjustment flag has been given). Instead of a decimal digit string one 148 may write "*" or "*m$" (for some decimal integer m) to specify that the field 149 width is given in the next argument, or in the *m-th* argument, 150 respectively, which must be of type int. A negative field width is taken as 151 a '-' flag followed by a positive field width. In no case does a nonexistent 152 or small field width cause truncation of a field; if the result of a 153 conversion is wider than the field width, the field is expanded to contain the 154 conversion result. 155 156 # Precision 157 158 An optional precision in the form of a period ('.') followed by an optional 159 decimal digit string. Instead of a decimal digit string one may write "*" or 160 "*m$" (for some decimal integer m) to specify that the precision is given in 161 the next argument, or in the *m-th* argument, respectively, which must be of 162 type int. If the precision is given as just '.', the precision is taken to be 163 zero. A negative precision is taken as if the precision were omitted. This 164 gives the minimum number of digits to appear for **d**, **i**, **o**, 165 **u**, **x**, and **X** conversions, the number of digits to appear 166 after the radix character for **a**, **A**, **e**, **E**, **f**, and 167 **F** conversions, the maximum number of significant digits for **g** and 168 **G** conversions, or the maximum number of characters to be printed from a 169 string for **s** and **S** conversions. 170 171 # Length modifier 172 173 ## h 174 175 A following integer conversion corresponds to a *short* or *unsigned short* 176 argument. 177 178 ## l 179 180 (ell) A following integer conversion corresponds to a *long* or 181 *unsigned long* argument, or a following n conversion corresponds to a 182 pointer to a long argument 183 184 ## ll 185 186 (ell-ell). A following integer conversion corresponds to a *long long* or 187 *unsigned long long* argument, or a following n conversion corresponds to 188 a pointer to a *long long* argument. 189 190 ## q 191 192 A synonym for **ll**. 193 194 ## L 195 196 A following a, A, e, E, f, F, g, or G conversion corresponds to a long double 197 argument. 198 199 ## z 200 201 A following integer conversion corresponds to a *size_t* or *ssize_t* 202 argument. 203 204 # Conversion specifiers 205 206 A character that specifies the type of conversion to be applied. The 207 conversion specifiers and their meanings are: 208 209 ## d, i 210 211 The int argument is converted to signed decimal notation. The precision, if 212 any, gives the minimum number of digits that must appear; if the converted 213 value requires fewer digits, it is padded on the left with zeros. The default 214 precision is 1. When 0 is printed with an explicit precision 0, the output is 215 empty. 216 217 ## o, u, x, X 218 219 The unsigned int argument is converted to unsigned octal (o), unsigned decimal 220 (u), or unsigned hexadecimal (**x** and **X**) notation. The letters 221 *abcdef* are used for **x** conversions; the letters *ABCDEF* are 222 used for **X** conversions. The precision, if any, gives the minimum number 223 of digits that must appear; if the converted value requires fewer digits, it 224 is padded on the left with zeros. The default precision is 1. When 0 is 225 printed with an explicit precision 0, the output is empty. 226 227 ## e, E 228 229 The double argument is rounded and output in the style **"[-]d.ddde{+|-}dd"** 230 231 ## f, F 232 233 The double argument is rounded and output to decimal notation in the style 234 **"[-]ddd.ddd"**. 235 236 ## g, G 237 238 The double argument is converted in style f or e. 239 240 ## c 241 242 The int argument is converted to an unsigned char, and the resulting character 243 is written. 244 245 ## s 246 247 The *const char ** argument is expected to be a pointer to an array of 248 character type (pointer to a string). Characters from the array are written up 249 to (but not including) a terminating null byte. If a precision is specified, 250 no more than the number specified are written. If a precision is given, no 251 null byte need be present; if the precision is not specified, or is greater 252 than the size of the array, the array must contain a terminating null byte. 253 254 ## p 255 256 The *void ** pointer argument is printed in hexadecimal. 257 258 ## n 259 260 The number of characters written so far is stored into the integer pointed to 261 by the corresponding argument. 262 263 ## % 264 265 A '%' symbol is written. No argument is converted. 266 267 # %PROTOCOLS% 268 269 # EXAMPLE 270 271 ~~~c 272 const char *name = "John"; 273 274 int main(void) 275 { 276 curl_mprintf("My name is %s\n", name); 277 curl_mprintf("Pi is almost %f\n", (double)25.0/8); 278 } 279 ~~~ 280 281 # %AVAILABILITY% 282 283 # RETURN VALUE 284 285 The **curl_maprintf** and **curl_mvaprintf** functions return a pointer to 286 a newly allocated string, or NULL if it failed. 287 288 All other functions return the number of characters actually printed 289 (excluding the null byte used to end output to strings). Note that this 290 sometimes differ from how the POSIX versions of these functions work.