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 /**
 347   Converts a decimal value to a Null-terminated Unicode string.
 348
 349   Converts the decimal number specified by Value to a Null-terminated Unicode
 350   string specified by Buffer containing at most Width characters. No padding of
 351   spaces is ever performed. If Width is 0 then a width of
 352   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 353   Width characters, then only the first Width characters are placed in Buffer.
 354   Additional conversion parameters are specified in Flags.
 355
 356   The Flags bit LEFT_JUSTIFY is always ignored.
 357   All conversions are left justified in Buffer.
 358   If Width is 0, PREFIX_ZERO is ignored in Flags.
 359   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 360   commas are inserted every 3rd digit starting from the right.
 361   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 362   hexadecimal format.
 363   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 364   Buffer is a '-'.
 365   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 366   Buffer is padded with '0' characters so the combination of the optional '-'
 367   sign character, '0' characters, digit characters for Value, and the
 368   Null-terminator add up to Width characters.
 369
 370   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 371   If an error would be returned, then the function will also ASSERT().
 372
 373   @param  Buffer      The pointer to the output buffer for the produced
 374                       Null-terminated Unicode string.
 375   @param  BufferSize  The size of Buffer in bytes, including the
 376                       Null-terminator.
 377   @param  Flags       The bitmask of flags that specify left justification,
 378                       zero pad, and commas.
 379   @param  Value       The 64-bit signed value to convert to a string.
 380   @param  Width       The maximum number of Unicode characters to place in
 381                       Buffer, not including the Null-terminator.
 382
 383   @retval RETURN_SUCCESS           The decimal value is converted.
 384   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 385                                    value.
 386   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 387                                    If PcdMaximumUnicodeStringLength is not
 388                                    zero, and BufferSize is greater than
 389                                    (PcdMaximumUnicodeStringLength *
 390                                    sizeof (CHAR16) + 1).
 391                                    If unsupported bits are set in Flags.
 392                                    If both COMMA_TYPE and RADIX_HEX are set in
 393                                    Flags.
 394                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 395
 396 **/
 397 RETURN_STATUS
 398 EFIAPI
 399 UnicodeValueToStringS (
 400   IN OUT CHAR16  *Buffer,
 401   IN UINTN       BufferSize,
 402   IN UINTN       Flags,
 403   IN INT64       Value,
 404   IN UINTN       Width
 405   )
 406 {
 407   ASSERT_UNICODE_BUFFER (Buffer);
 408   return BasePrintLibConvertValueToStringS ((CHAR8 *)Buffer, BufferSize, Flags, Value, Width, 2);
 409 }
 410
 411 /**
 412   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 413   ASCII format string and a VA_LIST argument list.
 414
 415   This function is similar as vsnprintf_s defined in C11.
 416
 417   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 418   and BufferSize.
 419   The ASCII string is produced by parsing the format string specified by FormatString.
 420   Arguments are pulled from the variable argument list specified by Marker based on
 421   the contents of the format string.
 422   The number of ASCII characters in the produced output buffer is returned not including
 423   the Null-terminator.
 424
 425   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 426   unmodified and 0 is returned.
 427   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 428   unmodified and 0 is returned.
 429   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 430   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 431   is unmodified and 0 is returned.
 432   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 433   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 434   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 435
 436   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 437
 438   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 439                           ASCII string.
 440   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 441   @param  FormatString    A Null-terminated ASCII format string.
 442   @param  Marker          VA_LIST marker for the variable argument list.
 443
 444   @return The number of ASCII characters in the produced output buffer not including the
 445           Null-terminator.
 446
 447 **/
 448 UINTN
 449 EFIAPI
 450 AsciiVSPrint (
 451   OUT CHAR8        *StartOfBuffer,
 452   IN  UINTN        BufferSize,
 453   IN  CONST CHAR8  *FormatString,
 454   IN  VA_LIST      Marker
 455   )
 456 {
 457   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, Marker, NULL);
 458 }
 459
 460 /**
 461   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 462   ASCII format string and a BASE_LIST argument list.
 463
 464   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 465   and BufferSize.
 466   The ASCII string is produced by parsing the format string specified by FormatString.
 467   Arguments are pulled from the variable argument list specified by Marker based on
 468   the contents of the format string.
 469   The number of ASCII characters in the produced output buffer is returned not including
 470   the Null-terminator.
 471
 472   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 473   unmodified and 0 is returned.
 474   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 475   unmodified and 0 is returned.
 476   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 477   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 478   is unmodified and 0 is returned.
 479   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 480   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 481   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 482
 483   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 484
 485   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 486                           ASCII string.
 487   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 488   @param  FormatString    A Null-terminated ASCII format string.
 489   @param  Marker          BASE_LIST marker for the variable argument list.
 490
 491   @return The number of ASCII characters in the produced output buffer not including the
 492           Null-terminator.
 493
 494 **/
 495 UINTN
 496 EFIAPI
 497 AsciiBSPrint (
 498   OUT CHAR8        *StartOfBuffer,
 499   IN  UINTN        BufferSize,
 500   IN  CONST CHAR8  *FormatString,
 501   IN  BASE_LIST    Marker
 502   )
 503 {
 504   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, gNullVaList, Marker);
 505 }
 506
 507 /**
 508   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 509   ASCII format string and  variable argument list.
 510
 511   This function is similar as snprintf_s defined in C11.
 512
 513   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 514   and BufferSize.
 515   The ASCII string is produced by parsing the format string specified by FormatString.
 516   Arguments are pulled from the variable argument list based on the contents of the
 517   format string.
 518   The number of ASCII characters in the produced output buffer is returned not including
 519   the Null-terminator.
 520
 521   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 522   unmodified and 0 is returned.
 523   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 524   unmodified and 0 is returned.
 525   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 526   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 527   is unmodified and 0 is returned.
 528   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 529   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
 530   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 531
 532   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 533
 534   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 535                           ASCII string.
 536   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 537   @param  FormatString    A Null-terminated ASCII format string.
 538   @param  ...             Variable argument list whose contents are accessed based on the
 539                           format string specified by FormatString.
 540
 541   @return The number of ASCII characters in the produced output buffer not including the
 542           Null-terminator.
 543
 544 **/
 545 UINTN
 546 EFIAPI
 547 AsciiSPrint (
 548   OUT CHAR8        *StartOfBuffer,
 549   IN  UINTN        BufferSize,
 550   IN  CONST CHAR8  *FormatString,
 551   ...
 552   )
 553 {
 554   VA_LIST  Marker;
 555   UINTN    NumberOfPrinted;
 556
 557   VA_START (Marker, FormatString);
 558   NumberOfPrinted = AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 559   VA_END (Marker);
 560   return NumberOfPrinted;
 561 }
 562
 563 /**
 564   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 565   Unicode format string and a VA_LIST argument list.
 566
 567   This function is similar as vsnprintf_s defined in C11.
 568
 569   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 570   and BufferSize.
 571   The ASCII string is produced by parsing the format string specified by FormatString.
 572   Arguments are pulled from the variable argument list specified by Marker based on
 573   the contents of the format string.
 574   The number of ASCII characters in the produced output buffer is returned not including
 575   the Null-terminator.
 576
 577   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 578
 579   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 580   unmodified and 0 is returned.
 581   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 582   unmodified and 0 is returned.
 583   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 584   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 585   is unmodified and 0 is returned.
 586   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 587   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 588   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 589
 590   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 591
 592   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 593                           ASCII string.
 594   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 595   @param  FormatString    A Null-terminated Unicode format string.
 596   @param  Marker          VA_LIST marker for the variable argument list.
 597
 598   @return The number of ASCII characters in the produced output buffer not including the
 599           Null-terminator.
 600
 601 **/
 602 UINTN
 603 EFIAPI
 604 AsciiVSPrintUnicodeFormat (
 605   OUT CHAR8         *StartOfBuffer,
 606   IN  UINTN         BufferSize,
 607   IN  CONST CHAR16  *FormatString,
 608   IN  VA_LIST       Marker
 609   )
 610 {
 611   ASSERT_UNICODE_BUFFER (FormatString);
 612   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);
 613 }
 614
 615 /**
 616   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 617   Unicode format string and a BASE_LIST argument list.
 618
 619   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 620   and BufferSize.
 621   The ASCII string is produced by parsing the format string specified by FormatString.
 622   Arguments are pulled from the variable argument list specified by Marker based on
 623   the contents of the format string.
 624   The number of ASCII characters in the produced output buffer is returned not including
 625   the Null-terminator.
 626
 627   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 628
 629   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 630   unmodified and 0 is returned.
 631   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 632   unmodified and 0 is returned.
 633   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 634   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 635   is unmodified and 0 is returned.
 636   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 637   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 638   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 639
 640   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 641
 642   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 643                           ASCII string.
 644   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 645   @param  FormatString    A Null-terminated Unicode format string.
 646   @param  Marker          BASE_LIST marker for the variable argument list.
 647
 648   @return The number of ASCII characters in the produced output buffer not including the
 649           Null-terminator.
 650
 651 **/
 652 UINTN
 653 EFIAPI
 654 AsciiBSPrintUnicodeFormat (
 655   OUT CHAR8         *StartOfBuffer,
 656   IN  UINTN         BufferSize,
 657   IN  CONST CHAR16  *FormatString,
 658   IN  BASE_LIST     Marker
 659   )
 660 {
 661   ASSERT_UNICODE_BUFFER (FormatString);
 662   return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, gNullVaList, Marker);
 663 }
 664
 665 /**
 666   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 667   Unicode format string and  variable argument list.
 668
 669   This function is similar as snprintf_s defined in C11.
 670
 671   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 672   and BufferSize.
 673   The ASCII string is produced by parsing the format string specified by FormatString.
 674   Arguments are pulled from the variable argument list based on the contents of the
 675   format string.
 676   The number of ASCII characters in the produced output buffer is returned not including
 677   the Null-terminator.
 678
 679   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 680
 681   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
 682   unmodified and 0 is returned.
 683   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
 684   unmodified and 0 is returned.
 685   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
 686   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
 687   is unmodified and 0 is returned.
 688   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 689   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 690   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
 691
 692   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 693
 694   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 695                           ASCII string.
 696   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 697   @param  FormatString    A Null-terminated Unicode format string.
 698   @param  ...             Variable argument list whose contents are accessed based on the
 699                           format string specified by FormatString.
 700
 701   @return The number of ASCII characters in the produced output buffer not including the
 702           Null-terminator.
 703
 704 **/
 705 UINTN
 706 EFIAPI
 707 AsciiSPrintUnicodeFormat (
 708   OUT CHAR8         *StartOfBuffer,
 709   IN  UINTN         BufferSize,
 710   IN  CONST CHAR16  *FormatString,
 711   ...
 712   )
 713 {
 714   VA_LIST  Marker;
 715   UINTN    NumberOfPrinted;
 716
 717   VA_START (Marker, FormatString);
 718   NumberOfPrinted = AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 719   VA_END (Marker);
 720   return NumberOfPrinted;
 721 }
 722
 723 /**
 724   Converts a decimal value to a Null-terminated Ascii string.
 725
 726   Converts the decimal number specified by Value to a Null-terminated Ascii
 727   string specified by Buffer containing at most Width characters. No padding of
 728   spaces is ever performed. If Width is 0 then a width of
 729   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
 730   Width characters, then only the first Width characters are placed in Buffer.
 731   Additional conversion parameters are specified in Flags.
 732
 733   The Flags bit LEFT_JUSTIFY is always ignored.
 734   All conversions are left justified in Buffer.
 735   If Width is 0, PREFIX_ZERO is ignored in Flags.
 736   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 737   commas are inserted every 3rd digit starting from the right.
 738   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
 739   hexadecimal format.
 740   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
 741   Buffer is a '-'.
 742   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
 743   Buffer is padded with '0' characters so the combination of the optional '-'
 744   sign character, '0' characters, digit characters for Value, and the
 745   Null-terminator add up to Width characters.
 746
 747   If an error would be returned, then the function will ASSERT().
 748
 749   @param  Buffer      The pointer to the output buffer for the produced
 750                       Null-terminated Ascii string.
 751   @param  BufferSize  The size of Buffer in bytes, including the
 752                       Null-terminator.
 753   @param  Flags       The bitmask of flags that specify left justification,
 754                       zero pad, and commas.
 755   @param  Value       The 64-bit signed value to convert to a string.
 756   @param  Width       The maximum number of Ascii characters to place in
 757                       Buffer, not including the Null-terminator.
 758
 759   @retval RETURN_SUCCESS           The decimal value is converted.
 760   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 761                                    value.
 762   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 763                                    If PcdMaximumAsciiStringLength is not
 764                                    zero, and BufferSize is greater than
 765                                    PcdMaximumAsciiStringLength.
 766                                    If unsupported bits are set in Flags.
 767                                    If both COMMA_TYPE and RADIX_HEX are set in
 768                                    Flags.
 769                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 770
 771 **/
 772 RETURN_STATUS
 773 EFIAPI
 774 AsciiValueToStringS (
 775   IN OUT CHAR8  *Buffer,
 776   IN UINTN      BufferSize,
 777   IN UINTN      Flags,
 778   IN INT64      Value,
 779   IN UINTN      Width
 780   )
 781 {
 782   return BasePrintLibConvertValueToStringS (Buffer, BufferSize, Flags, Value, Width, 1);
 783 }
 784
 785 /**
 786   Returns the number of characters that would be produced by if the formatted
 787   output were produced not including the Null-terminator.
 788
 789   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
 790
 791   If FormatString is NULL, then ASSERT() and 0 is returned.
 792   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
 793   than PcdMaximumUnicodeStringLength Unicode characters not including the
 794   Null-terminator, then ASSERT() and 0 is returned.
 795
 796   @param[in]  FormatString    A Null-terminated Unicode format string.
 797   @param[in]  Marker          VA_LIST marker for the variable argument list.
 798
 799   @return The number of characters that would be produced, not including the
 800           Null-terminator.
 801 **/
 802 UINTN
 803 EFIAPI
 804 SPrintLength (
 805   IN  CONST CHAR16  *FormatString,
 806   IN  VA_LIST       Marker
 807   )
 808 {
 809   ASSERT_UNICODE_BUFFER (FormatString);
 810   return BasePrintLibSPrintMarker (NULL, 0, FORMAT_UNICODE | OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 811 }
 812
 813 /**
 814   Returns the number of characters that would be produced by if the formatted
 815   output were produced not including the Null-terminator.
 816
 817   If FormatString is NULL, then ASSERT() and 0 is returned.
 818   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
 819   than PcdMaximumAsciiStringLength Ascii characters not including the
 820   Null-terminator, then ASSERT() and 0 is returned.
 821
 822   @param[in]  FormatString    A Null-terminated ASCII format string.
 823   @param[in]  Marker          VA_LIST marker for the variable argument list.
 824
 825   @return The number of characters that would be produced, not including the
 826           Null-terminator.
 827 **/
 828 UINTN
 829 EFIAPI
 830 SPrintLengthAsciiFormat (
 831   IN  CONST CHAR8  *FormatString,
 832   IN  VA_LIST      Marker
 833   )
 834 {
 835   return BasePrintLibSPrintMarker (NULL, 0, OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
 836 }