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