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 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 489 490 /** 491 [ATTENTION] This function is deprecated for security reason. 492 493 Converts a decimal value to a Null-terminated Unicode string. 494 495 Converts the decimal number specified by Value to a Null-terminated Unicode 496 string specified by Buffer containing at most Width characters. No padding of spaces 497 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 498 The number of Unicode characters in Buffer is returned, not including the Null-terminator. 499 If the conversion contains more than Width characters, then only the first 500 Width characters are returned, and the total number of characters 501 required to perform the conversion is returned. 502 Additional conversion parameters are specified in Flags. 503 504 The Flags bit LEFT_JUSTIFY is always ignored. 505 All conversions are left justified in Buffer. 506 If Width is 0, PREFIX_ZERO is ignored in Flags. 507 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 508 are inserted every 3rd digit starting from the right. 509 If RADIX_HEX is set in Flags, then the output buffer will be 510 formatted in hexadecimal format. 511 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 512 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 513 then Buffer is padded with '0' characters so the combination of the optional '-' 514 sign character, '0' characters, digit characters for Value, and the Null-terminator 515 add up to Width characters. 516 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 517 If Buffer is NULL, then ASSERT(). 518 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 519 If unsupported bits are set in Flags, then ASSERT(). 520 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 521 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 522 523 @param Buffer The pointer to the output buffer for the produced Null-terminated 524 Unicode string. 525 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 526 @param Value The 64-bit signed value to convert to a string. 527 @param Width The maximum number of Unicode characters to place in Buffer, not including 528 the Null-terminator. 529 530 @return The number of Unicode characters in Buffer, not including the Null-terminator. 531 532 **/ 533 UINTN 534 EFIAPI 535 UnicodeValueToString ( 536 IN OUT CHAR16 *Buffer, 537 IN UINTN Flags, 538 IN INT64 Value, 539 IN UINTN Width 540 ); 541 542 #endif 543 544 /** 545 Converts a decimal value to a Null-terminated Unicode string. 546 547 Converts the decimal number specified by Value to a Null-terminated Unicode 548 string specified by Buffer containing at most Width characters. No padding of 549 spaces is ever performed. If Width is 0 then a width of 550 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than 551 Width characters, then only the first Width characters are placed in Buffer. 552 Additional conversion parameters are specified in Flags. 553 554 The Flags bit LEFT_JUSTIFY is always ignored. 555 All conversions are left justified in Buffer. 556 If Width is 0, PREFIX_ZERO is ignored in Flags. 557 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and 558 commas are inserted every 3rd digit starting from the right. 559 If RADIX_HEX is set in Flags, then the output buffer will be formatted in 560 hexadecimal format. 561 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in 562 Buffer is a '-'. 563 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then 564 Buffer is padded with '0' characters so the combination of the optional '-' 565 sign character, '0' characters, digit characters for Value, and the 566 Null-terminator add up to Width characters. 567 568 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 569 If an error would be returned, then the function will also ASSERT(). 570 571 @param Buffer The pointer to the output buffer for the produced 572 Null-terminated Unicode string. 573 @param BufferSize The size of Buffer in bytes, including the 574 Null-terminator. 575 @param Flags The bitmask of flags that specify left justification, 576 zero pad, and commas. 577 @param Value The 64-bit signed value to convert to a string. 578 @param Width The maximum number of Unicode characters to place in 579 Buffer, not including the Null-terminator. 580 581 @retval RETURN_SUCCESS The decimal value is converted. 582 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted 583 value. 584 @retval RETURN_INVALID_PARAMETER If Buffer is NULL. 585 If PcdMaximumUnicodeStringLength is not 586 zero, and BufferSize is greater than 587 (PcdMaximumUnicodeStringLength * 588 sizeof (CHAR16) + 1). 589 If unsupported bits are set in Flags. 590 If both COMMA_TYPE and RADIX_HEX are set in 591 Flags. 592 If Width >= MAXIMUM_VALUE_CHARACTERS. 593 594 **/ 595 RETURN_STATUS 596 EFIAPI 597 UnicodeValueToStringS ( 598 IN OUT CHAR16 *Buffer, 599 IN UINTN BufferSize, 600 IN UINTN Flags, 601 IN INT64 Value, 602 IN UINTN Width 603 ); 604 605 /** 606 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 607 ASCII format string and a VA_LIST argument list. 608 609 This function is similar as vsnprintf_s defined in C11. 610 611 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 612 and BufferSize. 613 The ASCII string is produced by parsing the format string specified by FormatString. 614 Arguments are pulled from the variable argument list specified by Marker based on 615 the contents of the format string. 616 The number of ASCII characters in the produced output buffer is returned not including 617 the Null-terminator. 618 619 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 620 unmodified and 0 is returned. 621 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 622 unmodified and 0 is returned. 623 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 624 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 625 is unmodified and 0 is returned. 626 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 627 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 628 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 629 630 If BufferSize is 0, then no output buffer is produced and 0 is returned. 631 632 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 633 ASCII string. 634 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 635 @param FormatString A Null-terminated ASCII format string. 636 @param Marker VA_LIST marker for the variable argument list. 637 638 @return The number of ASCII characters in the produced output buffer not including the 639 Null-terminator. 640 641 **/ 642 UINTN 643 EFIAPI 644 AsciiVSPrint ( 645 OUT CHAR8 *StartOfBuffer, 646 IN UINTN BufferSize, 647 IN CONST CHAR8 *FormatString, 648 IN VA_LIST Marker 649 ); 650 651 /** 652 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 653 ASCII format string and a BASE_LIST argument list. 654 655 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 656 and BufferSize. 657 The ASCII string is produced by parsing the format string specified by FormatString. 658 Arguments are pulled from the variable argument list specified by Marker based on 659 the contents of the format string. 660 The number of ASCII characters in the produced output buffer is returned not including 661 the Null-terminator. 662 663 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 664 unmodified and 0 is returned. 665 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 666 unmodified and 0 is returned. 667 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 668 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 669 is unmodified and 0 is returned. 670 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 671 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 672 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 673 674 If BufferSize is 0, then no output buffer is produced and 0 is returned. 675 676 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 677 ASCII string. 678 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 679 @param FormatString A Null-terminated ASCII format string. 680 @param Marker BASE_LIST marker for the variable argument list. 681 682 @return The number of ASCII characters in the produced output buffer not including the 683 Null-terminator. 684 685 **/ 686 UINTN 687 EFIAPI 688 AsciiBSPrint ( 689 OUT CHAR8 *StartOfBuffer, 690 IN UINTN BufferSize, 691 IN CONST CHAR8 *FormatString, 692 IN BASE_LIST Marker 693 ); 694 695 /** 696 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 697 ASCII format string and variable argument list. 698 699 This function is similar as snprintf_s defined in C11. 700 701 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 702 and BufferSize. 703 The ASCII string is produced by parsing the format string specified by FormatString. 704 Arguments are pulled from the variable argument list based on the contents of the 705 format string. 706 The number of ASCII characters in the produced output buffer is returned not including 707 the Null-terminator. 708 709 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 710 unmodified and 0 is returned. 711 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 712 unmodified and 0 is returned. 713 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 714 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 715 is unmodified and 0 is returned. 716 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 717 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then 718 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 719 720 If BufferSize is 0, then no output buffer is produced and 0 is returned. 721 722 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 723 ASCII string. 724 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 725 @param FormatString A Null-terminated ASCII format string. 726 @param ... Variable argument list whose contents are accessed based on the 727 format string specified by FormatString. 728 729 @return The number of ASCII characters in the produced output buffer not including the 730 Null-terminator. 731 732 **/ 733 UINTN 734 EFIAPI 735 AsciiSPrint ( 736 OUT CHAR8 *StartOfBuffer, 737 IN UINTN BufferSize, 738 IN CONST CHAR8 *FormatString, 739 ... 740 ); 741 742 /** 743 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 744 Unicode format string and a VA_LIST argument list. 745 746 This function is similar as vsnprintf_s defined in C11. 747 748 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 749 and BufferSize. 750 The ASCII string is produced by parsing the format string specified by FormatString. 751 Arguments are pulled from the variable argument list specified by Marker based on 752 the contents of the format string. 753 The number of ASCII characters in the produced output buffer is returned not including 754 the Null-terminator. 755 756 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 757 758 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 759 unmodified and 0 is returned. 760 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 761 unmodified and 0 is returned. 762 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 763 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 764 is unmodified and 0 is returned. 765 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 766 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 767 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 768 769 If BufferSize is 0, then no output buffer is produced and 0 is returned. 770 771 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 772 ASCII string. 773 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 774 @param FormatString A Null-terminated Unicode format string. 775 @param Marker VA_LIST marker for the variable argument list. 776 777 @return The number of ASCII characters in the produced output buffer not including the 778 Null-terminator. 779 780 **/ 781 UINTN 782 EFIAPI 783 AsciiVSPrintUnicodeFormat ( 784 OUT CHAR8 *StartOfBuffer, 785 IN UINTN BufferSize, 786 IN CONST CHAR16 *FormatString, 787 IN VA_LIST Marker 788 ); 789 790 /** 791 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 792 Unicode format string and a BASE_LIST argument list. 793 794 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 795 and BufferSize. 796 The ASCII string is produced by parsing the format string specified by FormatString. 797 Arguments are pulled from the variable argument list specified by Marker based on 798 the contents of the format string. 799 The number of ASCII characters in the produced output buffer is returned not including 800 the Null-terminator. 801 802 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 803 804 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 805 unmodified and 0 is returned. 806 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 807 unmodified and 0 is returned. 808 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 809 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 810 is unmodified and 0 is returned. 811 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 812 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 813 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 814 815 If BufferSize is 0, then no output buffer is produced and 0 is returned. 816 817 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 818 ASCII string. 819 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 820 @param FormatString A Null-terminated Unicode format string. 821 @param Marker BASE_LIST marker for the variable argument list. 822 823 @return The number of ASCII characters in the produced output buffer not including the 824 Null-terminator. 825 826 **/ 827 UINTN 828 EFIAPI 829 AsciiBSPrintUnicodeFormat ( 830 OUT CHAR8 *StartOfBuffer, 831 IN UINTN BufferSize, 832 IN CONST CHAR16 *FormatString, 833 IN BASE_LIST Marker 834 ); 835 836 /** 837 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 838 Unicode format string and variable argument list. 839 840 This function is similar as snprintf_s defined in C11. 841 842 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 843 and BufferSize. 844 The ASCII string is produced by parsing the format string specified by FormatString. 845 Arguments are pulled from the variable argument list based on the contents of the 846 format string. 847 The number of ASCII characters in the produced output buffer is returned not including 848 the Null-terminator. 849 850 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 851 852 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is 853 unmodified and 0 is returned. 854 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is 855 unmodified and 0 is returned. 856 If PcdMaximumAsciiStringLength is not zero, and BufferSize > 857 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer 858 is unmodified and 0 is returned. 859 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 860 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 861 ASSERT(). Also, the output buffer is unmodified and 0 is returned. 862 863 If BufferSize is 0, then no output buffer is produced and 0 is returned. 864 865 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 866 ASCII string. 867 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 868 @param FormatString A Null-terminated Unicode format string. 869 @param ... Variable argument list whose contents are accessed based on the 870 format string specified by FormatString. 871 872 @return The number of ASCII characters in the produced output buffer not including the 873 Null-terminator. 874 875 **/ 876 UINTN 877 EFIAPI 878 AsciiSPrintUnicodeFormat ( 879 OUT CHAR8 *StartOfBuffer, 880 IN UINTN BufferSize, 881 IN CONST CHAR16 *FormatString, 882 ... 883 ); 884 885 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 886 887 /** 888 [ATTENTION] This function is deprecated for security reason. 889 890 Converts a decimal value to a Null-terminated ASCII string. 891 892 Converts the decimal number specified by Value to a Null-terminated ASCII string 893 specified by Buffer containing at most Width characters. No padding of spaces 894 is ever performed. 895 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 896 The number of ASCII characters in Buffer is returned, not including the Null-terminator. 897 If the conversion contains more than Width characters, then only the first Width 898 characters are returned, and the total number of characters required to perform 899 the conversion is returned. 900 Additional conversion parameters are specified in Flags. 901 The Flags bit LEFT_JUSTIFY is always ignored. 902 All conversions are left justified in Buffer. 903 If Width is 0, PREFIX_ZERO is ignored in Flags. 904 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 905 are inserted every 3rd digit starting from the right. 906 If RADIX_HEX is set in Flags, then the output buffer will be 907 formatted in hexadecimal format. 908 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 909 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 910 then Buffer is padded with '0' characters so the combination of the optional '-' 911 sign character, '0' characters, digit characters for Value, and the Null-terminator 912 add up to Width characters. 913 914 If Buffer is NULL, then ASSERT(). 915 If unsupported bits are set in Flags, then ASSERT(). 916 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 917 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 918 919 @param Buffer A pointer to the output buffer for the produced Null-terminated 920 ASCII string. 921 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 922 @param Value The 64-bit signed value to convert to a string. 923 @param Width The maximum number of ASCII characters to place in Buffer, not including 924 the Null-terminator. 925 926 @return The number of ASCII characters in Buffer, not including the Null-terminator. 927 928 **/ 929 UINTN 930 EFIAPI 931 AsciiValueToString ( 932 OUT CHAR8 *Buffer, 933 IN UINTN Flags, 934 IN INT64 Value, 935 IN UINTN Width 936 ); 937 938 #endif 939 940 /** 941 Converts a decimal value to a Null-terminated Ascii string. 942 943 Converts the decimal number specified by Value to a Null-terminated Ascii 944 string specified by Buffer containing at most Width characters. No padding of 945 spaces is ever performed. If Width is 0 then a width of 946 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than 947 Width characters, then only the first Width characters are placed in Buffer. 948 Additional conversion parameters are specified in Flags. 949 950 The Flags bit LEFT_JUSTIFY is always ignored. 951 All conversions are left justified in Buffer. 952 If Width is 0, PREFIX_ZERO is ignored in Flags. 953 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and 954 commas are inserted every 3rd digit starting from the right. 955 If RADIX_HEX is set in Flags, then the output buffer will be formatted in 956 hexadecimal format. 957 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in 958 Buffer is a '-'. 959 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then 960 Buffer is padded with '0' characters so the combination of the optional '-' 961 sign character, '0' characters, digit characters for Value, and the 962 Null-terminator add up to Width characters. 963 964 If an error would be returned, then the function will ASSERT(). 965 966 @param Buffer The pointer to the output buffer for the produced 967 Null-terminated Ascii string. 968 @param BufferSize The size of Buffer in bytes, including the 969 Null-terminator. 970 @param Flags The bitmask of flags that specify left justification, 971 zero pad, and commas. 972 @param Value The 64-bit signed value to convert to a string. 973 @param Width The maximum number of Ascii characters to place in 974 Buffer, not including the Null-terminator. 975 976 @retval RETURN_SUCCESS The decimal value is converted. 977 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted 978 value. 979 @retval RETURN_INVALID_PARAMETER If Buffer is NULL. 980 If PcdMaximumAsciiStringLength is not 981 zero, and BufferSize is greater than 982 PcdMaximumAsciiStringLength. 983 If unsupported bits are set in Flags. 984 If both COMMA_TYPE and RADIX_HEX are set in 985 Flags. 986 If Width >= MAXIMUM_VALUE_CHARACTERS. 987 988 **/ 989 RETURN_STATUS 990 EFIAPI 991 AsciiValueToStringS ( 992 IN OUT CHAR8 *Buffer, 993 IN UINTN BufferSize, 994 IN UINTN Flags, 995 IN INT64 Value, 996 IN UINTN Width 997 ); 998 999 /** 1000 Returns the number of characters that would be produced by if the formatted 1001 output were produced not including the Null-terminator. 1002 1003 If FormatString is not aligned on a 16-bit boundary, then ASSERT(). 1004 1005 If FormatString is NULL, then ASSERT() and 0 is returned. 1006 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more 1007 than PcdMaximumUnicodeStringLength Unicode characters not including the 1008 Null-terminator, then ASSERT() and 0 is returned. 1009 1010 @param[in] FormatString A Null-terminated Unicode format string. 1011 @param[in] Marker VA_LIST marker for the variable argument list. 1012 1013 @return The number of characters that would be produced, not including the 1014 Null-terminator. 1015 **/ 1016 UINTN 1017 EFIAPI 1018 SPrintLength ( 1019 IN CONST CHAR16 *FormatString, 1020 IN VA_LIST Marker 1021 ); 1022 1023 /** 1024 Returns the number of characters that would be produced by if the formatted 1025 output were produced not including the Null-terminator. 1026 1027 If FormatString is NULL, then ASSERT() and 0 is returned. 1028 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more 1029 than PcdMaximumAsciiStringLength Ascii characters not including the 1030 Null-terminator, then ASSERT() and 0 is returned. 1031 1032 @param[in] FormatString A Null-terminated ASCII format string. 1033 @param[in] Marker VA_LIST marker for the variable argument list. 1034 1035 @return The number of characters that would be produced, not including the 1036 Null-terminator. 1037 **/ 1038 UINTN 1039 EFIAPI 1040 SPrintLengthAsciiFormat ( 1041 IN CONST CHAR8 *FormatString, 1042 IN VA_LIST Marker 1043 ); 1044 1045 #endif 1046