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