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 /**
 353   Converts a decimal value to a Null-terminated Unicode string.
 354
 355   Converts the decimal number specified by Value to a Null-terminated Unicode
 356   string specified by Buffer containing at most Width characters. No padding of spaces
 357   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 358   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 359   If the conversion contains more than Width characters, then only the first
 360   Width characters are returned, and the total number of characters
 361   required to perform the conversion is returned.
 362   Additional conversion parameters are specified in Flags.
 363
 364   The Flags bit LEFT_JUSTIFY is always ignored.
 365   All conversions are left justified in Buffer.
 366   If Width is 0, PREFIX_ZERO is ignored in Flags.
 367   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 368   are inserted every 3rd digit starting from the right.
 369   If RADIX_HEX is set in Flags, then the output buffer will be
 370   formatted in hexadecimal format.
 371   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 372   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 373   then Buffer is padded with '0' characters so the combination of the optional '-'
 374   sign character, '0' characters, digit characters for Value, and the Null-terminator
 375   add up to Width characters.
 376   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 377   If Buffer is NULL, then ASSERT().
 378   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 379   If unsupported bits are set in Flags, then ASSERT().
 380   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 381   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 382
 383   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 384                   Unicode string.
 385   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 386   @param  Value   The 64-bit signed value to convert to a string.
 387   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 388                   the Null-terminator.
 389
 390   @return The number of Unicode characters in Buffer not including the Null-terminator.
 391
 392 **/
 393 UINTN
 394 EFIAPI
 395 UnicodeValueToString (
 396   IN OUT CHAR16  *Buffer,
 397   IN UINTN       Flags,
 398   IN INT64       Value,
 399   IN UINTN       Width
 400   )
 401 {
 402   ASSERT_UNICODE_BUFFER(Buffer);
 403   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
 404 }
 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 /**
 785   Converts a decimal value to a Null-terminated ASCII string.
 786
 787   Converts the decimal number specified by Value to a Null-terminated ASCII string
 788   specified by Buffer containing at most Width characters. No padding of spaces
 789   is ever performed.
 790   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 791   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 792   If the conversion contains more than Width characters, then only the first Width
 793   characters are returned, and the total number of characters required to perform
 794   the conversion is returned.
 795   Additional conversion parameters are specified in Flags.
 796   The Flags bit LEFT_JUSTIFY is always ignored.
 797   All conversions are left justified in Buffer.
 798   If Width is 0, PREFIX_ZERO is ignored in Flags.
 799   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 800   are inserted every 3rd digit starting from the right.
 801   If RADIX_HEX is set in Flags, then the output buffer will be
 802   formatted in hexadecimal format.
 803   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
 804   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 805   then Buffer is padded with '0' characters so the combination of the optional '-'
 806   sign character, '0' characters, digit characters for Value, and the Null-terminator
 807   add up to Width characters.
 808
 809   If Buffer is NULL, then ASSERT().
 810   If unsupported bits are set in Flags, then ASSERT().
 811   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
 812   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 813
 814   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
 815                   ASCII string.
 816   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 817   @param  Value   The 64-bit signed value to convert to a string.
 818   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 819                   the Null-terminator.
 820
 821   @return The number of ASCII characters in Buffer not including the Null-terminator.
 822
 823 **/
 824 UINTN
 825 EFIAPI
 826 AsciiValueToString (
 827   OUT CHAR8      *Buffer,
 828   IN  UINTN      Flags,
 829   IN  INT64      Value,
 830   IN  UINTN      Width
 831   )
 832 {
 833   return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);
 834 }
 835
 836 /**
 837   Converts a decimal value to a Null-terminated Ascii string.
 838
 839   Converts the decimal number specified by Value to a Null-terminated Ascii
 840   string specified by Buffer containing at most Width characters. No padding of
 841   spaces is ever performed. If Width is 0 then a width of
 842   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 843   Width characters, then only the first Width characters are placed in Buffer.
 844   Additional conversion parameters are specified in Flags.
 845
 846   The Flags bit LEFT_JUSTIFY is always ignored.
 847   All conversions are left justified in Buffer.
 848   If Width is 0, PREFIX_ZERO is ignored in Flags.
 849   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 850   commas are inserted every 3rd digit starting from the right.
 851   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 852   hexadecimal format.
 853   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 854   Buffer is a '-'.
 855   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 856   Buffer is padded with '0' characters so the combination of the optional '-'
 857   sign character, '0' characters, digit characters for Value, and the
 858   Null-terminator add up to Width characters.
 859
 860   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 861   If an error would be returned, then the function will also ASSERT().
 862
 863   @param  Buffer      The pointer to the output buffer for the produced
 864                       Null-terminated Ascii string.
 865   @param  BufferSize  The size of Buffer in bytes, including the
 866                       Null-terminator.
 867   @param  Flags       The bitmask of flags that specify left justification,
 868                       zero pad, and commas.
 869   @param  Value       The 64-bit signed value to convert to a string.
 870   @param  Width       The maximum number of Ascii characters to place in
 871                       Buffer, not including the Null-terminator.
 872
 873   @retval RETURN_SUCCESS           The decimal value is converted.
 874   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 875                                    value.
 876   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 877                                    If PcdMaximumAsciiStringLength is not
 878                                    zero, and BufferSize is greater than
 879                                    PcdMaximumAsciiStringLength.
 880                                    If unsupported bits are set in Flags.
 881                                    If both COMMA_TYPE and RADIX_HEX are set in
 882                                    Flags.
 883                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 884
 885 **/
 886 RETURN_STATUS
 887 EFIAPI
 888 AsciiValueToStringS (
 889   IN OUT CHAR8   *Buffer,
 890   IN UINTN       BufferSize,
 891   IN UINTN       Flags,
 892   IN INT64       Value,
 893   IN UINTN       Width
 894   )
 895 {
 896   return BasePrintLibConvertValueToStringS (Buffer, BufferSize, Flags, Value, Width, 1);
 897 }
 898
 899 /**
 900   Returns the number of characters that would be produced by if the formatted
 901   output were produced not including the Null-terminator.
 902
 903   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 904
 905   If FormatString is NULL, then ASSERT() and 0 is returned.
 906   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
 907   than PcdMaximumUnicodeStringLength Unicode characters not including the
 908   Null-terminator, then ASSERT() and 0 is returned.
 909
 910   @param[in]  FormatString    A Null-terminated Unicode format string.
 911   @param[in]  Marker          VA_LIST marker for the variable argument list.
 912
 913   @return The number of characters that would be produced, not including the
 914           Null-terminator.
 915 **/
 916 UINTN
 917 EFIAPI
 918 SPrintLength (
 919   IN  CONST CHAR16   *FormatString,
 920   IN  VA_LIST       Marker
 921   )
 922 {
 923   ASSERT_UNICODE_BUFFER (FormatString);
 924   return BasePrintLibSPrintMarker (NULL, 0, FORMAT_UNICODE | OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 925 }
 926
 927 /**
 928   Returns the number of characters that would be produced by if the formatted
 929   output were produced not including the Null-terminator.
 930
 931   If FormatString is NULL, then ASSERT() and 0 is returned.
 932   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
 933   than PcdMaximumAsciiStringLength Ascii characters not including the
 934   Null-terminator, then ASSERT() and 0 is returned.
 935
 936   @param[in]  FormatString    A Null-terminated ASCII format string.
 937   @param[in]  Marker          VA_LIST marker for the variable argument list.
 938
 939   @return The number of characters that would be produced, not including the
 940           Null-terminator.
 941 **/
 942 UINTN
 943 EFIAPI
 944 SPrintLengthAsciiFormat (
 945   IN  CONST CHAR8   *FormatString,
 946   IN  VA_LIST       Marker
 947   )
 948 {
 949   return BasePrintLibSPrintMarker (NULL, 0, OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 950 }