MdePkg/Library/BasePrintLib/PrintLib.c

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