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