MdePkg/Include/Library/PrintLib.h

   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 - 2013, 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     - p
  93       - The argument is a pointer that is a (VOID *), and it is printed as an
  94         unsigned hexadecimal number  The characters used are 0..9 and A..F.
  95     - a
  96       - The argument is a pointer to an ASCII string.
  97         This does not follow ANSI C.
  98     - S, s
  99       - The argument is a pointer to a Unicode string.
 100         This does not follow ANSI C.
 101     - g
 102       - The argument is a pointer to a GUID structure.  The GUID is printed
 103         in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
 104         This does not follow ANSI C.
 105     - t
 106       - The argument is a pointer to an EFI_TIME structure.  The time and
 107         date are printed in the format "mm/dd/yyyy hh:mm" where mm is the
 108         month zero padded, dd is the day zero padded, yyyy is the year zero
 109         padded, hh is the hour zero padded, and mm is minutes zero padded.
 110         This does not follow ANSI C.
 111     - r
 112       - The argument is a RETURN_STATUS value.  This value is converted to
 113         a string following the table below.  This does not follow ANSI C.
 114       - RETURN_SUCCESS
 115         - "Success"
 116       - RETURN_LOAD_ERROR
 117         - "Load Error"
 118       - RETURN_INVALID_PARAMETER
 119         - "Invalid Parameter"
 120       - RETURN_UNSUPPORTED
 121         - "Unsupported"
 122       - RETURN_BAD_BUFFER_SIZE
 123         - "Bad Buffer Size"
 124       - RETURN_BUFFER_TOO_SMALL
 125         - "Buffer Too Small"
 126       - RETURN_NOT_READY
 127         - "Not Ready"
 128       - RETURN_DEVICE_ERROR
 129         - "Device Error"
 130       - RETURN_WRITE_PROTECTED
 131         - "Write Protected"
 132       - RETURN_OUT_OF_RESOURCES
 133         - "Out of Resources"
 134       - RETURN_VOLUME_CORRUPTED
 135         - "Volume Corrupt"
 136       - RETURN_VOLUME_FULL
 137         - "Volume Full"
 138       - RETURN_NO_MEDIA
 139         - "No Media"
 140       - RETURN_MEDIA_CHANGED
 141         - "Media changed"
 142       - RETURN_NOT_FOUND
 143         - "Not Found"
 144       - RETURN_ACCESS_DENIED
 145         - "Access Denied"
 146       - RETURN_NO_RESPONSE
 147         - "No Response"
 148       - RETURN_NO_MAPPING
 149         - "No mapping"
 150       - RETURN_TIMEOUT
 151         - "Time out"
 152       - RETURN_NOT_STARTED
 153         - "Not started"
 154       - RETURN_ALREADY_STARTED
 155         - "Already started"
 156       - RETURN_ABORTED
 157         - "Aborted"
 158       - RETURN_ICMP_ERROR
 159         - "ICMP Error"
 160       - RETURN_TFTP_ERROR
 161         - "TFTP Error"
 162       - RETURN_PROTOCOL_ERROR
 163         - "Protocol Error"
 164       - RETURN_WARN_UNKNOWN_GLYPH
 165         - "Warning Unknown Glyph"
 166       - RETURN_WARN_DELETE_FAILURE
 167         - "Warning Delete Failure"
 168       - RETURN_WARN_WRITE_FAILURE
 169         - "Warning Write Failure"
 170       - RETURN_WARN_BUFFER_TOO_SMALL
 171         - "Warning Buffer Too Small"
 172
 173 **/
 174
 175 #ifndef __PRINT_LIB_H__
 176 #define __PRINT_LIB_H__
 177
 178 ///
 179 /// Define the maximum number of characters that are required to
 180 /// encode with a NULL terminator a decimal, hexadecimal, GUID,
 181 /// or TIME value.
 182 ///
 183 ///  Maximum Length Decimal String     = 28
 184 ///    "-9,223,372,036,854,775,808"
 185 ///  Maximum Length Hexadecimal String = 17
 186 ///    "FFFFFFFFFFFFFFFF"
 187 ///  Maximum Length GUID               = 37
 188 ///    "00000000-0000-0000-0000-000000000000"
 189 ///  Maximum Length TIME               = 18
 190 ///    "12/12/2006  12:12"
 191 ///
 192 #define MAXIMUM_VALUE_CHARACTERS  38
 193
 194 ///
 195 /// Flags bitmask values use in UnicodeValueToString() and
 196 /// AsciiValueToString()
 197 ///
 198 #define LEFT_JUSTIFY      0x01
 199 #define COMMA_TYPE        0x08
 200 #define PREFIX_ZERO       0x20
 201 #define RADIX_HEX         0x80
 202
 203 /**
 204   Produces a Null-terminated Unicode string in an output buffer based on
 205   a Null-terminated Unicode format string and a VA_LIST argument list.
 206
 207   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 208   and BufferSize.
 209   The Unicode string is produced by parsing the format string specified by FormatString.
 210   Arguments are pulled from the variable argument list specified by Marker based on the
 211   contents of the format string.
 212   The number of Unicode characters in the produced output buffer is returned, not including
 213   the Null-terminator.
 214   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 215
 216   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 217   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 218   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 219   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 220   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 221   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then
 222   ASSERT().
 223   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 224   contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the
 225   Null-terminator, then ASSERT().
 226
 227   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 228                           Unicode string.
 229   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 230   @param  FormatString    Null-terminated Unicode format string.
 231   @param  Marker          VA_LIST marker for the variable argument list.
 232
 233   @return The number of Unicode characters in the produced output buffer, not including the
 234           Null-terminator.
 235
 236 **/
 237 UINTN
 238 EFIAPI
 239 UnicodeVSPrint (
 240   OUT CHAR16        *StartOfBuffer,
 241   IN  UINTN         BufferSize,
 242   IN  CONST CHAR16  *FormatString,
 243   IN  VA_LIST       Marker
 244   );
 245
 246 /**
 247   Produces a Null-terminated Unicode string in an output buffer based on
 248   a Null-terminated Unicode format string and a BASE_LIST argument list.
 249
 250   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 251   and BufferSize.
 252   The Unicode string is produced by parsing the format string specified by FormatString.
 253   Arguments are pulled from the variable argument list specified by Marker based on the
 254   contents of the format string.
 255   The number of Unicode characters in the produced output buffer is returned, not including
 256   the Null-terminator.
 257   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 258
 259   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 260   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 261   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 262   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 263   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 264   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then
 265   ASSERT().
 266   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 267   contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the
 268   Null-terminator, then ASSERT().
 269
 270   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 271                           Unicode string.
 272   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 273   @param  FormatString    Null-terminated Unicode format string.
 274   @param  Marker          BASE_LIST marker for the variable argument list.
 275
 276   @return The number of Unicode characters in the produced output buffer, not including the
 277           Null-terminator.
 278
 279 **/
 280 UINTN
 281 EFIAPI
 282 UnicodeBSPrint (
 283   OUT CHAR16        *StartOfBuffer,
 284   IN  UINTN         BufferSize,
 285   IN  CONST CHAR16  *FormatString,
 286   IN  BASE_LIST     Marker
 287   );
 288
 289 /**
 290   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 291   Unicode format string and variable argument list.
 292
 293   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 294   and BufferSize.
 295   The Unicode string is produced by parsing the format string specified by FormatString.
 296   Arguments are pulled from the variable argument list based on the contents of the format string.
 297   The number of Unicode characters in the produced output buffer is returned, not including
 298   the Null-terminator.
 299   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 300
 301   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 302   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 303   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 304   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 305   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 306   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 307   ASSERT().
 308   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 309   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 310   Null-terminator, then ASSERT().
 311
 312   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 313                           Unicode string.
 314   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 315   @param  FormatString    A null-terminated Unicode format string.
 316   @param  ...             The variable argument list whose contents are accessed based on the
 317                           format string specified by FormatString.
 318
 319   @return The number of Unicode characters in the produced output buffer, not including the
 320           Null-terminator.
 321
 322 **/
 323 UINTN
 324 EFIAPI
 325 UnicodeSPrint (
 326   OUT CHAR16        *StartOfBuffer,
 327   IN  UINTN         BufferSize,
 328   IN  CONST CHAR16  *FormatString,
 329   ...
 330   );
 331
 332 /**
 333   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 334   ASCII format string and a VA_LIST argument list
 335
 336   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 337   and BufferSize.
 338   The Unicode string is produced by parsing the format string specified by FormatString.
 339   Arguments are pulled from the variable argument list specified by Marker based on the
 340   contents of the format string.
 341   The number of Unicode characters in the produced output buffer is returned, not including
 342   the Null-terminator.
 343   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 344
 345   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 346   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 347   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 348   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 349   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 350   ASSERT().
 351   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 352   contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the
 353   Null-terminator, then ASSERT().
 354
 355   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 356                           Unicode string.
 357   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 358   @param  FormatString    A null-terminated ASCII format string.
 359   @param  Marker          VA_LIST marker for the variable argument list.
 360
 361   @return The number of Unicode characters in the produced output buffer not including the
 362           Null-terminator.
 363
 364 **/
 365 UINTN
 366 EFIAPI
 367 UnicodeVSPrintAsciiFormat (
 368   OUT CHAR16       *StartOfBuffer,
 369   IN  UINTN        BufferSize,
 370   IN  CONST CHAR8  *FormatString,
 371   IN  VA_LIST      Marker
 372   );
 373
 374 /**
 375   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 376   ASCII format string and a BASE_LIST argument list
 377
 378   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 379   and BufferSize.
 380   The Unicode string is produced by parsing the format string specified by FormatString.
 381   Arguments are pulled from the variable argument list specified by Marker based on the
 382   contents of the format string.
 383   The number of Unicode characters in the produced output buffer is returned, not including
 384   the Null-terminator.
 385   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 386
 387   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 388   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 389   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 390   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 391   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 392   ASSERT().
 393   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 394   contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the
 395   Null-terminator, then ASSERT().
 396
 397   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 398                           Unicode string.
 399   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 400   @param  FormatString    A null-terminated ASCII format string.
 401   @param  Marker          A BASE_LIST marker for the variable argument list.
 402
 403   @return The number of Unicode characters in the produced output buffer, not including the
 404           Null-terminator.
 405
 406 **/
 407 UINTN
 408 EFIAPI
 409 UnicodeBSPrintAsciiFormat (
 410   OUT CHAR16       *StartOfBuffer,
 411   IN  UINTN        BufferSize,
 412   IN  CONST CHAR8  *FormatString,
 413   IN  BASE_LIST    Marker
 414   );
 415
 416 /**
 417   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 418   ASCII format string and  variable argument list.
 419
 420   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 421   and BufferSize.
 422   The Unicode string is produced by parsing the format string specified by FormatString.
 423   Arguments are pulled from the variable argument list based on the contents of the
 424   format string.
 425   The number of Unicode characters in the produced output buffer is returned, not including
 426   the Null-terminator.
 427   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 428
 429   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 430   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 431   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 432   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 433   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 434   ASSERT().
 435   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 436   contains more than PcdMaximumUnicodeStringLength Unicode characters, the
 437   Null-terminator, then ASSERT().
 438
 439   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 440                           Unicode string.
 441   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 442   @param  FormatString    A null-terminated ASCII format string.
 443   @param  ...             Variable argument list whose contents are accessed based on the
 444                           format string specified by FormatString.
 445
 446   @return The number of Unicode characters in the produced output buffer, not including the
 447           Null-terminator.
 448
 449 **/
 450 UINTN
 451 EFIAPI
 452 UnicodeSPrintAsciiFormat (
 453   OUT CHAR16       *StartOfBuffer,
 454   IN  UINTN        BufferSize,
 455   IN  CONST CHAR8  *FormatString,
 456   ...
 457   );
 458
 459 /**
 460   Converts a decimal value to a Null-terminated Unicode string.
 461
 462   Converts the decimal number specified by Value to a Null-terminated Unicode
 463   string specified by Buffer containing at most Width characters. No padding of spaces
 464   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 465   The number of Unicode characters in Buffer is returned, not including the Null-terminator.
 466   If the conversion contains more than Width characters, then only the first
 467   Width characters are returned, and the total number of characters
 468   required to perform the conversion is returned.
 469   Additional conversion parameters are specified in Flags.
 470
 471   The Flags bit LEFT_JUSTIFY is always ignored.
 472   All conversions are left justified in Buffer.
 473   If Width is 0, PREFIX_ZERO is ignored in Flags.
 474   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 475   are inserted every 3rd digit starting from the right.
 476   If RADIX_HEX is set in Flags, then the output buffer will be
 477   formatted in hexadecimal format.
 478   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 479   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 480   then Buffer is padded with '0' characters so the combination of the optional '-'
 481   sign character, '0' characters, digit characters for Value, and the Null-terminator
 482   add up to Width characters.
 483   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 484   If Buffer is NULL, then ASSERT().
 485   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 486   If unsupported bits are set in Flags, then ASSERT().
 487   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 488   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 489
 490   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 491                   Unicode string.
 492   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 493   @param  Value   The 64-bit signed value to convert to a string.
 494   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 495                   the Null-terminator.
 496
 497   @return The number of Unicode characters in Buffer, not including the Null-terminator.
 498
 499 **/
 500 UINTN
 501 EFIAPI
 502 UnicodeValueToString (
 503   IN OUT CHAR16  *Buffer,
 504   IN UINTN       Flags,
 505   IN INT64       Value,
 506   IN UINTN       Width
 507   );
 508
 509 /**
 510   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 511   ASCII format string and a VA_LIST argument list.
 512
 513   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 514   and BufferSize.
 515   The ASCII string is produced by parsing the format string specified by FormatString.
 516   Arguments are pulled from the variable argument list specified by Marker based on
 517   the contents of the format string.
 518   The number of ASCII characters in the produced output buffer is returned, not including
 519   the Null-terminator.
 520   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 521
 522   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 523   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 524   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 525   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 526   ASSERT().
 527   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 528   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 529   Null-terminator, then ASSERT().
 530
 531   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 532                           ASCII string.
 533   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 534   @param  FormatString    A null-terminated ASCII format string.
 535   @param  Marker          VA_LIST marker for the variable argument list.
 536
 537   @return The number of ASCII characters in the produced output buffer, not including the
 538           Null-terminator.
 539
 540 **/
 541 UINTN
 542 EFIAPI
 543 AsciiVSPrint (
 544   OUT CHAR8         *StartOfBuffer,
 545   IN  UINTN         BufferSize,
 546   IN  CONST CHAR8   *FormatString,
 547   IN  VA_LIST       Marker
 548   );
 549
 550 /**
 551   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 552   ASCII format string and a BASE_LIST argument list.
 553
 554   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 555   and BufferSize.
 556   The ASCII string is produced by parsing the format string specified by FormatString.
 557   Arguments are pulled from the variable argument list specified by Marker based on
 558   the contents of the format string.
 559   The number of ASCII characters in the produced output buffer is returned, not including
 560   the Null-terminator.
 561   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 562
 563   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 564   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 565   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 566   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 567   ASSERT().
 568   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 569   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 570   Null-terminator, then ASSERT().
 571
 572   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 573                           ASCII string.
 574   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 575   @param  FormatString    A null-terminated ASCII format string.
 576   @param  Marker          BASE_LIST marker for the variable argument list.
 577
 578   @return The number of ASCII characters in the produced output buffer, not including the
 579           Null-terminator.
 580
 581 **/
 582 UINTN
 583 EFIAPI
 584 AsciiBSPrint (
 585   OUT CHAR8         *StartOfBuffer,
 586   IN  UINTN         BufferSize,
 587   IN  CONST CHAR8   *FormatString,
 588   IN  BASE_LIST     Marker
 589   );
 590
 591 /**
 592   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 593   ASCII format string and  variable argument list.
 594
 595   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 596   and BufferSize.
 597   The ASCII string is produced by parsing the format string specified by FormatString.
 598   Arguments are pulled from the variable argument list based on the contents of the
 599   format string.
 600   The number of ASCII characters in the produced output buffer is returned, not including
 601   the Null-terminator.
 602   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 603
 604   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 605   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 606   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 607   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, then
 608   ASSERT().
 609   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 610   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 611   Null-terminator, then ASSERT().
 612
 613   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 614                           ASCII string.
 615   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 616   @param  FormatString    A null-terminated ASCII format string.
 617   @param  ...             The variable argument list whose contents are accessed based on the
 618                           format string specified by FormatString.
 619
 620   @return The number of ASCII characters in the produced output buffer, not including the
 621           Null-terminator.
 622
 623 **/
 624 UINTN
 625 EFIAPI
 626 AsciiSPrint (
 627   OUT CHAR8        *StartOfBuffer,
 628   IN  UINTN        BufferSize,
 629   IN  CONST CHAR8  *FormatString,
 630   ...
 631   );
 632
 633 /**
 634   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 635   Unicode format string and a VA_LIST argument list.
 636
 637   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 638   and BufferSize.
 639   The ASCII string is produced by parsing the format string specified by FormatString.
 640   Arguments are pulled from the variable argument list specified by Marker based on
 641   the contents of the format string.
 642   The number of ASCII characters in the produced output buffer is returned, not including
 643   the Null-terminator.
 644   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 645
 646   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 647   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 648   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 649   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 650   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then
 651   ASSERT().
 652   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 653   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 654   Null-terminator, then ASSERT().
 655
 656   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 657                           ASCII string.
 658   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 659   @param  FormatString    A null-terminated Unicode format string.
 660   @param  Marker          VA_LIST marker for the variable argument list.
 661
 662   @return The number of ASCII characters in the produced output buffer, not including the
 663           Null-terminator.
 664
 665 **/
 666 UINTN
 667 EFIAPI
 668 AsciiVSPrintUnicodeFormat (
 669   OUT CHAR8         *StartOfBuffer,
 670   IN  UINTN         BufferSize,
 671   IN  CONST CHAR16  *FormatString,
 672   IN  VA_LIST       Marker
 673   );
 674
 675 /**
 676   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 677   Unicode format string and a BASE_LIST argument list.
 678
 679   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 680   and BufferSize.
 681   The ASCII string is produced by parsing the format string specified by FormatString.
 682   Arguments are pulled from the variable argument list specified by Marker based on
 683   the contents of the format string.
 684   The number of ASCII characters in the produced output buffer is returned, not including
 685   the Null-terminator.
 686   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 687
 688   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 689   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 690   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 691   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 692   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then
 693   ASSERT().
 694   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 695   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 696   Null-terminator, then ASSERT().
 697
 698   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 699                           ASCII string.
 700   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 701   @param  FormatString    A null-terminated Unicode format string.
 702   @param  Marker          BASE_LIST marker for the variable argument list.
 703
 704   @return The number of ASCII characters in the produced output buffer, not including the
 705           Null-terminator.
 706
 707 **/
 708 UINTN
 709 EFIAPI
 710 AsciiBSPrintUnicodeFormat (
 711   OUT CHAR8         *StartOfBuffer,
 712   IN  UINTN         BufferSize,
 713   IN  CONST CHAR16  *FormatString,
 714   IN  BASE_LIST     Marker
 715   );
 716
 717 /**
 718   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 719   Unicode format string and  variable argument list.
 720
 721   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 722   and BufferSize.
 723   The ASCII string is produced by parsing the format string specified by FormatString.
 724   Arguments are pulled from the variable argument list based on the contents of the
 725   format string.
 726   The number of ASCII characters in the produced output buffer is returned, not including
 727   the Null-terminator.
 728   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 729
 730   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 731   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 732   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 733   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 734   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, then
 735   ASSERT().
 736   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 737   contains more than PcdMaximumAsciiStringLength ASCII characters, not including the
 738   Null-terminator, then ASSERT().
 739
 740   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 741                           ASCII string.
 742   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 743   @param  FormatString    A null-terminated Unicode format string.
 744   @param  ...             Variable argument list whose contents are accessed based on the
 745                           format string specified by FormatString.
 746
 747   @return The number of ASCII characters in the produced output buffer, not including the
 748           Null-terminator.
 749
 750 **/
 751 UINTN
 752 EFIAPI
 753 AsciiSPrintUnicodeFormat (
 754   OUT CHAR8         *StartOfBuffer,
 755   IN  UINTN         BufferSize,
 756   IN  CONST CHAR16  *FormatString,
 757   ...
 758   );
 759
 760 /**
 761   Converts a decimal value to a Null-terminated ASCII string.
 762
 763   Converts the decimal number specified by Value to a Null-terminated ASCII string
 764   specified by Buffer containing at most Width characters. No padding of spaces
 765   is ever performed.
 766   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 767   The number of ASCII characters in Buffer is returned, not including the Null-terminator.
 768   If the conversion contains more than Width characters, then only the first Width
 769   characters are returned, and the total number of characters required to perform
 770   the conversion is returned.
 771   Additional conversion parameters are specified in Flags.
 772   The Flags bit LEFT_JUSTIFY is always ignored.
 773   All conversions are left justified in Buffer.
 774   If Width is 0, PREFIX_ZERO is ignored in Flags.
 775   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 776   are inserted every 3rd digit starting from the right.
 777   If RADIX_HEX is set in Flags, then the output buffer will be
 778   formatted in hexadecimal format.
 779   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 780   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 781   then Buffer is padded with '0' characters so the combination of the optional '-'
 782   sign character, '0' characters, digit characters for Value, and the Null-terminator
 783   add up to Width characters.
 784
 785   If Buffer is NULL, then ASSERT().
 786   If unsupported bits are set in Flags, then ASSERT().
 787   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 788   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 789
 790   @param  Buffer  A pointer to the output buffer for the produced Null-terminated
 791                   ASCII string.
 792   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 793   @param  Value   The 64-bit signed value to convert to a string.
 794   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 795                   the Null-terminator.
 796
 797   @return The number of ASCII characters in Buffer, not including the Null-terminator.
 798
 799 **/
 800 UINTN
 801 EFIAPI
 802 AsciiValueToString (
 803   OUT CHAR8      *Buffer,
 804   IN  UINTN      Flags,
 805   IN  INT64      Value,
 806   IN  UINTN      Width
 807   );
 808
 809 /**
 810   Returns the number of characters that would be produced by if the formatted
 811   output were produced not including the Null-terminator.
 812
 813   If Format is NULL, then ASSERT().
 814   If Format is not aligned on a 16-bit boundary, then ASSERT().
 815
 816   @param[in]  FormatString    A Null-terminated Unicode format string.
 817   @param[in]  Marker          VA_LIST marker for the variable argument list.
 818
 819   @return The number of characters that would be produced, not including the
 820           Null-terminator.
 821 **/
 822 UINTN
 823 EFIAPI
 824 SPrintLength (
 825   IN  CONST CHAR16   *FormatString,
 826   IN  VA_LIST       Marker
 827   );
 828
 829 /**
 830   Returns the number of characters that would be produced by if the formatted
 831   output were produced not including the Null-terminator.
 832
 833   If Format is NULL, then ASSERT().
 834
 835   @param[in]  FormatString    A Null-terminated ASCII format string.
 836   @param[in]  Marker          VA_LIST marker for the variable argument list.
 837
 838   @return The number of characters that would be produced, not including the
 839           Null-terminator.
 840 **/
 841 UINTN
 842 EFIAPI
 843 SPrintLengthAsciiFormat (
 844   IN  CONST CHAR8   *FormatString,
 845   IN  VA_LIST       Marker
 846   );
 847
 848 #endif