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 - 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