MdePkg/Library/BasePrintLib/PrintLib.c

   1 /** @file
   2   Base Print Library instance implementation.
   3
   4   Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
   5   Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "PrintLibInternal.h"
  17
  18 //
  19 // Declare a VA_LIST global variable that is used in calls to BasePrintLibSPrintMarker()
  20 // when the BASE_LIST parameter is valid and the VA_LIST parameter is ignored.
  21 // A NULL VA_LIST can not be passed into  BasePrintLibSPrintMarker() because some
  22 // compilers define VA_LIST to be a structure.
  23 //
  24 VA_LIST gNullVaList;
  25
  26 #define ASSERT_UNICODE_BUFFER(Buffer) ASSERT ((((UINTN) (Buffer)) & 0x01) == 0)
  27
  28 /**
  29   Produces a Null-terminated Unicode string in an output buffer based on
  30   a Null-terminated Unicode format string and a VA_LIST argument list.
  31
  32   This function is similar as vsnprintf_s defined in C11.
  33
  34   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  35   and BufferSize.
  36   The Unicode string is produced by parsing the format string specified by FormatString.
  37   Arguments are pulled from the variable argument list specified by Marker based on the
  38   contents of the format string.
  39   The number of Unicode characters in the produced output buffer is returned not including
  40   the Null-terminator.
  41
  42   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  43   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
  44
  45   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
  46   unmodified and 0 is returned.
  47   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
  48   unmodified and 0 is returned.
  49   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
  50   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
  51   buffer is unmodified and 0 is returned.
  52   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  53   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  54   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
  55
  56   If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
  57
  58   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  59                           Unicode string.
  60   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  61   @param  FormatString    A Null-terminated Unicode format string.
  62   @param  Marker          VA_LIST marker for the variable argument list.
  63
  64   @return The number of Unicode characters in the produced output buffer not including the
  65           Null-terminator.
  66
  67 **/
  68 UINTN
  69 EFIAPI
  70 UnicodeVSPrint (
  71   OUT CHAR16        *StartOfBuffer,
  72   IN  UINTN         BufferSize,
  73   IN  CONST CHAR16  *FormatString,
  74   IN  VA_LIST       Marker
  75   )
  76 {
  77   ASSERT_UNICODE_BUFFER (StartOfBuffer);
  78   ASSERT_UNICODE_BUFFER (FormatString);
  79   return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);
  80 }
  81
  82 /**
  83   Produces a Null-terminated Unicode string in an output buffer based on
  84   a Null-terminated Unicode format string and a BASE_LIST argument list.
  85
  86   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  87   and BufferSize.
  88   The Unicode string is produced by parsing the format string specified by FormatString.
  89   Arguments are pulled from the variable argument list specified by Marker based on the
  90   contents of the format string.
  91   The number of Unicode characters in the produced output buffer is returned not including
  92   the Null-terminator.
  93
  94   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  95   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
  96
  97   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
  98   unmodified and 0 is returned.
  99   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 100   unmodified and 0 is returned.
 101   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
 102   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
 103   buffer is unmodified and 0 is returned.
 104   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 105   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 106   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 107
 108   If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
 109
 110   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 111                           Unicode string.
 112   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 113   @param  FormatString    A Null-terminated Unicode format string.
 114   @param  Marker          BASE_LIST marker for the variable argument list.
 115
 116   @return The number of Unicode characters in the produced output buffer not including the
 117           Null-terminator.
 118
 119 **/
 120 UINTN
 121 EFIAPI
 122 UnicodeBSPrint (
 123   OUT CHAR16        *StartOfBuffer,
 124   IN  UINTN         BufferSize,
 125   IN  CONST CHAR16  *FormatString,
 126   IN  BASE_LIST     Marker
 127   )
 128 {
 129   ASSERT_UNICODE_BUFFER (StartOfBuffer);
 130   ASSERT_UNICODE_BUFFER (FormatString);
 131   return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, gNullVaList, Marker);
 132 }
 133
 134 /**
 135   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 136   Unicode format string and variable argument list.
 137
 138   This function is similar as snprintf_s defined in C11.
 139
 140   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 141   and BufferSize.
 142   The Unicode string is produced by parsing the format string specified by FormatString.
 143   Arguments are pulled from the variable argument list based on the contents of the format string.
 144   The number of Unicode characters in the produced output buffer is returned not including
 145   the Null-terminator.
 146
 147   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 148   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 149
 150   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 151   unmodified and 0 is returned.
 152   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 153   unmodified and 0 is returned.
 154   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
 155   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
 156   buffer is unmodified and 0 is returned.
 157   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 158   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 159   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 160
 161   If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
 162
 163   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 164                           Unicode string.
 165   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 166   @param  FormatString    A Null-terminated Unicode format string.
 167   @param  ...             Variable argument list whose contents are accessed based on the
 168                           format string specified by FormatString.
 169
 170   @return The number of Unicode characters in the produced output buffer not including the
 171           Null-terminator.
 172
 173 **/
 174 UINTN
 175 EFIAPI
 176 UnicodeSPrint (
 177   OUT CHAR16        *StartOfBuffer,
 178   IN  UINTN         BufferSize,
 179   IN  CONST CHAR16  *FormatString,
 180   ...
 181   )
 182 {
 183   VA_LIST Marker;
 184   UINTN   NumberOfPrinted;
 185
 186   VA_START (Marker, FormatString);
 187   NumberOfPrinted = UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 188   VA_END (Marker);
 189   return NumberOfPrinted;
 190 }
 191
 192 /**
 193   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 194   ASCII format string and a VA_LIST argument list.
 195
 196   This function is similar as vsnprintf_s defined in C11.
 197
 198   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 199   and BufferSize.
 200   The Unicode string is produced by parsing the format string specified by FormatString.
 201   Arguments are pulled from the variable argument list specified by Marker based on the
 202   contents of the format string.
 203   The number of Unicode characters in the produced output buffer is returned not including
 204   the Null-terminator.
 205
 206   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 207
 208   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 209   unmodified and 0 is returned.
 210   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 211   unmodified and 0 is returned.
 212   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
 213   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
 214   buffer is unmodified and 0 is returned.
 215   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 216   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 217   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 218
 219   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 220
 221   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 222                           Unicode string.
 223   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 224   @param  FormatString    A Null-terminated ASCII format string.
 225   @param  Marker          VA_LIST marker for the variable argument list.
 226
 227   @return The number of Unicode characters in the produced output buffer not including the
 228           Null-terminator.
 229
 230 **/
 231 UINTN
 232 EFIAPI
 233 UnicodeVSPrintAsciiFormat (
 234   OUT CHAR16       *StartOfBuffer,
 235   IN  UINTN        BufferSize,
 236   IN  CONST CHAR8  *FormatString,
 237   IN  VA_LIST      Marker
 238   )
 239 {
 240   ASSERT_UNICODE_BUFFER (StartOfBuffer);
 241   return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE, FormatString, Marker, NULL);
 242 }
 243
 244 /**
 245   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 246   ASCII format string and a BASE_LIST argument list.
 247
 248   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 249   and BufferSize.
 250   The Unicode string is produced by parsing the format string specified by FormatString.
 251   Arguments are pulled from the variable argument list specified by Marker based on the
 252   contents of the format string.
 253   The number of Unicode characters in the produced output buffer is returned not including
 254   the Null-terminator.
 255
 256   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 257
 258   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 259   unmodified and 0 is returned.
 260   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 261   unmodified and 0 is returned.
 262   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
 263   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
 264   buffer is unmodified and 0 is returned.
 265   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 266   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 267   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 268
 269   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 270
 271   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 272                           Unicode string.
 273   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 274   @param  FormatString    A Null-terminated ASCII format string.
 275   @param  Marker          BASE_LIST marker for the variable argument list.
 276
 277   @return The number of Unicode characters in the produced output buffer not including the
 278           Null-terminator.
 279
 280 **/
 281 UINTN
 282 EFIAPI
 283 UnicodeBSPrintAsciiFormat (
 284   OUT CHAR16       *StartOfBuffer,
 285   IN  UINTN        BufferSize,
 286   IN  CONST CHAR8  *FormatString,
 287   IN  BASE_LIST    Marker
 288   )
 289 {
 290   ASSERT_UNICODE_BUFFER (StartOfBuffer);
 291   return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE, FormatString, gNullVaList, Marker);
 292 }
 293
 294 /**
 295   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 296   ASCII format string and  variable argument list.
 297
 298   This function is similar as snprintf_s defined in C11.
 299
 300   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 301   and BufferSize.
 302   The Unicode string is produced by parsing the format string specified by FormatString.
 303   Arguments are pulled from the variable argument list based on the contents of the
 304   format string.
 305   The number of Unicode characters in the produced output buffer is returned not including
 306   the Null-terminator.
 307
 308   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 309
 310   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 311   unmodified and 0 is returned.
 312   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 313   unmodified and 0 is returned.
 314   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
 315   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
 316   buffer is unmodified and 0 is returned.
 317   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 318   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 319   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 320
 321   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 322
 323   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 324                           Unicode string.
 325   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 326   @param  FormatString    A Null-terminated ASCII format string.
 327   @param  ...             Variable argument list whose contents are accessed based on the
 328                           format string specified by FormatString.
 329
 330   @return The number of Unicode characters in the produced output buffer not including the
 331           Null-terminator.
 332
 333 **/
 334 UINTN
 335 EFIAPI
 336 UnicodeSPrintAsciiFormat (
 337   OUT CHAR16       *StartOfBuffer,
 338   IN  UINTN        BufferSize,
 339   IN  CONST CHAR8  *FormatString,
 340   ...
 341   )
 342 {
 343   VA_LIST Marker;
 344   UINTN   NumberOfPrinted;
 345
 346   VA_START (Marker, FormatString);
 347   NumberOfPrinted = UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 348   VA_END (Marker);
 349   return NumberOfPrinted;
 350 }
 351
 352 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 353
 354 /**
 355   [ATTENTION] This function is deprecated for security reason.
 356
 357   Converts a decimal value to a Null-terminated Unicode string.
 358
 359   Converts the decimal number specified by Value to a Null-terminated Unicode
 360   string specified by Buffer containing at most Width characters. No padding of spaces
 361   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 362   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 363   If the conversion contains more than Width characters, then only the first
 364   Width characters are returned, and the total number of characters
 365   required to perform the conversion is returned.
 366   Additional conversion parameters are specified in Flags.
 367
 368   The Flags bit LEFT_JUSTIFY is always ignored.
 369   All conversions are left justified in Buffer.
 370   If Width is 0, PREFIX_ZERO is ignored in Flags.
 371   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 372   are inserted every 3rd digit starting from the right.
 373   If RADIX_HEX is set in Flags, then the output buffer will be
 374   formatted in hexadecimal format.
 375   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 376   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 377   then Buffer is padded with '0' characters so the combination of the optional '-'
 378   sign character, '0' characters, digit characters for Value, and the Null-terminator
 379   add up to Width characters.
 380   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 381   If Buffer is NULL, then ASSERT().
 382   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 383   If unsupported bits are set in Flags, then ASSERT().
 384   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 385   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 386
 387   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 388                   Unicode string.
 389   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 390   @param  Value   The 64-bit signed value to convert to a string.
 391   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 392                   the Null-terminator.
 393
 394   @return The number of Unicode characters in Buffer not including the Null-terminator.
 395
 396 **/
 397 UINTN
 398 EFIAPI
 399 UnicodeValueToString (
 400   IN OUT CHAR16  *Buffer,
 401   IN UINTN       Flags,
 402   IN INT64       Value,
 403   IN UINTN       Width
 404   )
 405 {
 406   ASSERT_UNICODE_BUFFER(Buffer);
 407   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
 408 }
 409
 410 #endif
 411
 412 /**
 413   Converts a decimal value to a Null-terminated Unicode string.
 414
 415   Converts the decimal number specified by Value to a Null-terminated Unicode
 416   string specified by Buffer containing at most Width characters. No padding of
 417   spaces is ever performed. If Width is 0 then a width of
 418   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 419   Width characters, then only the first Width characters are placed in Buffer.
 420   Additional conversion parameters are specified in Flags.
 421
 422   The Flags bit LEFT_JUSTIFY is always ignored.
 423   All conversions are left justified in Buffer.
 424   If Width is 0, PREFIX_ZERO is ignored in Flags.
 425   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 426   commas are inserted every 3rd digit starting from the right.
 427   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 428   hexadecimal format.
 429   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 430   Buffer is a '-'.
 431   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 432   Buffer is padded with '0' characters so the combination of the optional '-'
 433   sign character, '0' characters, digit characters for Value, and the
 434   Null-terminator add up to Width characters.
 435
 436   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 437   If an error would be returned, then the function will also ASSERT().
 438
 439   @param  Buffer      The pointer to the output buffer for the produced
 440                       Null-terminated Unicode string.
 441   @param  BufferSize  The size of Buffer in bytes, including the
 442                       Null-terminator.
 443   @param  Flags       The bitmask of flags that specify left justification,
 444                       zero pad, and commas.
 445   @param  Value       The 64-bit signed value to convert to a string.
 446   @param  Width       The maximum number of Unicode characters to place in
 447                       Buffer, not including the Null-terminator.
 448
 449   @retval RETURN_SUCCESS           The decimal value is converted.
 450   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 451                                    value.
 452   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 453                                    If PcdMaximumUnicodeStringLength is not
 454                                    zero, and BufferSize is greater than
 455                                    (PcdMaximumUnicodeStringLength *
 456                                    sizeof (CHAR16) + 1).
 457                                    If unsupported bits are set in Flags.
 458                                    If both COMMA_TYPE and RADIX_HEX are set in
 459                                    Flags.
 460                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 461
 462 **/
 463 RETURN_STATUS
 464 EFIAPI
 465 UnicodeValueToStringS (
 466   IN OUT CHAR16  *Buffer,
 467   IN UINTN       BufferSize,
 468   IN UINTN       Flags,
 469   IN INT64       Value,
 470   IN UINTN       Width
 471   )
 472 {
 473   ASSERT_UNICODE_BUFFER(Buffer);
 474   return BasePrintLibConvertValueToStringS ((CHAR8 *)Buffer, BufferSize, Flags, Value, Width, 2);
 475 }
 476
 477 /**
 478   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 479   ASCII format string and a VA_LIST argument list.
 480
 481   This function is similar as vsnprintf_s defined in C11.
 482
 483   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 484   and BufferSize.
 485   The ASCII string is produced by parsing the format string specified by FormatString.
 486   Arguments are pulled from the variable argument list specified by Marker based on
 487   the contents of the format string.
 488   The number of ASCII characters in the produced output buffer is returned not including
 489   the Null-terminator.
 490
 491   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 492   unmodified and 0 is returned.
 493   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 494   unmodified and 0 is returned.
 495   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 496   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 497   is unmodified and 0 is returned.
 498   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 499   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 500   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 501
 502   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 503
 504   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 505                           ASCII string.
 506   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 507   @param  FormatString    A Null-terminated ASCII format string.
 508   @param  Marker          VA_LIST marker for the variable argument list.
 509
 510   @return The number of ASCII characters in the produced output buffer not including the
 511           Null-terminator.
 512
 513 **/
 514 UINTN
 515 EFIAPI
 516 AsciiVSPrint (
 517   OUT CHAR8         *StartOfBuffer,
 518   IN  UINTN         BufferSize,
 519   IN  CONST CHAR8   *FormatString,
 520   IN  VA_LIST       Marker
 521   )
 522 {
 523   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, Marker, NULL);
 524 }
 525
 526 /**
 527   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 528   ASCII format string and a BASE_LIST argument list.
 529
 530   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 531   and BufferSize.
 532   The ASCII string is produced by parsing the format string specified by FormatString.
 533   Arguments are pulled from the variable argument list specified by Marker based on
 534   the contents of the format string.
 535   The number of ASCII characters in the produced output buffer is returned not including
 536   the Null-terminator.
 537
 538   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 539   unmodified and 0 is returned.
 540   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 541   unmodified and 0 is returned.
 542   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 543   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 544   is unmodified and 0 is returned.
 545   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 546   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 547   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 548
 549   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 550
 551   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 552                           ASCII string.
 553   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 554   @param  FormatString    A Null-terminated ASCII format string.
 555   @param  Marker          BASE_LIST marker for the variable argument list.
 556
 557   @return The number of ASCII characters in the produced output buffer not including the
 558           Null-terminator.
 559
 560 **/
 561 UINTN
 562 EFIAPI
 563 AsciiBSPrint (
 564   OUT CHAR8         *StartOfBuffer,
 565   IN  UINTN         BufferSize,
 566   IN  CONST CHAR8   *FormatString,
 567   IN  BASE_LIST     Marker
 568   )
 569 {
 570   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, gNullVaList, Marker);
 571 }
 572
 573 /**
 574   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 575   ASCII format string and  variable argument list.
 576
 577   This function is similar as snprintf_s defined in C11.
 578
 579   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 580   and BufferSize.
 581   The ASCII string is produced by parsing the format string specified by FormatString.
 582   Arguments are pulled from the variable argument list based on the contents of the
 583   format string.
 584   The number of ASCII characters in the produced output buffer is returned not including
 585   the Null-terminator.
 586
 587   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 588   unmodified and 0 is returned.
 589   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 590   unmodified and 0 is returned.
 591   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 592   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 593   is unmodified and 0 is returned.
 594   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 595   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 596   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 597
 598   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 599
 600   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 601                           ASCII string.
 602   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 603   @param  FormatString    A Null-terminated ASCII format string.
 604   @param  ...             Variable argument list whose contents are accessed based on the
 605                           format string specified by FormatString.
 606
 607   @return The number of ASCII characters in the produced output buffer not including the
 608           Null-terminator.
 609
 610 **/
 611 UINTN
 612 EFIAPI
 613 AsciiSPrint (
 614   OUT CHAR8        *StartOfBuffer,
 615   IN  UINTN        BufferSize,
 616   IN  CONST CHAR8  *FormatString,
 617   ...
 618   )
 619 {
 620   VA_LIST Marker;
 621   UINTN   NumberOfPrinted;
 622
 623   VA_START (Marker, FormatString);
 624   NumberOfPrinted = AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 625   VA_END (Marker);
 626   return NumberOfPrinted;
 627 }
 628
 629 /**
 630   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 631   Unicode format string and a VA_LIST argument list.
 632
 633   This function is similar as vsnprintf_s defined in C11.
 634
 635   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 636   and BufferSize.
 637   The ASCII string is produced by parsing the format string specified by FormatString.
 638   Arguments are pulled from the variable argument list specified by Marker based on
 639   the contents of the format string.
 640   The number of ASCII characters in the produced output buffer is returned not including
 641   the Null-terminator.
 642
 643   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 644
 645   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 646   unmodified and 0 is returned.
 647   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 648   unmodified and 0 is returned.
 649   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 650   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 651   is unmodified and 0 is returned.
 652   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 653   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 654   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 655
 656   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 657
 658   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 659                           ASCII string.
 660   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 661   @param  FormatString    A Null-terminated Unicode format string.
 662   @param  Marker          VA_LIST marker for the variable argument list.
 663
 664   @return The number of ASCII characters in the produced output buffer not including the
 665           Null-terminator.
 666
 667 **/
 668 UINTN
 669 EFIAPI
 670 AsciiVSPrintUnicodeFormat (
 671   OUT CHAR8         *StartOfBuffer,
 672   IN  UINTN         BufferSize,
 673   IN  CONST CHAR16  *FormatString,
 674   IN  VA_LIST       Marker
 675   )
 676 {
 677   ASSERT_UNICODE_BUFFER (FormatString);
 678   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);
 679 }
 680
 681 /**
 682   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 683   Unicode format string and a BASE_LIST argument list.
 684
 685   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 686   and BufferSize.
 687   The ASCII string is produced by parsing the format string specified by FormatString.
 688   Arguments are pulled from the variable argument list specified by Marker based on
 689   the contents of the format string.
 690   The number of ASCII characters in the produced output buffer is returned not including
 691   the Null-terminator.
 692
 693   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 694
 695   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 696   unmodified and 0 is returned.
 697   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 698   unmodified and 0 is returned.
 699   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 700   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 701   is unmodified and 0 is returned.
 702   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 703   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 704   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 705
 706   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 707
 708   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 709                           ASCII string.
 710   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 711   @param  FormatString    A Null-terminated Unicode format string.
 712   @param  Marker          BASE_LIST marker for the variable argument list.
 713
 714   @return The number of ASCII characters in the produced output buffer not including the
 715           Null-terminator.
 716
 717 **/
 718 UINTN
 719 EFIAPI
 720 AsciiBSPrintUnicodeFormat (
 721   OUT CHAR8         *StartOfBuffer,
 722   IN  UINTN         BufferSize,
 723   IN  CONST CHAR16  *FormatString,
 724   IN  BASE_LIST     Marker
 725   )
 726 {
 727   ASSERT_UNICODE_BUFFER (FormatString);
 728   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, gNullVaList, Marker);
 729 }
 730
 731 /**
 732   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 733   Unicode format string and  variable argument list.
 734
 735   This function is similar as snprintf_s defined in C11.
 736
 737   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 738   and BufferSize.
 739   The ASCII string is produced by parsing the format string specified by FormatString.
 740   Arguments are pulled from the variable argument list based on the contents of the
 741   format string.
 742   The number of ASCII characters in the produced output buffer is returned not including
 743   the Null-terminator.
 744
 745   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 746
 747   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 748   unmodified and 0 is returned.
 749   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 750   unmodified and 0 is returned.
 751   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 752   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 753   is unmodified and 0 is returned.
 754   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 755   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 756   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 757
 758   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 759
 760   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 761                           ASCII string.
 762   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 763   @param  FormatString    A Null-terminated Unicode format string.
 764   @param  ...             Variable argument list whose contents are accessed based on the
 765                           format string specified by FormatString.
 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 AsciiSPrintUnicodeFormat (
 774   OUT CHAR8         *StartOfBuffer,
 775   IN  UINTN         BufferSize,
 776   IN  CONST CHAR16  *FormatString,
 777   ...
 778   )
 779 {
 780   VA_LIST Marker;
 781   UINTN   NumberOfPrinted;
 782
 783   VA_START (Marker, FormatString);
 784   NumberOfPrinted = AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 785   VA_END (Marker);
 786   return NumberOfPrinted;
 787 }
 788
 789
 790 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 791
 792 /**
 793   [ATTENTION] This function is deprecated for security reason.
 794
 795   Converts a decimal value to a Null-terminated ASCII string.
 796
 797   Converts the decimal number specified by Value to a Null-terminated ASCII string
 798   specified by Buffer containing at most Width characters. No padding of spaces
 799   is ever performed.
 800   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 801   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 802   If the conversion contains more than Width characters, then only the first Width
 803   characters are returned, and the total number of characters required to perform
 804   the conversion is returned.
 805   Additional conversion parameters are specified in Flags.
 806   The Flags bit LEFT_JUSTIFY is always ignored.
 807   All conversions are left justified in Buffer.
 808   If Width is 0, PREFIX_ZERO is ignored in Flags.
 809   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 810   are inserted every 3rd digit starting from the right.
 811   If RADIX_HEX is set in Flags, then the output buffer will be
 812   formatted in hexadecimal format.
 813   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 814   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 815   then Buffer is padded with '0' characters so the combination of the optional '-'
 816   sign character, '0' characters, digit characters for Value, and the Null-terminator
 817   add up to Width characters.
 818
 819   If Buffer is NULL, then ASSERT().
 820   If unsupported bits are set in Flags, then ASSERT().
 821   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 822   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 823
 824   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 825                   ASCII string.
 826   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 827   @param  Value   The 64-bit signed value to convert to a string.
 828   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 829                   the Null-terminator.
 830
 831   @return The number of ASCII characters in Buffer not including the Null-terminator.
 832
 833 **/
 834 UINTN
 835 EFIAPI
 836 AsciiValueToString (
 837   OUT CHAR8      *Buffer,
 838   IN  UINTN      Flags,
 839   IN  INT64      Value,
 840   IN  UINTN      Width
 841   )
 842 {
 843   return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);
 844 }
 845
 846 #endif
 847
 848 /**
 849   Converts a decimal value to a Null-terminated Ascii string.
 850
 851   Converts the decimal number specified by Value to a Null-terminated Ascii
 852   string specified by Buffer containing at most Width characters. No padding of
 853   spaces is ever performed. If Width is 0 then a width of
 854   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 855   Width characters, then only the first Width characters are placed in Buffer.
 856   Additional conversion parameters are specified in Flags.
 857
 858   The Flags bit LEFT_JUSTIFY is always ignored.
 859   All conversions are left justified in Buffer.
 860   If Width is 0, PREFIX_ZERO is ignored in Flags.
 861   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 862   commas are inserted every 3rd digit starting from the right.
 863   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 864   hexadecimal format.
 865   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 866   Buffer is a '-'.
 867   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 868   Buffer is padded with '0' characters so the combination of the optional '-'
 869   sign character, '0' characters, digit characters for Value, and the
 870   Null-terminator add up to Width characters.
 871
 872   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 873   If an error would be returned, then the function will also ASSERT().
 874
 875   @param  Buffer      The pointer to the output buffer for the produced
 876                       Null-terminated Ascii string.
 877   @param  BufferSize  The size of Buffer in bytes, including the
 878                       Null-terminator.
 879   @param  Flags       The bitmask of flags that specify left justification,
 880                       zero pad, and commas.
 881   @param  Value       The 64-bit signed value to convert to a string.
 882   @param  Width       The maximum number of Ascii characters to place in
 883                       Buffer, not including the Null-terminator.
 884
 885   @retval RETURN_SUCCESS           The decimal value is converted.
 886   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 887                                    value.
 888   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 889                                    If PcdMaximumAsciiStringLength is not
 890                                    zero, and BufferSize is greater than
 891                                    PcdMaximumAsciiStringLength.
 892                                    If unsupported bits are set in Flags.
 893                                    If both COMMA_TYPE and RADIX_HEX are set in
 894                                    Flags.
 895                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 896
 897 **/
 898 RETURN_STATUS
 899 EFIAPI
 900 AsciiValueToStringS (
 901   IN OUT CHAR8   *Buffer,
 902   IN UINTN       BufferSize,
 903   IN UINTN       Flags,
 904   IN INT64       Value,
 905   IN UINTN       Width
 906   )
 907 {
 908   return BasePrintLibConvertValueToStringS (Buffer, BufferSize, Flags, Value, Width, 1);
 909 }
 910
 911 /**
 912   Returns the number of characters that would be produced by if the formatted
 913   output were produced not including the Null-terminator.
 914
 915   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 916
 917   If FormatString is NULL, then ASSERT() and 0 is returned.
 918   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
 919   than PcdMaximumUnicodeStringLength Unicode characters not including the
 920   Null-terminator, then ASSERT() and 0 is returned.
 921
 922   @param[in]  FormatString    A Null-terminated Unicode format string.
 923   @param[in]  Marker          VA_LIST marker for the variable argument list.
 924
 925   @return The number of characters that would be produced, not including the
 926           Null-terminator.
 927 **/
 928 UINTN
 929 EFIAPI
 930 SPrintLength (
 931   IN  CONST CHAR16   *FormatString,
 932   IN  VA_LIST       Marker
 933   )
 934 {
 935   ASSERT_UNICODE_BUFFER (FormatString);
 936   return BasePrintLibSPrintMarker (NULL, 0, FORMAT_UNICODE | OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 937 }
 938
 939 /**
 940   Returns the number of characters that would be produced by if the formatted
 941   output were produced not including the Null-terminator.
 942
 943   If FormatString is NULL, then ASSERT() and 0 is returned.
 944   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
 945   than PcdMaximumAsciiStringLength Ascii characters not including the
 946   Null-terminator, then ASSERT() and 0 is returned.
 947
 948   @param[in]  FormatString    A Null-terminated ASCII format string.
 949   @param[in]  Marker          VA_LIST marker for the variable argument list.
 950
 951   @return The number of characters that would be produced, not including the
 952           Null-terminator.
 953 **/
 954 UINTN
 955 EFIAPI
 956 SPrintLengthAsciiFormat (
 957   IN  CONST CHAR8   *FormatString,
 958   IN  VA_LIST       Marker
 959   )
 960 {
 961   return BasePrintLibSPrintMarker (NULL, 0, OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 962 }