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 - 2015, 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 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 211 and BufferSize. 212 The Unicode string is produced by parsing the format string specified by FormatString. 213 Arguments are pulled from the variable argument list specified by Marker based on the 214 contents of the format string. 215 The number of Unicode characters in the produced output buffer is returned, not including 216 the Null-terminator. 217 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 218 219 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 220 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 221 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 222 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 223 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 224 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then 225 ASSERT(). 226 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 227 contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the 228 Null-terminator, then ASSERT(). 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 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 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 261 262 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 263 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 264 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 265 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 266 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 267 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then 268 ASSERT(). 269 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 270 contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the 271 Null-terminator, then ASSERT(). 272 273 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 274 Unicode string. 275 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 276 @param FormatString Null-terminated Unicode format string. 277 @param Marker BASE_LIST marker for the variable argument list. 278 279 @return The number of Unicode characters in the produced output buffer, not including the 280 Null-terminator. 281 282 **/ 283 UINTN 284 EFIAPI 285 UnicodeBSPrint ( 286 OUT CHAR16 *StartOfBuffer, 287 IN UINTN BufferSize, 288 IN CONST CHAR16 *FormatString, 289 IN BASE_LIST Marker 290 ); 291 292 /** 293 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 294 Unicode format string and variable argument list. 295 296 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 297 and BufferSize. 298 The Unicode string is produced by parsing the format string specified by FormatString. 299 Arguments are pulled from the variable argument list based on the contents of the format string. 300 The number of Unicode characters in the produced output buffer is returned, not including 301 the Null-terminator. 302 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 303 304 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 305 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 306 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 307 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 308 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 309 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then 310 ASSERT(). 311 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 312 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the 313 Null-terminator, then ASSERT(). 314 315 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 316 Unicode string. 317 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 318 @param FormatString A null-terminated Unicode format string. 319 @param ... The variable argument list whose contents are accessed based on the 320 format string specified by FormatString. 321 322 @return The number of Unicode characters in the produced output buffer, not including the 323 Null-terminator. 324 325 **/ 326 UINTN 327 EFIAPI 328 UnicodeSPrint ( 329 OUT CHAR16 *StartOfBuffer, 330 IN UINTN BufferSize, 331 IN CONST CHAR16 *FormatString, 332 ... 333 ); 334 335 /** 336 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 337 ASCII format string and a VA_LIST argument list 338 339 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 340 and BufferSize. 341 The Unicode string is produced by parsing the format string specified by FormatString. 342 Arguments are pulled from the variable argument list specified by Marker based on the 343 contents of the format string. 344 The number of Unicode characters in the produced output buffer is returned, not including 345 the Null-terminator. 346 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 347 348 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 349 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 350 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 351 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 352 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 353 ASSERT(). 354 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 355 contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the 356 Null-terminator, then ASSERT(). 357 358 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 359 Unicode string. 360 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 361 @param FormatString A null-terminated ASCII format string. 362 @param Marker VA_LIST marker for the variable argument list. 363 364 @return The number of Unicode characters in the produced output buffer not including the 365 Null-terminator. 366 367 **/ 368 UINTN 369 EFIAPI 370 UnicodeVSPrintAsciiFormat ( 371 OUT CHAR16 *StartOfBuffer, 372 IN UINTN BufferSize, 373 IN CONST CHAR8 *FormatString, 374 IN VA_LIST Marker 375 ); 376 377 /** 378 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 379 ASCII format string and a BASE_LIST argument list 380 381 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 382 and BufferSize. 383 The Unicode string is produced by parsing the format string specified by FormatString. 384 Arguments are pulled from the variable argument list specified by Marker based on the 385 contents of the format string. 386 The number of Unicode characters in the produced output buffer is returned, not including 387 the Null-terminator. 388 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 389 390 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 391 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 392 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 393 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 394 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 395 ASSERT(). 396 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 397 contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the 398 Null-terminator, then ASSERT(). 399 400 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 401 Unicode string. 402 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 403 @param FormatString A null-terminated ASCII format string. 404 @param Marker A BASE_LIST marker for the variable argument list. 405 406 @return The number of Unicode characters in the produced output buffer, not including the 407 Null-terminator. 408 409 **/ 410 UINTN 411 EFIAPI 412 UnicodeBSPrintAsciiFormat ( 413 OUT CHAR16 *StartOfBuffer, 414 IN UINTN BufferSize, 415 IN CONST CHAR8 *FormatString, 416 IN BASE_LIST Marker 417 ); 418 419 /** 420 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated 421 ASCII format string and variable argument list. 422 423 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer 424 and BufferSize. 425 The Unicode string is produced by parsing the format string specified by FormatString. 426 Arguments are pulled from the variable argument list based on the contents of the 427 format string. 428 The number of Unicode characters in the produced output buffer is returned, not including 429 the Null-terminator. 430 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. 431 432 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). 433 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). 434 If BufferSize > 1 and FormatString is NULL, then ASSERT(). 435 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 436 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 437 ASSERT(). 438 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string 439 contains more than PcdMaximumUnicodeStringLength Unicode characters, the 440 Null-terminator, then ASSERT(). 441 442 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 443 Unicode string. 444 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 445 @param FormatString A null-terminated ASCII format string. 446 @param ... Variable argument list whose contents are accessed based on the 447 format string specified by FormatString. 448 449 @return The number of Unicode characters in the produced output buffer, not including the 450 Null-terminator. 451 452 **/ 453 UINTN 454 EFIAPI 455 UnicodeSPrintAsciiFormat ( 456 OUT CHAR16 *StartOfBuffer, 457 IN UINTN BufferSize, 458 IN CONST CHAR8 *FormatString, 459 ... 460 ); 461 462 /** 463 Converts a decimal value to a Null-terminated Unicode string. 464 465 Converts the decimal number specified by Value to a Null-terminated Unicode 466 string specified by Buffer containing at most Width characters. No padding of spaces 467 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 468 The number of Unicode characters in Buffer is returned, not including the Null-terminator. 469 If the conversion contains more than Width characters, then only the first 470 Width characters are returned, and the total number of characters 471 required to perform the conversion is returned. 472 Additional conversion parameters are specified in Flags. 473 474 The Flags bit LEFT_JUSTIFY is always ignored. 475 All conversions are left justified in Buffer. 476 If Width is 0, PREFIX_ZERO is ignored in Flags. 477 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 478 are inserted every 3rd digit starting from the right. 479 If RADIX_HEX is set in Flags, then the output buffer will be 480 formatted in hexadecimal format. 481 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 482 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 483 then Buffer is padded with '0' characters so the combination of the optional '-' 484 sign character, '0' characters, digit characters for Value, and the Null-terminator 485 add up to Width characters. 486 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 487 If Buffer is NULL, then ASSERT(). 488 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 489 If unsupported bits are set in Flags, then ASSERT(). 490 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 491 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 492 493 @param Buffer The pointer to the output buffer for the produced Null-terminated 494 Unicode string. 495 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 496 @param Value The 64-bit signed value to convert to a string. 497 @param Width The maximum number of Unicode characters to place in Buffer, not including 498 the Null-terminator. 499 500 @return The number of Unicode characters in Buffer, not including the Null-terminator. 501 502 **/ 503 UINTN 504 EFIAPI 505 UnicodeValueToString ( 506 IN OUT CHAR16 *Buffer, 507 IN UINTN Flags, 508 IN INT64 Value, 509 IN UINTN Width 510 ); 511 512 /** 513 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 514 ASCII format string and a VA_LIST argument list. 515 516 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 517 and BufferSize. 518 The ASCII string is produced by parsing the format string specified by FormatString. 519 Arguments are pulled from the variable argument list specified by Marker based on 520 the contents of the format string. 521 The number of ASCII characters in the produced output buffer is returned, not including 522 the Null-terminator. 523 If BufferSize is 0, then no output buffer is produced and 0 is returned. 524 525 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 526 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 527 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 528 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 529 ASSERT(). 530 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 531 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 532 Null-terminator, then ASSERT(). 533 534 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 535 ASCII string. 536 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 537 @param FormatString A null-terminated ASCII format string. 538 @param Marker VA_LIST marker for the variable argument list. 539 540 @return The number of ASCII characters in the produced output buffer, not including the 541 Null-terminator. 542 543 **/ 544 UINTN 545 EFIAPI 546 AsciiVSPrint ( 547 OUT CHAR8 *StartOfBuffer, 548 IN UINTN BufferSize, 549 IN CONST CHAR8 *FormatString, 550 IN VA_LIST Marker 551 ); 552 553 /** 554 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 555 ASCII format string and a BASE_LIST argument list. 556 557 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 558 and BufferSize. 559 The ASCII string is produced by parsing the format string specified by FormatString. 560 Arguments are pulled from the variable argument list specified by Marker based on 561 the contents of the format string. 562 The number of ASCII characters in the produced output buffer is returned, not including 563 the Null-terminator. 564 If BufferSize is 0, then no output buffer is produced and 0 is returned. 565 566 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 567 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 568 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 569 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 570 ASSERT(). 571 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 572 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 573 Null-terminator, then ASSERT(). 574 575 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 576 ASCII string. 577 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 578 @param FormatString A null-terminated ASCII format string. 579 @param Marker BASE_LIST marker for the variable argument list. 580 581 @return The number of ASCII characters in the produced output buffer, not including the 582 Null-terminator. 583 584 **/ 585 UINTN 586 EFIAPI 587 AsciiBSPrint ( 588 OUT CHAR8 *StartOfBuffer, 589 IN UINTN BufferSize, 590 IN CONST CHAR8 *FormatString, 591 IN BASE_LIST Marker 592 ); 593 594 /** 595 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 596 ASCII format string and variable argument list. 597 598 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 599 and BufferSize. 600 The ASCII string is produced by parsing the format string specified by FormatString. 601 Arguments are pulled from the variable argument list based on the contents of the 602 format string. 603 The number of ASCII characters in the produced output buffer is returned, not including 604 the Null-terminator. 605 If BufferSize is 0, then no output buffer is produced and 0 is returned. 606 607 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 608 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 609 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than 610 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then 611 ASSERT(). 612 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 613 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 614 Null-terminator, then ASSERT(). 615 616 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 617 ASCII string. 618 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 619 @param FormatString A null-terminated ASCII format string. 620 @param ... The variable argument list whose contents are accessed based on the 621 format string specified by FormatString. 622 623 @return The number of ASCII characters in the produced output buffer, not including the 624 Null-terminator. 625 626 **/ 627 UINTN 628 EFIAPI 629 AsciiSPrint ( 630 OUT CHAR8 *StartOfBuffer, 631 IN UINTN BufferSize, 632 IN CONST CHAR8 *FormatString, 633 ... 634 ); 635 636 /** 637 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 638 Unicode format string and a VA_LIST argument list. 639 640 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 641 and BufferSize. 642 The ASCII string is produced by parsing the format string specified by FormatString. 643 Arguments are pulled from the variable argument list specified by Marker based on 644 the contents of the format string. 645 The number of ASCII characters in the produced output buffer is returned, not including 646 the Null-terminator. 647 If BufferSize is 0, then no output buffer is produced and 0 is returned. 648 649 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 650 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 651 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 652 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 653 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then 654 ASSERT(). 655 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 656 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 657 Null-terminator, then ASSERT(). 658 659 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 660 ASCII string. 661 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 662 @param FormatString A null-terminated Unicode format string. 663 @param Marker VA_LIST marker for the variable argument list. 664 665 @return The number of ASCII characters in the produced output buffer, not including the 666 Null-terminator. 667 668 **/ 669 UINTN 670 EFIAPI 671 AsciiVSPrintUnicodeFormat ( 672 OUT CHAR8 *StartOfBuffer, 673 IN UINTN BufferSize, 674 IN CONST CHAR16 *FormatString, 675 IN VA_LIST Marker 676 ); 677 678 /** 679 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 680 Unicode format string and a BASE_LIST argument list. 681 682 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 683 and BufferSize. 684 The ASCII string is produced by parsing the format string specified by FormatString. 685 Arguments are pulled from the variable argument list specified by Marker based on 686 the contents of the format string. 687 The number of ASCII characters in the produced output buffer is returned, not including 688 the Null-terminator. 689 If BufferSize is 0, then no output buffer is produced and 0 is returned. 690 691 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 692 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 693 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 694 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 695 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then 696 ASSERT(). 697 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 698 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 699 Null-terminator, then ASSERT(). 700 701 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 702 ASCII string. 703 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 704 @param FormatString A null-terminated Unicode format string. 705 @param Marker BASE_LIST marker for the variable argument list. 706 707 @return The number of ASCII characters in the produced output buffer, not including the 708 Null-terminator. 709 710 **/ 711 UINTN 712 EFIAPI 713 AsciiBSPrintUnicodeFormat ( 714 OUT CHAR8 *StartOfBuffer, 715 IN UINTN BufferSize, 716 IN CONST CHAR16 *FormatString, 717 IN BASE_LIST Marker 718 ); 719 720 /** 721 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated 722 Unicode format string and variable argument list. 723 724 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer 725 and BufferSize. 726 The ASCII string is produced by parsing the format string specified by FormatString. 727 Arguments are pulled from the variable argument list based on the contents of the 728 format string. 729 The number of ASCII characters in the produced output buffer is returned, not including 730 the Null-terminator. 731 If BufferSize is 0, then no output buffer is produced and 0 is returned. 732 733 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). 734 If BufferSize > 0 and FormatString is NULL, then ASSERT(). 735 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). 736 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than 737 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then 738 ASSERT(). 739 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string 740 contains more than PcdMaximumAsciiStringLength ASCII characters, not including the 741 Null-terminator, then ASSERT(). 742 743 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated 744 ASCII string. 745 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. 746 @param FormatString A null-terminated Unicode format string. 747 @param ... Variable argument list whose contents are accessed based on the 748 format string specified by FormatString. 749 750 @return The number of ASCII characters in the produced output buffer, not including the 751 Null-terminator. 752 753 **/ 754 UINTN 755 EFIAPI 756 AsciiSPrintUnicodeFormat ( 757 OUT CHAR8 *StartOfBuffer, 758 IN UINTN BufferSize, 759 IN CONST CHAR16 *FormatString, 760 ... 761 ); 762 763 /** 764 Converts a decimal value to a Null-terminated ASCII string. 765 766 Converts the decimal number specified by Value to a Null-terminated ASCII string 767 specified by Buffer containing at most Width characters. No padding of spaces 768 is ever performed. 769 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. 770 The number of ASCII characters in Buffer is returned, not including the Null-terminator. 771 If the conversion contains more than Width characters, then only the first Width 772 characters are returned, and the total number of characters required to perform 773 the conversion is returned. 774 Additional conversion parameters are specified in Flags. 775 The Flags bit LEFT_JUSTIFY is always ignored. 776 All conversions are left justified in Buffer. 777 If Width is 0, PREFIX_ZERO is ignored in Flags. 778 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas 779 are inserted every 3rd digit starting from the right. 780 If RADIX_HEX is set in Flags, then the output buffer will be 781 formatted in hexadecimal format. 782 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. 783 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, 784 then Buffer is padded with '0' characters so the combination of the optional '-' 785 sign character, '0' characters, digit characters for Value, and the Null-terminator 786 add up to Width characters. 787 788 If Buffer is NULL, then ASSERT(). 789 If unsupported bits are set in Flags, then ASSERT(). 790 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). 791 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() 792 793 @param Buffer A pointer to the output buffer for the produced Null-terminated 794 ASCII string. 795 @param Flags The bitmask of flags that specify left justification, zero pad, and commas. 796 @param Value The 64-bit signed value to convert to a string. 797 @param Width The maximum number of ASCII characters to place in Buffer, not including 798 the Null-terminator. 799 800 @return The number of ASCII characters in Buffer, not including the Null-terminator. 801 802 **/ 803 UINTN 804 EFIAPI 805 AsciiValueToString ( 806 OUT CHAR8 *Buffer, 807 IN UINTN Flags, 808 IN INT64 Value, 809 IN UINTN Width 810 ); 811 812 /** 813 Returns the number of characters that would be produced by if the formatted 814 output were produced not including the Null-terminator. 815 816 If Format is NULL, then ASSERT(). 817 If Format is not aligned on a 16-bit boundary, then ASSERT(). 818 819 @param[in] FormatString A Null-terminated Unicode format string. 820 @param[in] Marker VA_LIST marker for the variable argument list. 821 822 @return The number of characters that would be produced, not including the 823 Null-terminator. 824 **/ 825 UINTN 826 EFIAPI 827 SPrintLength ( 828 IN CONST CHAR16 *FormatString, 829 IN VA_LIST Marker 830 ); 831 832 /** 833 Returns the number of characters that would be produced by if the formatted 834 output were produced not including the Null-terminator. 835 836 If Format is NULL, then ASSERT(). 837 838 @param[in] FormatString A Null-terminated ASCII format string. 839 @param[in] Marker VA_LIST marker for the variable argument list. 840 841 @return The number of characters that would be produced, not including the 842 Null-terminator. 843 **/ 844 UINTN 845 EFIAPI 846 SPrintLengthAsciiFormat ( 847 IN CONST CHAR8 *FormatString, 848 IN VA_LIST Marker 849 ); 850 851 #endif 852