1 /** @file 2 Provides services to print a formatted string to a buffer. All combinations of 3 Unicode and ASCII strings are supported. 4 5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 The Print Library functions provide a simple means to produce formatted output 9 strings. Many of the output functions use a format string to describe how to 10 format the output of variable arguments. The format string consists of normal 11 text and argument descriptors. There are no restrictions for how the normal 12 text and argument descriptors can be mixed. The following end of line(EOL) 13 translations must be performed on the contents of the format string: 14 15 - '\\r' is translated to '\\r' 16 - '\\r\\n' is translated to '\\r\\n' 17 - '\\n' is translated to '\\r\\n' 18 - '\\n\\r' is translated to '\\r\\n' 19 20 This does not follow the ANSI C standard for sprint(). The format of argument 21 descriptors is described below. The ANSI C standard for sprint() has been 22 followed for some of the format types, and has not been followed for others. 23 The exceptions are noted below. 24 25 %[flags][width][.precision]type 26 27 [flags]: 28 - - 29 - The field is left justified. If not flag is not specified, then the 30 field is right justified. 31 - space 32 - Prefix a space character to a number. Only valid for types X, x, and d. 33 - + 34 - Prefix a plus character to a number. Only valid for types X, x, and d. 35 If both space and + are specified, then space is ignored. 36 - 0 37 - Pad with 0 characters to the left of a number. Only valid for types 38 X, x, and d. 39 - , 40 - Place a comma every 3rd digit of the number. Only valid for type d. 41 If 0 is also specified, then 0 is ignored. 42 - L, l 43 - The number being printed is size UINT64. Only valid for types X, x, and d. 44 If this flag is not specified, then the number being printed is size int. 45 - NOTE: All invalid flags are ignored. 46 47 [width]: 48 49 - * 50 - The width of the field is specified by a UINTN argument in the 51 argument list. 52 - number 53 - The number specified as a decimal value represents the width of 54 the field. 55 - NOTE: If [width] is not specified, then a field width of 0 is assumed. 56 57 [.precision]: 58 59 - * 60 - The precision of the field is specified by a UINTN argument in the 61 argument list. 62 - number 63 - The number specified as a decimal value represents the precision of 64 the field. 65 - NOTE: If [.precision] is not specified, then a precision of 0 is assumed. 66 67 type: 68 69 - % 70 - Print a %%. 71 - c 72 - The argument is a Unicode character. ASCII characters can be printed 73 using this type too by making sure bits 8..15 of the argument are set to 0. 74 - x 75 - The argument is an unsigned hexadecimal number. The characters used are 0..9 and 76 A..F. If the flag 'L' is not specified, then the argument is assumed 77 to be size int. This does not follow ANSI C. 78 - X 79 - The argument is an unsigned hexadecimal number and the number is padded with 80 zeros. This is equivalent to a format string of "0x". If the flag 81 'L' is not specified, then the argument is assumed to be size int. 82 This does not follow ANSI C. 83 - d 84 - The argument is a signed decimal number. If the flag 'L' is not specified, 85 then the argument is assumed to be size int. 86 - u 87 - The argument is a unsigned decimal number. If the flag 'L' is not specified, 88 then the argument is assumed to be size int. 89 - p 90 - The argument is a pointer that is a (VOID *), and it is printed as an 91 unsigned hexadecimal number The characters used are 0..9 and A..F. 92 - a 93 - The argument is a pointer to an ASCII string. 94 This does not follow ANSI C. 95 - S, s 96 - The argument is a pointer to a Unicode string. 97 This does not follow ANSI C. 98 - g 99 - The argument is a pointer to a GUID structure. The GUID is printed 100 in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. 101 This does not follow ANSI C. 102 - t 103 - The argument is a pointer to an EFI_TIME structure. The time and 104 date are printed in the format "mm/dd/yyyy hh:mm" where mm is the 105 month zero padded, dd is the day zero padded, yyyy is the year zero 106 padded, hh is the hour zero padded, and mm is minutes zero padded. 107 This does not follow ANSI C. 108 - r 109 - The argument is a RETURN_STATUS value. This value is converted to 110 a string following the table below. This does not follow ANSI C. 111 - RETURN_SUCCESS 112 - "Success" 113 - RETURN_LOAD_ERROR 114 - "Load Error" 115 - RETURN_INVALID_PARAMETER 116 - "Invalid Parameter" 117 - RETURN_UNSUPPORTED 118 - "Unsupported" 119 - RETURN_BAD_BUFFER_SIZE 120 - "Bad Buffer Size" 121 - RETURN_BUFFER_TOO_SMALL 122 - "Buffer Too Small" 123 - RETURN_NOT_READY 124 - "Not Ready" 125 - RETURN_DEVICE_ERROR 126 - "Device Error" 127 - RETURN_WRITE_PROTECTED 128 - "Write Protected" 129 - RETURN_OUT_OF_RESOURCES 130 - "Out of Resources" 131 - RETURN_VOLUME_CORRUPTED 132 - "Volume Corrupt" 133 - RETURN_VOLUME_FULL 134 - "Volume Full" 135 - RETURN_NO_MEDIA 136 - "No Media" 137 - RETURN_MEDIA_CHANGED 138 - "Media changed" 139 - RETURN_NOT_FOUND 140 - "Not Found" 141 - RETURN_ACCESS_DENIED 142 - "Access Denied" 143 - RETURN_NO_RESPONSE 144 - "No Response" 145 - RETURN_NO_MAPPING 146 - "No mapping" 147 - RETURN_TIMEOUT 148 - "Time out" 149 - RETURN_NOT_STARTED 150 - "Not started" 151 - RETURN_ALREADY_STARTED 152 - "Already started" 153 - RETURN_ABORTED 154 - "Aborted" 155 - RETURN_ICMP_ERROR 156 - "ICMP Error" 157 - RETURN_TFTP_ERROR 158 - "TFTP Error" 159 - RETURN_PROTOCOL_ERROR 160 - "Protocol Error" 161 - RETURN_WARN_UNKNOWN_GLYPH 162 - "Warning Unknown Glyph" 163 - RETURN_WARN_DELETE_FAILURE 164 - "Warning Delete Failure" 165 - RETURN_WARN_WRITE_FAILURE 166 - "Warning Write Failure" 167 - RETURN_WARN_BUFFER_TOO_SMALL 168 - "Warning Buffer Too Small" 169 170 **/ 171 172 #ifndef __PRINT_LIB_H__ 173 #define __PRINT_LIB_H__ 174 175 /// 176 /// Define the maximum number of characters that are required to 177 /// encode with a NULL terminator a decimal, hexadecimal, GUID, 178 /// or TIME value. 179 /// 180 /// Maximum Length Decimal String = 28 181 /// "-9,223,372,036,854,775,808" 182 /// Maximum Length Hexadecimal String = 17 183 /// "FFFFFFFFFFFFFFFF" 184 /// Maximum Length GUID = 37 185 /// "00000000-0000-0000-0000-000000000000" 186 /// Maximum Length TIME = 18 187 /// "12/12/2006 12:12" 188 /// 189 #define MAXIMUM_VALUE_CHARACTERS 38 190 191 /// 192 /// Flags bitmask values use in UnicodeValueToString() and 193 /// AsciiValueToString() 194 /// 195 #define LEFT_JUSTIFY 0x01 196 #define COMMA_TYPE 0x08 197 #define PREFIX_ZERO 0x20 198 #define RADIX_HEX 0x80 199 200 /** 201 Produces a Null-terminated Unicode string in an output buffer based on 202 a Null-terminated Unicode format string and a VA_LIST argument list. 203 204 This function is similar as vsnprintf_s defined in C11. 205 206 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 207 and BufferSize. 208 The Unicode string is produced by parsing the format string specified by FormatString. 209 Arguments are pulled from the variable argument list specified by Marker based on the 210 contents of the format string. 211 The number of Unicode characters in the produced output buffer is returned not including 212 the Null-terminator. 213 214 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 215 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 216 217 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 218 unmodified and 0 is returned. 219 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 220 unmodified and 0 is returned. 221 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 222 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 223 buffer is unmodified and 0 is returned. 224 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 225 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 226 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 227 228 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned. 229 230 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 231 Unicode string. 232 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 233 @param FormatString A Null-terminated Unicode format string. 234 @param Marker VA_LIST marker for the variable argument list. 235 236 @return The number of Unicode characters in the produced output buffer not including the 237 Null-terminator. 238 239 **/ 240 UINTN 241 EFIAPI 242 UnicodeVSPrint ( 243 OUT CHAR16 *StartOfBuffer, 244 IN UINTN BufferSize, 245 IN CONST CHAR16 *FormatString, 246 IN VA_LIST Marker 247 ); 248 249 /** 250 Produces a Null-terminated Unicode string in an output buffer based on 251 a Null-terminated Unicode format string and a BASE_LIST argument list. 252 253 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 254 and BufferSize. 255 The Unicode string is produced by parsing the format string specified by FormatString. 256 Arguments are pulled from the variable argument list specified by Marker based on the 257 contents of the format string. 258 The number of Unicode characters in the produced output buffer is returned not including 259 the Null-terminator. 260 261 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 262 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 263 264 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 265 unmodified and 0 is returned. 266 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 267 unmodified and 0 is returned. 268 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 269 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 270 buffer is unmodified and 0 is returned. 271 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 272 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 273 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 274 275 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned. 276 277 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 278 Unicode string. 279 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 280 @param FormatString A Null-terminated Unicode format string. 281 @param Marker BASE_LIST marker for the variable argument list. 282 283 @return The number of Unicode characters in the produced output buffer not including the 284 Null-terminator. 285 286 **/ 287 UINTN 288 EFIAPI 289 UnicodeBSPrint ( 290 OUT CHAR16 *StartOfBuffer, 291 IN UINTN BufferSize, 292 IN CONST CHAR16 *FormatString, 293 IN BASE_LIST Marker 294 ); 295 296 /** 297 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 298 Unicode format string and variable argument list. 299 300 This function is similar as snprintf_s defined in C11. 301 302 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 303 and BufferSize. 304 The Unicode string is produced by parsing the format string specified by FormatString. 305 Arguments are pulled from the variable argument list based on the contents of the format string. 306 The number of Unicode characters in the produced output buffer is returned not including 307 the Null-terminator. 308 309 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 310 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 311 312 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 313 unmodified and 0 is returned. 314 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 315 unmodified and 0 is returned. 316 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 317 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 318 buffer is unmodified and 0 is returned. 319 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 320 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 321 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 322 323 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned. 324 325 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 326 Unicode string. 327 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 328 @param FormatString A Null-terminated Unicode format string. 329 @param ... Variable argument list whose contents are accessed based on the 330 format string specified by FormatString. 331 332 @return The number of Unicode characters in the produced output buffer not including the 333 Null-terminator. 334 335 **/ 336 UINTN 337 EFIAPI 338 UnicodeSPrint ( 339 OUT CHAR16 *StartOfBuffer, 340 IN UINTN BufferSize, 341 IN CONST CHAR16 *FormatString, 342 ... 343 ); 344 345 /** 346 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 347 ASCII format string and a VA_LIST argument list. 348 349 This function is similar as vsnprintf_s defined in C11. 350 351 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 352 and BufferSize. 353 The Unicode string is produced by parsing the format string specified by FormatString. 354 Arguments are pulled from the variable argument list specified by Marker based on the 355 contents of the format string. 356 The number of Unicode characters in the produced output buffer is returned not including 357 the Null-terminator. 358 359 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 360 361 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 362 unmodified and 0 is returned. 363 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 364 unmodified and 0 is returned. 365 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 366 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 367 buffer is unmodified and 0 is returned. 368 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 369 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 370 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 371 372 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 373 374 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 375 Unicode string. 376 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 377 @param FormatString A Null-terminated ASCII format string. 378 @param Marker VA_LIST marker for the variable argument list. 379 380 @return The number of Unicode characters in the produced output buffer not including the 381 Null-terminator. 382 383 **/ 384 UINTN 385 EFIAPI 386 UnicodeVSPrintAsciiFormat ( 387 OUT CHAR16 *StartOfBuffer, 388 IN UINTN BufferSize, 389 IN CONST CHAR8 *FormatString, 390 IN VA_LIST Marker 391 ); 392 393 /** 394 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 395 ASCII format string and a BASE_LIST argument list. 396 397 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 398 and BufferSize. 399 The Unicode string is produced by parsing the format string specified by FormatString. 400 Arguments are pulled from the variable argument list specified by Marker based on the 401 contents of the format string. 402 The number of Unicode characters in the produced output buffer is returned not including 403 the Null-terminator. 404 405 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 406 407 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 408 unmodified and 0 is returned. 409 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 410 unmodified and 0 is returned. 411 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 412 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 413 buffer is unmodified and 0 is returned. 414 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 415 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 416 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 417 418 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 419 420 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 421 Unicode string. 422 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 423 @param FormatString A Null-terminated ASCII format string. 424 @param Marker BASE_LIST marker for the variable argument list. 425 426 @return The number of Unicode characters in the produced output buffer not including the 427 Null-terminator. 428 429 **/ 430 UINTN 431 EFIAPI 432 UnicodeBSPrintAsciiFormat ( 433 OUT CHAR16 *StartOfBuffer, 434 IN UINTN BufferSize, 435 IN CONST CHAR8 *FormatString, 436 IN BASE_LIST Marker 437 ); 438 439 /** 440 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 441 ASCII format string and variable argument list. 442 443 This function is similar as snprintf_s defined in C11. 444 445 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 446 and BufferSize. 447 The Unicode string is produced by parsing the format string specified by FormatString. 448 Arguments are pulled from the variable argument list based on the contents of the 449 format string. 450 The number of Unicode characters in the produced output buffer is returned not including 451 the Null-terminator. 452 453 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 454 455 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 456 unmodified and 0 is returned. 457 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is 458 unmodified and 0 is returned. 459 If PcdMaximumUnicodeStringLength is not zero, and BufferSize > 460 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output 461 buffer is unmodified and 0 is returned. 462 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 463 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 464 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 465 466 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 467 468 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 469 Unicode string. 470 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 471 @param FormatString A Null-terminated ASCII format string. 472 @param ... Variable argument list whose contents are accessed based on the 473 format string specified by FormatString. 474 475 @return The number of Unicode characters in the produced output buffer not including the 476 Null-terminator. 477 478 **/ 479 UINTN 480 EFIAPI 481 UnicodeSPrintAsciiFormat ( 482 OUT CHAR16 *StartOfBuffer, 483 IN UINTN BufferSize, 484 IN CONST CHAR8 *FormatString, 485 ... 486 ); 487 488 /** 489 Converts a decimal value to a Null-terminated Unicode string. 490 491 Converts the decimal number specified by Value to a Null-terminated Unicode 492 string specified by Buffer containing at most Width characters. No padding of 493 spaces is ever performed. If Width is 0 then a width of 494 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than 495 Width characters, then only the first Width characters are placed in Buffer. 496 Additional conversion parameters are specified in Flags. 497 498 The Flags bit LEFT_JUSTIFY is always ignored. 499 All conversions are left justified in Buffer. 500 If Width is 0, PREFIX_ZERO is ignored in Flags. 501 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and 502 commas are inserted every 3rd digit starting from the right. 503 If RADIX_HEX is set in Flags, then the output buffer will be formatted in 504 hexadecimal format. 505 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in 506 Buffer is a '-'. 507 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then 508 Buffer is padded with '0' characters so the combination of the optional '-' 509 sign character, '0' characters, digit characters for Value, and the 510 Null-terminator add up to Width characters. 511 512 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 513 If an error would be returned, then the function will also ASSERT(). 514 515 @param Buffer The pointer to the output buffer for the produced 516 Null-terminated Unicode string. 517 @param BufferSize The size of Buffer in bytes, including the 518 Null-terminator. 519 @param Flags The bitmask of flags that specify left justification, 520 zero pad, and commas. 521 @param Value The 64-bit signed value to convert to a string. 522 @param Width The maximum number of Unicode characters to place in 523 Buffer, not including the Null-terminator. 524 525 @retval RETURN_SUCCESS The decimal value is converted. 526 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted 527 value. 528 @retval RETURN_INVALID_PARAMETER If Buffer is NULL. 529 If PcdMaximumUnicodeStringLength is not 530 zero, and BufferSize is greater than 531 (PcdMaximumUnicodeStringLength * 532 sizeof (CHAR16) + 1). 533 If unsupported bits are set in Flags. 534 If both COMMA_TYPE and RADIX_HEX are set in 535 Flags. 536 If Width >= MAXIMUM_VALUE_CHARACTERS. 537 538 **/ 539 RETURN_STATUS 540 EFIAPI 541 UnicodeValueToStringS ( 542 IN OUT CHAR16 *Buffer, 543 IN UINTN BufferSize, 544 IN UINTN Flags, 545 IN INT64 Value, 546 IN UINTN Width 547 ); 548 549 /** 550 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 551 ASCII format string and a VA_LIST argument list. 552 553 This function is similar as vsnprintf_s defined in C11. 554 555 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 556 and BufferSize. 557 The ASCII string is produced by parsing the format string specified by FormatString. 558 Arguments are pulled from the variable argument list specified by Marker based on 559 the contents of the format string. 560 The number of ASCII characters in the produced output buffer is returned not including 561 the Null-terminator. 562 563 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 564 unmodified and 0 is returned. 565 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 566 unmodified and 0 is returned. 567 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 568 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 569 is unmodified and 0 is returned. 570 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 571 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 572 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 573 574 If BufferSize is 0, then no output buffer is produced and 0 is returned. 575 576 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 577 ASCII string. 578 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 579 @param FormatString A Null-terminated ASCII format string. 580 @param Marker VA_LIST marker for the variable argument list. 581 582 @return The number of ASCII characters in the produced output buffer not including the 583 Null-terminator. 584 585 **/ 586 UINTN 587 EFIAPI 588 AsciiVSPrint ( 589 OUT CHAR8 *StartOfBuffer, 590 IN UINTN BufferSize, 591 IN CONST CHAR8 *FormatString, 592 IN VA_LIST Marker 593 ); 594 595 /** 596 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 597 ASCII format string and a BASE_LIST argument list. 598 599 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 600 and BufferSize. 601 The ASCII string is produced by parsing the format string specified by FormatString. 602 Arguments are pulled from the variable argument list specified by Marker based on 603 the contents of the format string. 604 The number of ASCII characters in the produced output buffer is returned not including 605 the Null-terminator. 606 607 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 608 unmodified and 0 is returned. 609 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 610 unmodified and 0 is returned. 611 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 612 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 613 is unmodified and 0 is returned. 614 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 615 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 616 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 617 618 If BufferSize is 0, then no output buffer is produced and 0 is returned. 619 620 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 621 ASCII string. 622 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 623 @param FormatString A Null-terminated ASCII format string. 624 @param Marker BASE_LIST marker for the variable argument list. 625 626 @return The number of ASCII characters in the produced output buffer not including the 627 Null-terminator. 628 629 **/ 630 UINTN 631 EFIAPI 632 AsciiBSPrint ( 633 OUT CHAR8 *StartOfBuffer, 634 IN UINTN BufferSize, 635 IN CONST CHAR8 *FormatString, 636 IN BASE_LIST Marker 637 ); 638 639 /** 640 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 641 ASCII format string and variable argument list. 642 643 This function is similar as snprintf_s defined in C11. 644 645 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 646 and BufferSize. 647 The ASCII string is produced by parsing the format string specified by FormatString. 648 Arguments are pulled from the variable argument list based on the contents of the 649 format string. 650 The number of ASCII characters in the produced output buffer is returned not including 651 the Null-terminator. 652 653 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 654 unmodified and 0 is returned. 655 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 656 unmodified and 0 is returned. 657 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 658 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 659 is unmodified and 0 is returned. 660 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 661 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 662 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 663 664 If BufferSize is 0, then no output buffer is produced and 0 is returned. 665 666 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 667 ASCII string. 668 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 669 @param FormatString A Null-terminated ASCII format string. 670 @param ... Variable argument list whose contents are accessed based on the 671 format string specified by FormatString. 672 673 @return The number of ASCII characters in the produced output buffer not including the 674 Null-terminator. 675 676 **/ 677 UINTN 678 EFIAPI 679 AsciiSPrint ( 680 OUT CHAR8 *StartOfBuffer, 681 IN UINTN BufferSize, 682 IN CONST CHAR8 *FormatString, 683 ... 684 ); 685 686 /** 687 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 688 Unicode format string and a VA_LIST argument list. 689 690 This function is similar as vsnprintf_s defined in C11. 691 692 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 693 and BufferSize. 694 The ASCII string is produced by parsing the format string specified by FormatString. 695 Arguments are pulled from the variable argument list specified by Marker based on 696 the contents of the format string. 697 The number of ASCII characters in the produced output buffer is returned not including 698 the Null-terminator. 699 700 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 701 702 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 703 unmodified and 0 is returned. 704 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 705 unmodified and 0 is returned. 706 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 707 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 708 is unmodified and 0 is returned. 709 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 710 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 711 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 712 713 If BufferSize is 0, then no output buffer is produced and 0 is returned. 714 715 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 716 ASCII string. 717 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 718 @param FormatString A Null-terminated Unicode format string. 719 @param Marker VA_LIST marker for the variable argument list. 720 721 @return The number of ASCII characters in the produced output buffer not including the 722 Null-terminator. 723 724 **/ 725 UINTN 726 EFIAPI 727 AsciiVSPrintUnicodeFormat ( 728 OUT CHAR8 *StartOfBuffer, 729 IN UINTN BufferSize, 730 IN CONST CHAR16 *FormatString, 731 IN VA_LIST Marker 732 ); 733 734 /** 735 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 736 Unicode format string and a BASE_LIST argument list. 737 738 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 739 and BufferSize. 740 The ASCII string is produced by parsing the format string specified by FormatString. 741 Arguments are pulled from the variable argument list specified by Marker based on 742 the contents of the format string. 743 The number of ASCII characters in the produced output buffer is returned not including 744 the Null-terminator. 745 746 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 747 748 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 749 unmodified and 0 is returned. 750 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 751 unmodified and 0 is returned. 752 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 753 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 754 is unmodified and 0 is returned. 755 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 756 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 757 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 758 759 If BufferSize is 0, then no output buffer is produced and 0 is returned. 760 761 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 762 ASCII string. 763 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 764 @param FormatString A Null-terminated Unicode format string. 765 @param Marker BASE_LIST marker for the variable argument list. 766 767 @return The number of ASCII characters in the produced output buffer not including the 768 Null-terminator. 769 770 **/ 771 UINTN 772 EFIAPI 773 AsciiBSPrintUnicodeFormat ( 774 OUT CHAR8 *StartOfBuffer, 775 IN UINTN BufferSize, 776 IN CONST CHAR16 *FormatString, 777 IN BASE_LIST Marker 778 ); 779 780 /** 781 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 782 Unicode format string and variable argument list. 783 784 This function is similar as snprintf_s defined in C11. 785 786 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 787 and BufferSize. 788 The ASCII string is produced by parsing the format string specified by FormatString. 789 Arguments are pulled from the variable argument list based on the contents of the 790 format string. 791 The number of ASCII characters in the produced output buffer is returned not including 792 the Null-terminator. 793 794 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 795 796 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 797 unmodified and 0 is returned. 798 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 799 unmodified and 0 is returned. 800 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 801 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 802 is unmodified and 0 is returned. 803 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 804 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 805 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 806 807 If BufferSize is 0, then no output buffer is produced and 0 is returned. 808 809 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 810 ASCII string. 811 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 812 @param FormatString A Null-terminated Unicode format string. 813 @param ... Variable argument list whose contents are accessed based on the 814 format string specified by FormatString. 815 816 @return The number of ASCII characters in the produced output buffer not including the 817 Null-terminator. 818 819 **/ 820 UINTN 821 EFIAPI 822 AsciiSPrintUnicodeFormat ( 823 OUT CHAR8 *StartOfBuffer, 824 IN UINTN BufferSize, 825 IN CONST CHAR16 *FormatString, 826 ... 827 ); 828 829 /** 830 Converts a decimal value to a Null-terminated Ascii string. 831 832 Converts the decimal number specified by Value to a Null-terminated Ascii 833 string specified by Buffer containing at most Width characters. No padding of 834 spaces is ever performed. If Width is 0 then a width of 835 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than 836 Width characters, then only the first Width characters are placed in Buffer. 837 Additional conversion parameters are specified in Flags. 838 839 The Flags bit LEFT_JUSTIFY is always ignored. 840 All conversions are left justified in Buffer. 841 If Width is 0, PREFIX_ZERO is ignored in Flags. 842 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and 843 commas are inserted every 3rd digit starting from the right. 844 If RADIX_HEX is set in Flags, then the output buffer will be formatted in 845 hexadecimal format. 846 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in 847 Buffer is a '-'. 848 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then 849 Buffer is padded with '0' characters so the combination of the optional '-' 850 sign character, '0' characters, digit characters for Value, and the 851 Null-terminator add up to Width characters. 852 853 If an error would be returned, then the function will ASSERT(). 854 855 @param Buffer The pointer to the output buffer for the produced 856 Null-terminated Ascii string. 857 @param BufferSize The size of Buffer in bytes, including the 858 Null-terminator. 859 @param Flags The bitmask of flags that specify left justification, 860 zero pad, and commas. 861 @param Value The 64-bit signed value to convert to a string. 862 @param Width The maximum number of Ascii characters to place in 863 Buffer, not including the Null-terminator. 864 865 @retval RETURN_SUCCESS The decimal value is converted. 866 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted 867 value. 868 @retval RETURN_INVALID_PARAMETER If Buffer is NULL. 869 If PcdMaximumAsciiStringLength is not 870 zero, and BufferSize is greater than 871 PcdMaximumAsciiStringLength. 872 If unsupported bits are set in Flags. 873 If both COMMA_TYPE and RADIX_HEX are set in 874 Flags. 875 If Width >= MAXIMUM_VALUE_CHARACTERS. 876 877 **/ 878 RETURN_STATUS 879 EFIAPI 880 AsciiValueToStringS ( 881 IN OUT CHAR8 *Buffer, 882 IN UINTN BufferSize, 883 IN UINTN Flags, 884 IN INT64 Value, 885 IN UINTN Width 886 ); 887 888 /** 889 Returns the number of characters that would be produced by if the formatted 890 output were produced not including the Null-terminator. 891 892 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 893 894 If FormatString is NULL, then ASSERT() and 0 is returned. 895 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more 896 than PcdMaximumUnicodeStringLength Unicode characters not including the 897 Null-terminator, then ASSERT() and 0 is returned. 898 899 @param[in] FormatString A Null-terminated Unicode format string. 900 @param[in] Marker VA_LIST marker for the variable argument list. 901 902 @return The number of characters that would be produced, not including the 903 Null-terminator. 904 **/ 905 UINTN 906 EFIAPI 907 SPrintLength ( 908 IN CONST CHAR16 *FormatString, 909 IN VA_LIST Marker 910 ); 911 912 /** 913 Returns the number of characters that would be produced by if the formatted 914 output were produced not including the Null-terminator. 915 916 If FormatString is NULL, then ASSERT() and 0 is returned. 917 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more 918 than PcdMaximumAsciiStringLength Ascii characters not including the 919 Null-terminator, then ASSERT() and 0 is returned. 920 921 @param[in] FormatString A Null-terminated ASCII format string. 922 @param[in] Marker VA_LIST marker for the variable argument list. 923 924 @return The number of characters that would be produced, not including the 925 Null-terminator. 926 **/ 927 UINTN 928 EFIAPI 929 SPrintLengthAsciiFormat ( 930 IN CONST CHAR8 *FormatString, 931 IN VA_LIST Marker 932 ); 933 934 #endif 935