1/** @file
2  Provides services to print a formatted string to a buffer. All combinations of
3  Unicode and ASCII strings are supported.
4
5Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
6This program and the accompanying materials are licensed and made available under
7the terms and conditions of the BSD License that accompanies this distribution.
8The full text of the license may be found at
9http://opensource.org/licenses/bsd-license.php.
10
11THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14  The Print Library functions provide a simple means to produce formatted output
15  strings.  Many of the output functions use a format string to describe how to
16  format the output of variable arguments.  The format string consists of normal
17  text and argument descriptors.  There are no restrictions for how the normal
18  text and argument descriptors can be mixed.  The following end of line(EOL)
19  translations must be performed on the contents of the format string:
20
21     - '\\r' is translated to '\\r'
22     - '\\r\\n' is translated to '\\r\\n'
23     - '\\n' is translated to '\\r\\n'
24     - '\\n\\r' is translated to '\\r\\n'
25
26  This does not follow the ANSI C standard for sprint().  The format of argument
27  descriptors is described below.  The ANSI C standard for sprint() has been
28  followed for some of the format types, and has not been followed for others.
29  The exceptions are noted below.
30
31    %[flags][width][.precision]type
32
33  [flags]:
34    - -
35      - The field is left justified.  If not flag is not specified, then the
36        field is right justified.
37    - space
38      - Prefix a space character to a number.  Only valid for types X, x, and d.
39    - +
40      - Prefix a plus character to a number.  Only valid for types X, x, and d.
41        If both space and + are specified, then space is ignored.
42    - 0
43      - Pad with 0 characters to the left of a number.  Only valid for types
44        X, x, and d.
45    - ,
46      - Place a comma every 3rd digit of the number.  Only valid for type d.
47        If 0 is also specified, then 0 is ignored.
48    - L, l
49      - The number being printed is size UINT64.  Only valid for types X, x, and d.
50        If this flag is not specified, then the number being printed is size int.
51    - NOTE: All invalid flags are ignored.
52
53  [width]:
54
55    - *
56      - The width of the field is specified by a UINTN argument in the
57        argument list.
58    - number
59      - The number specified as a decimal value represents the width of
60        the field.
61    - NOTE: If [width] is not specified, then a field width of 0 is assumed.
62
63  [.precision]:
64
65    - *
66      - The precision of the field is specified by a UINTN argument in the
67        argument list.
68    - number
69      - The number specified as a decimal value represents the precision of
70        the field.
71    - NOTE: If [.precision] is not specified, then a precision of 0 is assumed.
72
73  type:
74
75    - %
76      - Print a %%.
77    - c
78      - The argument is a Unicode character.  ASCII characters can be printed
79        using this type too by making sure bits 8..15 of the argument are set to 0.
80    - x
81      - The argument is an unsigned hexadecimal number.  The characters used are 0..9 and
82        A..F.  If the flag 'L' is not specified, then the argument is assumed
83        to be size int.  This does not follow ANSI C.
84    - X
85      - The argument is an unsigned hexadecimal number and the number is padded with
86        zeros.  This is equivalent to a format string of "0x". If the flag
87        'L' is not specified, then the argument is assumed to be size int.
88        This does not follow ANSI C.
89    - d
90      - The argument is a signed decimal number.  If the flag 'L' is not specified,
91        then the argument is assumed to be size int.
92    - u
93      - The argument is a unsigned decimal number.  If the flag 'L' is not specified,
94        then the argument is assumed to be size int.
95    - p
96      - The argument is a pointer that is a (VOID *), and it is printed as an
97        unsigned hexadecimal number  The characters used are 0..9 and A..F.
98    - a
99      - The argument is a pointer to an ASCII string.
100        This does not follow ANSI C.
101    - S, s
102      - The argument is a pointer to a Unicode string.
103        This does not follow ANSI C.
104    - g
105      - The argument is a pointer to a GUID structure.  The GUID is printed
106        in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
107        This does not follow ANSI C.
108    - t
109      - The argument is a pointer to an EFI_TIME structure.  The time and
110        date are printed in the format "mm/dd/yyyy hh:mm" where mm is the
111        month zero padded, dd is the day zero padded, yyyy is the year zero
112        padded, hh is the hour zero padded, and mm is minutes zero padded.
113        This does not follow ANSI C.
114    - r
115      - The argument is a RETURN_STATUS value.  This value is converted to
116        a string following the table below.  This does not follow ANSI C.
117      - RETURN_SUCCESS
118        - "Success"
119      - RETURN_LOAD_ERROR
120        - "Load Error"
121      - RETURN_INVALID_PARAMETER
122        - "Invalid Parameter"
123      - RETURN_UNSUPPORTED
124        - "Unsupported"
125      - RETURN_BAD_BUFFER_SIZE
126        - "Bad Buffer Size"
127      - RETURN_BUFFER_TOO_SMALL
128        - "Buffer Too Small"
129      - RETURN_NOT_READY
130        - "Not Ready"
131      - RETURN_DEVICE_ERROR
132        - "Device Error"
133      - RETURN_WRITE_PROTECTED
134        - "Write Protected"
135      - RETURN_OUT_OF_RESOURCES
136        - "Out of Resources"
137      - RETURN_VOLUME_CORRUPTED
138        - "Volume Corrupt"
139      - RETURN_VOLUME_FULL
140        - "Volume Full"
141      - RETURN_NO_MEDIA
142        - "No Media"
143      - RETURN_MEDIA_CHANGED
144        - "Media changed"
145      - RETURN_NOT_FOUND
146        - "Not Found"
147      - RETURN_ACCESS_DENIED
148        - "Access Denied"
149      - RETURN_NO_RESPONSE
150        - "No Response"
151      - RETURN_NO_MAPPING
152        - "No mapping"
153      - RETURN_TIMEOUT
154        - "Time out"
155      - RETURN_NOT_STARTED
156        - "Not started"
157      - RETURN_ALREADY_STARTED
158        - "Already started"
159      - RETURN_ABORTED
160        - "Aborted"
161      - RETURN_ICMP_ERROR
162        - "ICMP Error"
163      - RETURN_TFTP_ERROR
164        - "TFTP Error"
165      - RETURN_PROTOCOL_ERROR
166        - "Protocol Error"
167      - RETURN_WARN_UNKNOWN_GLYPH
168        - "Warning Unknown Glyph"
169      - RETURN_WARN_DELETE_FAILURE
170        - "Warning Delete Failure"
171      - RETURN_WARN_WRITE_FAILURE
172        - "Warning Write Failure"
173      - RETURN_WARN_BUFFER_TOO_SMALL
174        - "Warning Buffer Too Small"
175
176**/
177
178#ifndef __PRINT_LIB_H__
179#define __PRINT_LIB_H__
180
181///
182/// Define the maximum number of characters that are required to
183/// encode with a NULL terminator a decimal, hexadecimal, GUID,
184/// or TIME value.
185///
186///  Maximum Length Decimal String     = 28
187///    "-9,223,372,036,854,775,808"
188///  Maximum Length Hexadecimal String = 17
189///    "FFFFFFFFFFFFFFFF"
190///  Maximum Length GUID               = 37
191///    "00000000-0000-0000-0000-000000000000"
192///  Maximum Length TIME               = 18
193///    "12/12/2006  12:12"
194///
195#define MAXIMUM_VALUE_CHARACTERS  38
196
197///
198/// Flags bitmask values use in UnicodeValueToString() and
199/// AsciiValueToString()
200///
201#define LEFT_JUSTIFY      0x01
202#define COMMA_TYPE        0x08
203#define PREFIX_ZERO       0x20
204#define RADIX_HEX         0x80
205
206/**
207  Produces a Null-terminated Unicode string in an output buffer based on
208  a Null-terminated Unicode format string and a VA_LIST argument list.
209
210  This function is similar as vsnprintf_s defined in C11.
211
212  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
213  and BufferSize.
214  The Unicode string is produced by parsing the format string specified by FormatString.
215  Arguments are pulled from the variable argument list specified by Marker based on the
216  contents of the format string.
217  The number of Unicode characters in the produced output buffer is returned not including
218  the Null-terminator.
219
220  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
221  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
222
223  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
224  unmodified and 0 is returned.
225  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
226  unmodified and 0 is returned.
227  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
228  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
229  buffer is unmodified and 0 is returned.
230  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
231  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
232  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
233
234  If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
235
236  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
237                          Unicode string.
238  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
239  @param  FormatString    A Null-terminated Unicode format string.
240  @param  Marker          VA_LIST marker for the variable argument list.
241
242  @return The number of Unicode characters in the produced output buffer not including the
243          Null-terminator.
244
245**/
246UINTN
247EFIAPI
248UnicodeVSPrint (
249  OUT CHAR16        *StartOfBuffer,
250  IN  UINTN         BufferSize,
251  IN  CONST CHAR16  *FormatString,
252  IN  VA_LIST       Marker
253  );
254
255/**
256  Produces a Null-terminated Unicode string in an output buffer based on
257  a Null-terminated Unicode format string and a BASE_LIST argument list.
258
259  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
260  and BufferSize.
261  The Unicode string is produced by parsing the format string specified by FormatString.
262  Arguments are pulled from the variable argument list specified by Marker based on the
263  contents of the format string.
264  The number of Unicode characters in the produced output buffer is returned not including
265  the Null-terminator.
266
267  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
268  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
269
270  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
271  unmodified and 0 is returned.
272  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
273  unmodified and 0 is returned.
274  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
275  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
276  buffer is unmodified and 0 is returned.
277  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
278  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
279  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
280
281  If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
282
283  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
284                          Unicode string.
285  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
286  @param  FormatString    A Null-terminated Unicode format string.
287  @param  Marker          BASE_LIST marker for the variable argument list.
288
289  @return The number of Unicode characters in the produced output buffer not including the
290          Null-terminator.
291
292**/
293UINTN
294EFIAPI
295UnicodeBSPrint (
296  OUT CHAR16        *StartOfBuffer,
297  IN  UINTN         BufferSize,
298  IN  CONST CHAR16  *FormatString,
299  IN  BASE_LIST     Marker
300  );
301
302/**
303  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
304  Unicode format string and variable argument list.
305
306  This function is similar as snprintf_s defined in C11.
307
308  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
309  and BufferSize.
310  The Unicode string is produced by parsing the format string specified by FormatString.
311  Arguments are pulled from the variable argument list based on the contents of the format string.
312  The number of Unicode characters in the produced output buffer is returned not including
313  the Null-terminator.
314
315  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
316  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
317
318  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
319  unmodified and 0 is returned.
320  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
321  unmodified and 0 is returned.
322  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
323  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
324  buffer is unmodified and 0 is returned.
325  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
326  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
327  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
328
329  If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
330
331  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
332                          Unicode string.
333  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
334  @param  FormatString    A Null-terminated Unicode format string.
335  @param  ...             Variable argument list whose contents are accessed based on the
336                          format string specified by FormatString.
337
338  @return The number of Unicode characters in the produced output buffer not including the
339          Null-terminator.
340
341**/
342UINTN
343EFIAPI
344UnicodeSPrint (
345  OUT CHAR16        *StartOfBuffer,
346  IN  UINTN         BufferSize,
347  IN  CONST CHAR16  *FormatString,
348  ...
349  );
350
351/**
352  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
353  ASCII format string and a VA_LIST argument list.
354
355  This function is similar as vsnprintf_s defined in C11.
356
357  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
358  and BufferSize.
359  The Unicode string is produced by parsing the format string specified by FormatString.
360  Arguments are pulled from the variable argument list specified by Marker based on the
361  contents of the format string.
362  The number of Unicode characters in the produced output buffer is returned not including
363  the Null-terminator.
364
365  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
366
367  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
368  unmodified and 0 is returned.
369  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
370  unmodified and 0 is returned.
371  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
372  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
373  buffer is unmodified and 0 is returned.
374  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
375  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
376  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
377
378  If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
379
380  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
381                          Unicode string.
382  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
383  @param  FormatString    A Null-terminated ASCII format string.
384  @param  Marker          VA_LIST marker for the variable argument list.
385
386  @return The number of Unicode characters in the produced output buffer not including the
387          Null-terminator.
388
389**/
390UINTN
391EFIAPI
392UnicodeVSPrintAsciiFormat (
393  OUT CHAR16       *StartOfBuffer,
394  IN  UINTN        BufferSize,
395  IN  CONST CHAR8  *FormatString,
396  IN  VA_LIST      Marker
397  );
398
399/**
400  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
401  ASCII format string and a BASE_LIST argument list.
402
403  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
404  and BufferSize.
405  The Unicode string is produced by parsing the format string specified by FormatString.
406  Arguments are pulled from the variable argument list specified by Marker based on the
407  contents of the format string.
408  The number of Unicode characters in the produced output buffer is returned not including
409  the Null-terminator.
410
411  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
412
413  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
414  unmodified and 0 is returned.
415  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
416  unmodified and 0 is returned.
417  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
418  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
419  buffer is unmodified and 0 is returned.
420  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
421  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
422  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
423
424  If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
425
426  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
427                          Unicode string.
428  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
429  @param  FormatString    A Null-terminated ASCII format string.
430  @param  Marker          BASE_LIST marker for the variable argument list.
431
432  @return The number of Unicode characters in the produced output buffer not including the
433          Null-terminator.
434
435**/
436UINTN
437EFIAPI
438UnicodeBSPrintAsciiFormat (
439  OUT CHAR16       *StartOfBuffer,
440  IN  UINTN        BufferSize,
441  IN  CONST CHAR8  *FormatString,
442  IN  BASE_LIST    Marker
443  );
444
445/**
446  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
447  ASCII format string and  variable argument list.
448
449  This function is similar as snprintf_s defined in C11.
450
451  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
452  and BufferSize.
453  The Unicode string is produced by parsing the format string specified by FormatString.
454  Arguments are pulled from the variable argument list based on the contents of the
455  format string.
456  The number of Unicode characters in the produced output buffer is returned not including
457  the Null-terminator.
458
459  If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
460
461  If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
462  unmodified and 0 is returned.
463  If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
464  unmodified and 0 is returned.
465  If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
466  (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
467  buffer is unmodified and 0 is returned.
468  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
469  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
470  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
471
472  If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
473
474  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
475                          Unicode string.
476  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
477  @param  FormatString    A Null-terminated ASCII format string.
478  @param  ...             Variable argument list whose contents are accessed based on the
479                          format string specified by FormatString.
480
481  @return The number of Unicode characters in the produced output buffer not including the
482          Null-terminator.
483
484**/
485UINTN
486EFIAPI
487UnicodeSPrintAsciiFormat (
488  OUT CHAR16       *StartOfBuffer,
489  IN  UINTN        BufferSize,
490  IN  CONST CHAR8  *FormatString,
491  ...
492  );
493
494#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
495
496/**
497  [ATTENTION] This function is deprecated for security reason.
498
499  Converts a decimal value to a Null-terminated Unicode string.
500
501  Converts the decimal number specified by Value to a Null-terminated Unicode
502  string specified by Buffer containing at most Width characters. No padding of spaces
503  is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
504  The number of Unicode characters in Buffer is returned, not including the Null-terminator.
505  If the conversion contains more than Width characters, then only the first
506  Width characters are returned, and the total number of characters
507  required to perform the conversion is returned.
508  Additional conversion parameters are specified in Flags.
509
510  The Flags bit LEFT_JUSTIFY is always ignored.
511  All conversions are left justified in Buffer.
512  If Width is 0, PREFIX_ZERO is ignored in Flags.
513  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
514  are inserted every 3rd digit starting from the right.
515  If RADIX_HEX is set in Flags, then the output buffer will be
516  formatted in hexadecimal format.
517  If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
518  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
519  then Buffer is padded with '0' characters so the combination of the optional '-'
520  sign character, '0' characters, digit characters for Value, and the Null-terminator
521  add up to Width characters.
522  If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
523  If Buffer is NULL, then ASSERT().
524  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
525  If unsupported bits are set in Flags, then ASSERT().
526  If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
527  If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
528
529  @param  Buffer  The pointer to the output buffer for the produced Null-terminated
530                  Unicode string.
531  @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
532  @param  Value   The 64-bit signed value to convert to a string.
533  @param  Width   The maximum number of Unicode characters to place in Buffer, not including
534                  the Null-terminator.
535
536  @return The number of Unicode characters in Buffer, not including the Null-terminator.
537
538**/
539UINTN
540EFIAPI
541UnicodeValueToString (
542  IN OUT CHAR16  *Buffer,
543  IN UINTN       Flags,
544  IN INT64       Value,
545  IN UINTN       Width
546  );
547
548#endif
549
550/**
551  Converts a decimal value to a Null-terminated Unicode string.
552
553  Converts the decimal number specified by Value to a Null-terminated Unicode
554  string specified by Buffer containing at most Width characters. No padding of
555  spaces is ever performed. If Width is 0 then a width of
556  MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
557  Width characters, then only the first Width characters are placed in Buffer.
558  Additional conversion parameters are specified in Flags.
559
560  The Flags bit LEFT_JUSTIFY is always ignored.
561  All conversions are left justified in Buffer.
562  If Width is 0, PREFIX_ZERO is ignored in Flags.
563  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
564  commas are inserted every 3rd digit starting from the right.
565  If RADIX_HEX is set in Flags, then the output buffer will be formatted in
566  hexadecimal format.
567  If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
568  Buffer is a '-'.
569  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
570  Buffer is padded with '0' characters so the combination of the optional '-'
571  sign character, '0' characters, digit characters for Value, and the
572  Null-terminator add up to Width characters.
573
574  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
575  If an error would be returned, then the function will also ASSERT().
576
577  @param  Buffer      The pointer to the output buffer for the produced
578                      Null-terminated Unicode string.
579  @param  BufferSize  The size of Buffer in bytes, including the
580                      Null-terminator.
581  @param  Flags       The bitmask of flags that specify left justification,
582                      zero pad, and commas.
583  @param  Value       The 64-bit signed value to convert to a string.
584  @param  Width       The maximum number of Unicode characters to place in
585                      Buffer, not including the Null-terminator.
586
587  @retval RETURN_SUCCESS           The decimal value is converted.
588  @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
589                                   value.
590  @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
591                                   If PcdMaximumUnicodeStringLength is not
592                                   zero, and BufferSize is greater than
593                                   (PcdMaximumUnicodeStringLength *
594                                   sizeof (CHAR16) + 1).
595                                   If unsupported bits are set in Flags.
596                                   If both COMMA_TYPE and RADIX_HEX are set in
597                                   Flags.
598                                   If Width >= MAXIMUM_VALUE_CHARACTERS.
599
600**/
601RETURN_STATUS
602EFIAPI
603UnicodeValueToStringS (
604  IN OUT CHAR16  *Buffer,
605  IN UINTN       BufferSize,
606  IN UINTN       Flags,
607  IN INT64       Value,
608  IN UINTN       Width
609  );
610
611/**
612  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
613  ASCII format string and a VA_LIST argument list.
614
615  This function is similar as vsnprintf_s defined in C11.
616
617  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
618  and BufferSize.
619  The ASCII string is produced by parsing the format string specified by FormatString.
620  Arguments are pulled from the variable argument list specified by Marker based on
621  the contents of the format string.
622  The number of ASCII characters in the produced output buffer is returned not including
623  the Null-terminator.
624
625  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
626  unmodified and 0 is returned.
627  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
628  unmodified and 0 is returned.
629  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
630  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
631  is unmodified and 0 is returned.
632  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
633  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
634  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
635
636  If BufferSize is 0, then no output buffer is produced and 0 is returned.
637
638  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
639                          ASCII string.
640  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
641  @param  FormatString    A Null-terminated ASCII format string.
642  @param  Marker          VA_LIST marker for the variable argument list.
643
644  @return The number of ASCII characters in the produced output buffer not including the
645          Null-terminator.
646
647**/
648UINTN
649EFIAPI
650AsciiVSPrint (
651  OUT CHAR8         *StartOfBuffer,
652  IN  UINTN         BufferSize,
653  IN  CONST CHAR8   *FormatString,
654  IN  VA_LIST       Marker
655  );
656
657/**
658  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
659  ASCII format string and a BASE_LIST argument list.
660
661  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
662  and BufferSize.
663  The ASCII string is produced by parsing the format string specified by FormatString.
664  Arguments are pulled from the variable argument list specified by Marker based on
665  the contents of the format string.
666  The number of ASCII characters in the produced output buffer is returned not including
667  the Null-terminator.
668
669  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
670  unmodified and 0 is returned.
671  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
672  unmodified and 0 is returned.
673  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
674  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
675  is unmodified and 0 is returned.
676  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
677  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
678  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
679
680  If BufferSize is 0, then no output buffer is produced and 0 is returned.
681
682  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
683                          ASCII string.
684  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
685  @param  FormatString    A Null-terminated ASCII format string.
686  @param  Marker          BASE_LIST marker for the variable argument list.
687
688  @return The number of ASCII characters in the produced output buffer not including the
689          Null-terminator.
690
691**/
692UINTN
693EFIAPI
694AsciiBSPrint (
695  OUT CHAR8         *StartOfBuffer,
696  IN  UINTN         BufferSize,
697  IN  CONST CHAR8   *FormatString,
698  IN  BASE_LIST     Marker
699  );
700
701/**
702  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
703  ASCII format string and  variable argument list.
704
705  This function is similar as snprintf_s defined in C11.
706
707  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
708  and BufferSize.
709  The ASCII string is produced by parsing the format string specified by FormatString.
710  Arguments are pulled from the variable argument list based on the contents of the
711  format string.
712  The number of ASCII characters in the produced output buffer is returned not including
713  the Null-terminator.
714
715  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
716  unmodified and 0 is returned.
717  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
718  unmodified and 0 is returned.
719  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
720  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
721  is unmodified and 0 is returned.
722  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
723  PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
724  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
725
726  If BufferSize is 0, then no output buffer is produced and 0 is returned.
727
728  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
729                          ASCII string.
730  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
731  @param  FormatString    A Null-terminated ASCII format string.
732  @param  ...             Variable argument list whose contents are accessed based on the
733                          format string specified by FormatString.
734
735  @return The number of ASCII characters in the produced output buffer not including the
736          Null-terminator.
737
738**/
739UINTN
740EFIAPI
741AsciiSPrint (
742  OUT CHAR8        *StartOfBuffer,
743  IN  UINTN        BufferSize,
744  IN  CONST CHAR8  *FormatString,
745  ...
746  );
747
748/**
749  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
750  Unicode format string and a VA_LIST argument list.
751
752  This function is similar as vsnprintf_s defined in C11.
753
754  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
755  and BufferSize.
756  The ASCII string is produced by parsing the format string specified by FormatString.
757  Arguments are pulled from the variable argument list specified by Marker based on
758  the contents of the format string.
759  The number of ASCII characters in the produced output buffer is returned not including
760  the Null-terminator.
761
762  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
763
764  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
765  unmodified and 0 is returned.
766  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
767  unmodified and 0 is returned.
768  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
769  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
770  is unmodified and 0 is returned.
771  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
772  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
773  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
774
775  If BufferSize is 0, then no output buffer is produced and 0 is returned.
776
777  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
778                          ASCII string.
779  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
780  @param  FormatString    A Null-terminated Unicode format string.
781  @param  Marker          VA_LIST marker for the variable argument list.
782
783  @return The number of ASCII characters in the produced output buffer not including the
784          Null-terminator.
785
786**/
787UINTN
788EFIAPI
789AsciiVSPrintUnicodeFormat (
790  OUT CHAR8         *StartOfBuffer,
791  IN  UINTN         BufferSize,
792  IN  CONST CHAR16  *FormatString,
793  IN  VA_LIST       Marker
794  );
795
796/**
797  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
798  Unicode format string and a BASE_LIST argument list.
799
800  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
801  and BufferSize.
802  The ASCII string is produced by parsing the format string specified by FormatString.
803  Arguments are pulled from the variable argument list specified by Marker based on
804  the contents of the format string.
805  The number of ASCII characters in the produced output buffer is returned not including
806  the Null-terminator.
807
808  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
809
810  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
811  unmodified and 0 is returned.
812  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
813  unmodified and 0 is returned.
814  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
815  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
816  is unmodified and 0 is returned.
817  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
818  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
819  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
820
821  If BufferSize is 0, then no output buffer is produced and 0 is returned.
822
823  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
824                          ASCII string.
825  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
826  @param  FormatString    A Null-terminated Unicode format string.
827  @param  Marker          BASE_LIST marker for the variable argument list.
828
829  @return The number of ASCII characters in the produced output buffer not including the
830          Null-terminator.
831
832**/
833UINTN
834EFIAPI
835AsciiBSPrintUnicodeFormat (
836  OUT CHAR8         *StartOfBuffer,
837  IN  UINTN         BufferSize,
838  IN  CONST CHAR16  *FormatString,
839  IN  BASE_LIST     Marker
840  );
841
842/**
843  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
844  Unicode format string and  variable argument list.
845
846  This function is similar as snprintf_s defined in C11.
847
848  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
849  and BufferSize.
850  The ASCII string is produced by parsing the format string specified by FormatString.
851  Arguments are pulled from the variable argument list based on the contents of the
852  format string.
853  The number of ASCII characters in the produced output buffer is returned not including
854  the Null-terminator.
855
856  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
857
858  If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
859  unmodified and 0 is returned.
860  If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
861  unmodified and 0 is returned.
862  If PcdMaximumAsciiStringLength is not zero, and BufferSize >
863  (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
864  is unmodified and 0 is returned.
865  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
866  PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
867  ASSERT(). Also, the output buffer is unmodified and 0 is returned.
868
869  If BufferSize is 0, then no output buffer is produced and 0 is returned.
870
871  @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
872                          ASCII string.
873  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
874  @param  FormatString    A Null-terminated Unicode format string.
875  @param  ...             Variable argument list whose contents are accessed based on the
876                          format string specified by FormatString.
877
878  @return The number of ASCII characters in the produced output buffer not including the
879          Null-terminator.
880
881**/
882UINTN
883EFIAPI
884AsciiSPrintUnicodeFormat (
885  OUT CHAR8         *StartOfBuffer,
886  IN  UINTN         BufferSize,
887  IN  CONST CHAR16  *FormatString,
888  ...
889  );
890
891#ifndef DISABLE_NEW_DEPRECATED_INTERFACES
892
893/**
894  [ATTENTION] This function is deprecated for security reason.
895
896  Converts a decimal value to a Null-terminated ASCII string.
897
898  Converts the decimal number specified by Value to a Null-terminated ASCII string
899  specified by Buffer containing at most Width characters. No padding of spaces
900  is ever performed.
901  If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
902  The number of ASCII characters in Buffer is returned, not including the Null-terminator.
903  If the conversion contains more than Width characters, then only the first Width
904  characters are returned, and the total number of characters required to perform
905  the conversion is returned.
906  Additional conversion parameters are specified in Flags.
907  The Flags bit LEFT_JUSTIFY is always ignored.
908  All conversions are left justified in Buffer.
909  If Width is 0, PREFIX_ZERO is ignored in Flags.
910  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
911  are inserted every 3rd digit starting from the right.
912  If RADIX_HEX is set in Flags, then the output buffer will be
913  formatted in hexadecimal format.
914  If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
915  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
916  then Buffer is padded with '0' characters so the combination of the optional '-'
917  sign character, '0' characters, digit characters for Value, and the Null-terminator
918  add up to Width characters.
919
920  If Buffer is NULL, then ASSERT().
921  If unsupported bits are set in Flags, then ASSERT().
922  If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
923  If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
924
925  @param  Buffer  A pointer to the output buffer for the produced Null-terminated
926                  ASCII string.
927  @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
928  @param  Value   The 64-bit signed value to convert to a string.
929  @param  Width   The maximum number of ASCII characters to place in Buffer, not including
930                  the Null-terminator.
931
932  @return The number of ASCII characters in Buffer, not including the Null-terminator.
933
934**/
935UINTN
936EFIAPI
937AsciiValueToString (
938  OUT CHAR8      *Buffer,
939  IN  UINTN      Flags,
940  IN  INT64      Value,
941  IN  UINTN      Width
942  );
943
944#endif
945
946/**
947  Converts a decimal value to a Null-terminated Ascii string.
948
949  Converts the decimal number specified by Value to a Null-terminated Ascii
950  string specified by Buffer containing at most Width characters. No padding of
951  spaces is ever performed. If Width is 0 then a width of
952  MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
953  Width characters, then only the first Width characters are placed in Buffer.
954  Additional conversion parameters are specified in Flags.
955
956  The Flags bit LEFT_JUSTIFY is always ignored.
957  All conversions are left justified in Buffer.
958  If Width is 0, PREFIX_ZERO is ignored in Flags.
959  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
960  commas are inserted every 3rd digit starting from the right.
961  If RADIX_HEX is set in Flags, then the output buffer will be formatted in
962  hexadecimal format.
963  If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
964  Buffer is a '-'.
965  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
966  Buffer is padded with '0' characters so the combination of the optional '-'
967  sign character, '0' characters, digit characters for Value, and the
968  Null-terminator add up to Width characters.
969
970  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
971  If an error would be returned, then the function will also ASSERT().
972
973  @param  Buffer      The pointer to the output buffer for the produced
974                      Null-terminated Ascii string.
975  @param  BufferSize  The size of Buffer in bytes, including the
976                      Null-terminator.
977  @param  Flags       The bitmask of flags that specify left justification,
978                      zero pad, and commas.
979  @param  Value       The 64-bit signed value to convert to a string.
980  @param  Width       The maximum number of Ascii characters to place in
981                      Buffer, not including the Null-terminator.
982
983  @retval RETURN_SUCCESS           The decimal value is converted.
984  @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
985                                   value.
986  @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
987                                   If PcdMaximumAsciiStringLength is not
988                                   zero, and BufferSize is greater than
989                                   PcdMaximumAsciiStringLength.
990                                   If unsupported bits are set in Flags.
991                                   If both COMMA_TYPE and RADIX_HEX are set in
992                                   Flags.
993                                   If Width >= MAXIMUM_VALUE_CHARACTERS.
994
995**/
996RETURN_STATUS
997EFIAPI
998AsciiValueToStringS (
999  IN OUT CHAR8   *Buffer,
1000  IN UINTN       BufferSize,
1001  IN UINTN       Flags,
1002  IN INT64       Value,
1003  IN UINTN       Width
1004  );
1005
1006/**
1007  Returns the number of characters that would be produced by if the formatted
1008  output were produced not including the Null-terminator.
1009
1010  If FormatString is not aligned on a 16-bit boundary, then ASSERT().
1011
1012  If FormatString is NULL, then ASSERT() and 0 is returned.
1013  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
1014  than PcdMaximumUnicodeStringLength Unicode characters not including the
1015  Null-terminator, then ASSERT() and 0 is returned.
1016
1017  @param[in]  FormatString    A Null-terminated Unicode format string.
1018  @param[in]  Marker          VA_LIST marker for the variable argument list.
1019
1020  @return The number of characters that would be produced, not including the
1021          Null-terminator.
1022**/
1023UINTN
1024EFIAPI
1025SPrintLength (
1026  IN  CONST CHAR16   *FormatString,
1027  IN  VA_LIST       Marker
1028  );
1029
1030/**
1031  Returns the number of characters that would be produced by if the formatted
1032  output were produced not including the Null-terminator.
1033
1034  If FormatString is NULL, then ASSERT() and 0 is returned.
1035  If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
1036  than PcdMaximumAsciiStringLength Ascii characters not including the
1037  Null-terminator, then ASSERT() and 0 is returned.
1038
1039  @param[in]  FormatString    A Null-terminated ASCII format string.
1040  @param[in]  Marker          VA_LIST marker for the variable argument list.
1041
1042  @return The number of characters that would be produced, not including the
1043          Null-terminator.
1044**/
1045UINTN
1046EFIAPI
1047SPrintLengthAsciiFormat (
1048  IN  CONST CHAR8   *FormatString,
1049  IN  VA_LIST       Marker
1050  );
1051
1052#endif
1053