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 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 495
 496 /**
 497   [ATTENTION] This function is deprecated for security reason.
 498
 499   Converts a decimal value to a Null-terminated Unicode string.
 500
 501   Converts the decimal number specified by Value to a Null-terminated Unicode
 502   string specified by Buffer containing at most Width characters. No padding of spaces
 503   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 504   The number of Unicode characters in Buffer is returned, not including the Null-terminator.
 505   If the conversion contains more than Width characters, then only the first
 506   Width characters are returned, and the total number of characters
 507   required to perform the conversion is returned.
 508   Additional conversion parameters are specified in Flags.
 509
 510   The Flags bit LEFT_JUSTIFY is always ignored.
 511   All conversions are left justified in Buffer.
 512   If Width is 0, PREFIX_ZERO is ignored in Flags.
 513   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 514   are inserted every 3rd digit starting from the right.
 515   If RADIX_HEX is set in Flags, then the output buffer will be
 516   formatted in hexadecimal format.
 517   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 518   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 519   then Buffer is padded with '0' characters so the combination of the optional '-'
 520   sign character, '0' characters, digit characters for Value, and the Null-terminator
 521   add up to Width characters.
 522   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 523   If Buffer is NULL, then ASSERT().
 524   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 525   If unsupported bits are set in Flags, then ASSERT().
 526   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 527   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 528
 529   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 530                   Unicode string.
 531   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 532   @param  Value   The 64-bit signed value to convert to a string.
 533   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 534                   the Null-terminator.
 535
 536   @return The number of Unicode characters in Buffer, not including the Null-terminator.
 537
 538 **/
 539 UINTN
 540 EFIAPI
 541 UnicodeValueToString (
 542   IN OUT CHAR16  *Buffer,
 543   IN UINTN       Flags,
 544   IN INT64       Value,
 545   IN UINTN       Width
 546   );
 547
 548 #endif
 549
 550 /**
 551   Converts a decimal value to a Null-terminated Unicode string.
 552
 553   Converts the decimal number specified by Value to a Null-terminated Unicode
 554   string specified by Buffer containing at most Width characters. No padding of
 555   spaces is ever performed. If Width is 0 then a width of
 556   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 557   Width characters, then only the first Width characters are placed in Buffer.
 558   Additional conversion parameters are specified in Flags.
 559
 560   The Flags bit LEFT_JUSTIFY is always ignored.
 561   All conversions are left justified in Buffer.
 562   If Width is 0, PREFIX_ZERO is ignored in Flags.
 563   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 564   commas are inserted every 3rd digit starting from the right.
 565   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 566   hexadecimal format.
 567   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 568   Buffer is a '-'.
 569   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 570   Buffer is padded with '0' characters so the combination of the optional '-'
 571   sign character, '0' characters, digit characters for Value, and the
 572   Null-terminator add up to Width characters.
 573
 574   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 575   If an error would be returned, then the function will also ASSERT().
 576
 577   @param  Buffer      The pointer to the output buffer for the produced
 578                       Null-terminated Unicode string.
 579   @param  BufferSize  The size of Buffer in bytes, including the
 580                       Null-terminator.
 581   @param  Flags       The bitmask of flags that specify left justification,
 582                       zero pad, and commas.
 583   @param  Value       The 64-bit signed value to convert to a string.
 584   @param  Width       The maximum number of Unicode characters to place in
 585                       Buffer, not including the Null-terminator.
 586
 587   @retval RETURN_SUCCESS           The decimal value is converted.
 588   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 589                                    value.
 590   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 591                                    If PcdMaximumUnicodeStringLength is not
 592                                    zero, and BufferSize is greater than
 593                                    (PcdMaximumUnicodeStringLength *
 594                                    sizeof (CHAR16) + 1).
 595                                    If unsupported bits are set in Flags.
 596                                    If both COMMA_TYPE and RADIX_HEX are set in
 597                                    Flags.
 598                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 599
 600 **/
 601 RETURN_STATUS
 602 EFIAPI
 603 UnicodeValueToStringS (
 604   IN OUT CHAR16  *Buffer,
 605   IN UINTN       BufferSize,
 606   IN UINTN       Flags,
 607   IN INT64       Value,
 608   IN UINTN       Width
 609   );
 610
 611 /**
 612   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 613   ASCII format string and a VA_LIST argument list.
 614
 615   This function is similar as vsnprintf_s defined in C11.
 616
 617   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 618   and BufferSize.
 619   The ASCII string is produced by parsing the format string specified by FormatString.
 620   Arguments are pulled from the variable argument list specified by Marker based on
 621   the contents of the format string.
 622   The number of ASCII characters in the produced output buffer is returned not including
 623   the Null-terminator.
 624
 625   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 626   unmodified and 0 is returned.
 627   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 628   unmodified and 0 is returned.
 629   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 630   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 631   is unmodified and 0 is returned.
 632   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 633   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 634   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 635
 636   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 637
 638   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 639                           ASCII string.
 640   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 641   @param  FormatString    A Null-terminated ASCII format string.
 642   @param  Marker          VA_LIST marker for the variable argument list.
 643
 644   @return The number of ASCII characters in the produced output buffer not including the
 645           Null-terminator.
 646
 647 **/
 648 UINTN
 649 EFIAPI
 650 AsciiVSPrint (
 651   OUT CHAR8         *StartOfBuffer,
 652   IN  UINTN         BufferSize,
 653   IN  CONST CHAR8   *FormatString,
 654   IN  VA_LIST       Marker
 655   );
 656
 657 /**
 658   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 659   ASCII format string and a BASE_LIST argument list.
 660
 661   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 662   and BufferSize.
 663   The ASCII string is produced by parsing the format string specified by FormatString.
 664   Arguments are pulled from the variable argument list specified by Marker based on
 665   the contents of the format string.
 666   The number of ASCII characters in the produced output buffer is returned not including
 667   the Null-terminator.
 668
 669   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 670   unmodified and 0 is returned.
 671   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 672   unmodified and 0 is returned.
 673   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 674   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 675   is unmodified and 0 is returned.
 676   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 677   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 678   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 679
 680   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 681
 682   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 683                           ASCII string.
 684   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 685   @param  FormatString    A Null-terminated ASCII format string.
 686   @param  Marker          BASE_LIST marker for the variable argument list.
 687
 688   @return The number of ASCII characters in the produced output buffer not including the
 689           Null-terminator.
 690
 691 **/
 692 UINTN
 693 EFIAPI
 694 AsciiBSPrint (
 695   OUT CHAR8         *StartOfBuffer,
 696   IN  UINTN         BufferSize,
 697   IN  CONST CHAR8   *FormatString,
 698   IN  BASE_LIST     Marker
 699   );
 700
 701 /**
 702   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 703   ASCII format string and  variable argument list.
 704
 705   This function is similar as snprintf_s defined in C11.
 706
 707   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 708   and BufferSize.
 709   The ASCII string is produced by parsing the format string specified by FormatString.
 710   Arguments are pulled from the variable argument list based on the contents of the
 711   format string.
 712   The number of ASCII characters in the produced output buffer is returned not including
 713   the Null-terminator.
 714
 715   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 716   unmodified and 0 is returned.
 717   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 718   unmodified and 0 is returned.
 719   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 720   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 721   is unmodified and 0 is returned.
 722   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 723   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 724   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 725
 726   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 727
 728   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 729                           ASCII string.
 730   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 731   @param  FormatString    A Null-terminated ASCII format string.
 732   @param  ...             Variable argument list whose contents are accessed based on the
 733                           format string specified by FormatString.
 734
 735   @return The number of ASCII characters in the produced output buffer not including the
 736           Null-terminator.
 737
 738 **/
 739 UINTN
 740 EFIAPI
 741 AsciiSPrint (
 742   OUT CHAR8        *StartOfBuffer,
 743   IN  UINTN        BufferSize,
 744   IN  CONST CHAR8  *FormatString,
 745   ...
 746   );
 747
 748 /**
 749   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 750   Unicode format string and a VA_LIST argument list.
 751
 752   This function is similar as vsnprintf_s defined in C11.
 753
 754   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 755   and BufferSize.
 756   The ASCII string is produced by parsing the format string specified by FormatString.
 757   Arguments are pulled from the variable argument list specified by Marker based on
 758   the contents of the format string.
 759   The number of ASCII characters in the produced output buffer is returned not including
 760   the Null-terminator.
 761
 762   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 763
 764   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 765   unmodified and 0 is returned.
 766   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 767   unmodified and 0 is returned.
 768   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 769   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 770   is unmodified and 0 is returned.
 771   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 772   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 773   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 774
 775   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 776
 777   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 778                           ASCII string.
 779   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 780   @param  FormatString    A Null-terminated Unicode format string.
 781   @param  Marker          VA_LIST marker for the variable argument list.
 782
 783   @return The number of ASCII characters in the produced output buffer not including the
 784           Null-terminator.
 785
 786 **/
 787 UINTN
 788 EFIAPI
 789 AsciiVSPrintUnicodeFormat (
 790   OUT CHAR8         *StartOfBuffer,
 791   IN  UINTN         BufferSize,
 792   IN  CONST CHAR16  *FormatString,
 793   IN  VA_LIST       Marker
 794   );
 795
 796 /**
 797   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 798   Unicode format string and a BASE_LIST argument list.
 799
 800   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 801   and BufferSize.
 802   The ASCII string is produced by parsing the format string specified by FormatString.
 803   Arguments are pulled from the variable argument list specified by Marker based on
 804   the contents of the format string.
 805   The number of ASCII characters in the produced output buffer is returned not including
 806   the Null-terminator.
 807
 808   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 809
 810   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 811   unmodified and 0 is returned.
 812   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 813   unmodified and 0 is returned.
 814   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 815   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 816   is unmodified and 0 is returned.
 817   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 818   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 819   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 820
 821   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 822
 823   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 824                           ASCII string.
 825   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 826   @param  FormatString    A Null-terminated Unicode format string.
 827   @param  Marker          BASE_LIST marker for the variable argument list.
 828
 829   @return The number of ASCII characters in the produced output buffer not including the
 830           Null-terminator.
 831
 832 **/
 833 UINTN
 834 EFIAPI
 835 AsciiBSPrintUnicodeFormat (
 836   OUT CHAR8         *StartOfBuffer,
 837   IN  UINTN         BufferSize,
 838   IN  CONST CHAR16  *FormatString,
 839   IN  BASE_LIST     Marker
 840   );
 841
 842 /**
 843   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 844   Unicode format string and  variable argument list.
 845
 846   This function is similar as snprintf_s defined in C11.
 847
 848   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 849   and BufferSize.
 850   The ASCII string is produced by parsing the format string specified by FormatString.
 851   Arguments are pulled from the variable argument list based on the contents of the
 852   format string.
 853   The number of ASCII characters in the produced output buffer is returned not including
 854   the Null-terminator.
 855
 856   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 857
 858   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 859   unmodified and 0 is returned.
 860   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 861   unmodified and 0 is returned.
 862   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 863   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 864   is unmodified and 0 is returned.
 865   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 866   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 867   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 868
 869   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 870
 871   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 872                           ASCII string.
 873   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 874   @param  FormatString    A Null-terminated Unicode format string.
 875   @param  ...             Variable argument list whose contents are accessed based on the
 876                           format string specified by FormatString.
 877
 878   @return The number of ASCII characters in the produced output buffer not including the
 879           Null-terminator.
 880
 881 **/
 882 UINTN
 883 EFIAPI
 884 AsciiSPrintUnicodeFormat (
 885   OUT CHAR8         *StartOfBuffer,
 886   IN  UINTN         BufferSize,
 887   IN  CONST CHAR16  *FormatString,
 888   ...
 889   );
 890
 891 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 892
 893 /**
 894   [ATTENTION] This function is deprecated for security reason.
 895
 896   Converts a decimal value to a Null-terminated ASCII string.
 897
 898   Converts the decimal number specified by Value to a Null-terminated ASCII string
 899   specified by Buffer containing at most Width characters. No padding of spaces
 900   is ever performed.
 901   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 902   The number of ASCII characters in Buffer is returned, not including the Null-terminator.
 903   If the conversion contains more than Width characters, then only the first Width
 904   characters are returned, and the total number of characters required to perform
 905   the conversion is returned.
 906   Additional conversion parameters are specified in Flags.
 907   The Flags bit LEFT_JUSTIFY is always ignored.
 908   All conversions are left justified in Buffer.
 909   If Width is 0, PREFIX_ZERO is ignored in Flags.
 910   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 911   are inserted every 3rd digit starting from the right.
 912   If RADIX_HEX is set in Flags, then the output buffer will be
 913   formatted in hexadecimal format.
 914   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 915   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 916   then Buffer is padded with '0' characters so the combination of the optional '-'
 917   sign character, '0' characters, digit characters for Value, and the Null-terminator
 918   add up to Width characters.
 919
 920   If Buffer is NULL, then ASSERT().
 921   If unsupported bits are set in Flags, then ASSERT().
 922   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 923   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 924
 925   @param  Buffer  A pointer to the output buffer for the produced Null-terminated
 926                   ASCII string.
 927   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 928   @param  Value   The 64-bit signed value to convert to a string.
 929   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 930                   the Null-terminator.
 931
 932   @return The number of ASCII characters in Buffer, not including the Null-terminator.
 933
 934 **/
 935 UINTN
 936 EFIAPI
 937 AsciiValueToString (
 938   OUT CHAR8      *Buffer,
 939   IN  UINTN      Flags,
 940   IN  INT64      Value,
 941   IN  UINTN      Width
 942   );
 943
 944 #endif
 945
 946 /**
 947   Converts a decimal value to a Null-terminated Ascii string.
 948
 949   Converts the decimal number specified by Value to a Null-terminated Ascii
 950   string specified by Buffer containing at most Width characters. No padding of
 951   spaces is ever performed. If Width is 0 then a width of
 952   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 953   Width characters, then only the first Width characters are placed in Buffer.
 954   Additional conversion parameters are specified in Flags.
 955
 956   The Flags bit LEFT_JUSTIFY is always ignored.
 957   All conversions are left justified in Buffer.
 958   If Width is 0, PREFIX_ZERO is ignored in Flags.
 959   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 960   commas are inserted every 3rd digit starting from the right.
 961   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 962   hexadecimal format.
 963   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 964   Buffer is a '-'.
 965   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 966   Buffer is padded with '0' characters so the combination of the optional '-'
 967   sign character, '0' characters, digit characters for Value, and the
 968   Null-terminator add up to Width characters.
 969
 970   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 971   If an error would be returned, then the function will also ASSERT().
 972
 973   @param  Buffer      The pointer to the output buffer for the produced
 974                       Null-terminated Ascii string.
 975   @param  BufferSize  The size of Buffer in bytes, including the
 976                       Null-terminator.
 977   @param  Flags       The bitmask of flags that specify left justification,
 978                       zero pad, and commas.
 979   @param  Value       The 64-bit signed value to convert to a string.
 980   @param  Width       The maximum number of Ascii characters to place in
 981                       Buffer, not including the Null-terminator.
 982
 983   @retval RETURN_SUCCESS           The decimal value is converted.
 984   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 985                                    value.
 986   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 987                                    If PcdMaximumAsciiStringLength is not
 988                                    zero, and BufferSize is greater than
 989                                    PcdMaximumAsciiStringLength.
 990                                    If unsupported bits are set in Flags.
 991                                    If both COMMA_TYPE and RADIX_HEX are set in
 992                                    Flags.
 993                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 994
 995 **/
 996 RETURN_STATUS
 997 EFIAPI
 998 AsciiValueToStringS (
 999   IN OUT CHAR8   *Buffer,
1000   IN UINTN       BufferSize,
1001   IN UINTN       Flags,
1002   IN INT64       Value,
1003   IN UINTN       Width
1004   );
1005
1006 /**
1007   Returns the number of characters that would be produced by if the formatted
1008   output were produced not including the Null-terminator.
1009
1010   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1011
1012   If FormatString is NULL, then ASSERT() and 0 is returned.
1013   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
1014   than PcdMaximumUnicodeStringLength Unicode characters not including the
1015   Null-terminator, then ASSERT() and 0 is returned.
1016
1017   @param[in]  FormatString    A Null-terminated Unicode format string.
1018   @param[in]  Marker          VA_LIST marker for the variable argument list.
1019
1020   @return The number of characters that would be produced, not including the
1021           Null-terminator.
1022 **/
1023 UINTN
1024 EFIAPI
1025 SPrintLength (
1026   IN  CONST CHAR16   *FormatString,
1027   IN  VA_LIST       Marker
1028   );
1029
1030 /**
1031   Returns the number of characters that would be produced by if the formatted
1032   output were produced not including the Null-terminator.
1033
1034   If FormatString is NULL, then ASSERT() and 0 is returned.
1035   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
1036   than PcdMaximumAsciiStringLength Ascii characters not including the
1037   Null-terminator, then ASSERT() and 0 is returned.
1038
1039   @param[in]  FormatString    A Null-terminated ASCII format string.
1040   @param[in]  Marker          VA_LIST marker for the variable argument list.
1041
1042   @return The number of characters that would be produced, not including the
1043           Null-terminator.
1044 **/
1045 UINTN
1046 EFIAPI
1047 SPrintLengthAsciiFormat (
1048   IN  CONST CHAR8   *FormatString,
1049   IN  VA_LIST       Marker
1050   );
1051
1052 #endif