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   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 546   ASCII format string and a VA_LIST argument list.
 547
 548   This function is similar as vsnprintf_s defined in C11.
 549
 550   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 551   and BufferSize.
 552   The ASCII string is produced by parsing the format string specified by FormatString.
 553   Arguments are pulled from the variable argument list specified by Marker based on
 554   the contents of the format string.
 555   The number of ASCII characters in the produced output buffer is returned not including
 556   the Null-terminator.
 557
 558   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 559   unmodified and 0 is returned.
 560   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 561   unmodified and 0 is returned.
 562   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 563   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 564   is unmodified and 0 is returned.
 565   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 566   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 567   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 568
 569   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 570
 571   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 572                           ASCII string.
 573   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 574   @param  FormatString    A Null-terminated ASCII format string.
 575   @param  Marker          VA_LIST marker for the variable argument list.
 576
 577   @return The number of ASCII characters in the produced output buffer not including the
 578           Null-terminator.
 579
 580 **/
 581 UINTN
 582 EFIAPI
 583 AsciiVSPrint (
 584   OUT CHAR8         *StartOfBuffer,
 585   IN  UINTN         BufferSize,
 586   IN  CONST CHAR8   *FormatString,
 587   IN  VA_LIST       Marker
 588   );
 589
 590 /**
 591   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 592   ASCII format string and a BASE_LIST argument list.
 593
 594   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 595   and BufferSize.
 596   The ASCII string is produced by parsing the format string specified by FormatString.
 597   Arguments are pulled from the variable argument list specified by Marker based on
 598   the contents of the format string.
 599   The number of ASCII characters in the produced output buffer is returned not including
 600   the Null-terminator.
 601
 602   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 603   unmodified and 0 is returned.
 604   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 605   unmodified and 0 is returned.
 606   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 607   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 608   is unmodified and 0 is returned.
 609   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 610   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 611   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 612
 613   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 614
 615   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 616                           ASCII string.
 617   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 618   @param  FormatString    A Null-terminated ASCII format string.
 619   @param  Marker          BASE_LIST marker for the variable argument list.
 620
 621   @return The number of ASCII characters in the produced output buffer not including the
 622           Null-terminator.
 623
 624 **/
 625 UINTN
 626 EFIAPI
 627 AsciiBSPrint (
 628   OUT CHAR8         *StartOfBuffer,
 629   IN  UINTN         BufferSize,
 630   IN  CONST CHAR8   *FormatString,
 631   IN  BASE_LIST     Marker
 632   );
 633
 634 /**
 635   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 636   ASCII format string and  variable argument list.
 637
 638   This function is similar as snprintf_s defined in C11.
 639
 640   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 641   and BufferSize.
 642   The ASCII string is produced by parsing the format string specified by FormatString.
 643   Arguments are pulled from the variable argument list based on the contents of the
 644   format string.
 645   The number of ASCII characters in the produced output buffer is returned not including
 646   the Null-terminator.
 647
 648   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 649   unmodified and 0 is returned.
 650   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 651   unmodified and 0 is returned.
 652   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 653   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 654   is unmodified and 0 is returned.
 655   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 656   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 657   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 658
 659   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 660
 661   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 662                           ASCII string.
 663   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 664   @param  FormatString    A Null-terminated ASCII format string.
 665   @param  ...             Variable argument list whose contents are accessed based on the
 666                           format string specified by FormatString.
 667
 668   @return The number of ASCII characters in the produced output buffer not including the
 669           Null-terminator.
 670
 671 **/
 672 UINTN
 673 EFIAPI
 674 AsciiSPrint (
 675   OUT CHAR8        *StartOfBuffer,
 676   IN  UINTN        BufferSize,
 677   IN  CONST CHAR8  *FormatString,
 678   ...
 679   );
 680
 681 /**
 682   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 683   Unicode format string and a VA_LIST argument list.
 684
 685   This function is similar as vsnprintf_s defined in C11.
 686
 687   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 688   and BufferSize.
 689   The ASCII string is produced by parsing the format string specified by FormatString.
 690   Arguments are pulled from the variable argument list specified by Marker based on
 691   the contents of the format string.
 692   The number of ASCII characters in the produced output buffer is returned not including
 693   the Null-terminator.
 694
 695   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 696
 697   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 698   unmodified and 0 is returned.
 699   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 700   unmodified and 0 is returned.
 701   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 702   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 703   is unmodified and 0 is returned.
 704   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 705   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 706   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 707
 708   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 709
 710   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 711                           ASCII string.
 712   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 713   @param  FormatString    A Null-terminated Unicode format string.
 714   @param  Marker          VA_LIST marker for the variable argument list.
 715
 716   @return The number of ASCII characters in the produced output buffer not including the
 717           Null-terminator.
 718
 719 **/
 720 UINTN
 721 EFIAPI
 722 AsciiVSPrintUnicodeFormat (
 723   OUT CHAR8         *StartOfBuffer,
 724   IN  UINTN         BufferSize,
 725   IN  CONST CHAR16  *FormatString,
 726   IN  VA_LIST       Marker
 727   );
 728
 729 /**
 730   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 731   Unicode format string and a BASE_LIST argument list.
 732
 733   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 734   and BufferSize.
 735   The ASCII string is produced by parsing the format string specified by FormatString.
 736   Arguments are pulled from the variable argument list specified by Marker based on
 737   the contents of the format string.
 738   The number of ASCII characters in the produced output buffer is returned not including
 739   the Null-terminator.
 740
 741   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 742
 743   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 744   unmodified and 0 is returned.
 745   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 746   unmodified and 0 is returned.
 747   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 748   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 749   is unmodified and 0 is returned.
 750   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 751   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 752   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 753
 754   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 755
 756   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 757                           ASCII string.
 758   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 759   @param  FormatString    A Null-terminated Unicode format string.
 760   @param  Marker          BASE_LIST marker for the variable argument list.
 761
 762   @return The number of ASCII characters in the produced output buffer not including the
 763           Null-terminator.
 764
 765 **/
 766 UINTN
 767 EFIAPI
 768 AsciiBSPrintUnicodeFormat (
 769   OUT CHAR8         *StartOfBuffer,
 770   IN  UINTN         BufferSize,
 771   IN  CONST CHAR16  *FormatString,
 772   IN  BASE_LIST     Marker
 773   );
 774
 775 /**
 776   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 777   Unicode format string and  variable argument list.
 778
 779   This function is similar as snprintf_s defined in C11.
 780
 781   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 782   and BufferSize.
 783   The ASCII string is produced by parsing the format string specified by FormatString.
 784   Arguments are pulled from the variable argument list based on the contents of the
 785   format string.
 786   The number of ASCII characters in the produced output buffer is returned not including
 787   the Null-terminator.
 788
 789   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 790
 791   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 792   unmodified and 0 is returned.
 793   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 794   unmodified and 0 is returned.
 795   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 796   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 797   is unmodified and 0 is returned.
 798   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 799   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 800   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 801
 802   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 803
 804   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 805                           ASCII string.
 806   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 807   @param  FormatString    A Null-terminated Unicode format string.
 808   @param  ...             Variable argument list whose contents are accessed based on the
 809                           format string specified by FormatString.
 810
 811   @return The number of ASCII characters in the produced output buffer not including the
 812           Null-terminator.
 813
 814 **/
 815 UINTN
 816 EFIAPI
 817 AsciiSPrintUnicodeFormat (
 818   OUT CHAR8         *StartOfBuffer,
 819   IN  UINTN         BufferSize,
 820   IN  CONST CHAR16  *FormatString,
 821   ...
 822   );
 823
 824 /**
 825   Converts a decimal value to a Null-terminated ASCII string.
 826
 827   Converts the decimal number specified by Value to a Null-terminated ASCII string
 828   specified by Buffer containing at most Width characters. No padding of spaces
 829   is ever performed.
 830   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 831   The number of ASCII characters in Buffer is returned, not including the Null-terminator.
 832   If the conversion contains more than Width characters, then only the first Width
 833   characters are returned, and the total number of characters required to perform
 834   the conversion is returned.
 835   Additional conversion parameters are specified in Flags.
 836   The Flags bit LEFT_JUSTIFY is always ignored.
 837   All conversions are left justified in Buffer.
 838   If Width is 0, PREFIX_ZERO is ignored in Flags.
 839   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 840   are inserted every 3rd digit starting from the right.
 841   If RADIX_HEX is set in Flags, then the output buffer will be
 842   formatted in hexadecimal format.
 843   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 844   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 845   then Buffer is padded with '0' characters so the combination of the optional '-'
 846   sign character, '0' characters, digit characters for Value, and the Null-terminator
 847   add up to Width characters.
 848
 849   If Buffer is NULL, then ASSERT().
 850   If unsupported bits are set in Flags, then ASSERT().
 851   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 852   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 853
 854   @param  Buffer  A pointer to the output buffer for the produced Null-terminated
 855                   ASCII string.
 856   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 857   @param  Value   The 64-bit signed value to convert to a string.
 858   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 859                   the Null-terminator.
 860
 861   @return The number of ASCII characters in Buffer, not including the Null-terminator.
 862
 863 **/
 864 UINTN
 865 EFIAPI
 866 AsciiValueToString (
 867   OUT CHAR8      *Buffer,
 868   IN  UINTN      Flags,
 869   IN  INT64      Value,
 870   IN  UINTN      Width
 871   );
 872
 873 /**
 874   Returns the number of characters that would be produced by if the formatted
 875   output were produced not including the Null-terminator.
 876
 877   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 878
 879   If FormatString is NULL, then ASSERT() and 0 is returned.
 880   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
 881   than PcdMaximumUnicodeStringLength Unicode characters not including the
 882   Null-terminator, then ASSERT() and 0 is returned.
 883
 884   @param[in]  FormatString    A Null-terminated Unicode format string.
 885   @param[in]  Marker          VA_LIST marker for the variable argument list.
 886
 887   @return The number of characters that would be produced, not including the
 888           Null-terminator.
 889 **/
 890 UINTN
 891 EFIAPI
 892 SPrintLength (
 893   IN  CONST CHAR16   *FormatString,
 894   IN  VA_LIST       Marker
 895   );
 896
 897 /**
 898   Returns the number of characters that would be produced by if the formatted
 899   output were produced not including the Null-terminator.
 900
 901   If FormatString is NULL, then ASSERT() and 0 is returned.
 902   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
 903   than PcdMaximumAsciiStringLength Ascii characters not including the
 904   Null-terminator, then ASSERT() and 0 is returned.
 905
 906   @param[in]  FormatString    A Null-terminated ASCII format string.
 907   @param[in]  Marker          VA_LIST marker for the variable argument list.
 908
 909   @return The number of characters that would be produced, not including the
 910           Null-terminator.
 911 **/
 912 UINTN
 913 EFIAPI
 914 SPrintLengthAsciiFormat (
 915   IN  CONST CHAR8   *FormatString,
 916   IN  VA_LIST       Marker
 917   );
 918
 919 #endif