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