1 /** @file
2   Provides services to print a formatted string to a buffer. All combinations of
3   Unicode and ASCII strings are supported.
4 
5 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials are licensed and made available under
7 the terms and conditions of the BSD License that accompanies this distribution.
8 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   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 **/
246 UINTN
247 EFIAPI
248 UnicodeVSPrint (
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 **/
293 UINTN
294 EFIAPI
295 UnicodeBSPrint (
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 **/
342 UINTN
343 EFIAPI
344 UnicodeSPrint (
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 **/
390 UINTN
391 EFIAPI
392 UnicodeVSPrintAsciiFormat (
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 **/
436 UINTN
437 EFIAPI
438 UnicodeBSPrintAsciiFormat (
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 **/
485 UINTN
486 EFIAPI
487 UnicodeSPrintAsciiFormat (
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 **/
539 UINTN
540 EFIAPI
541 UnicodeValueToString (
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 **/
601 RETURN_STATUS
602 EFIAPI
603 UnicodeValueToStringS (
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 **/
648 UINTN
649 EFIAPI
650 AsciiVSPrint (
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 **/
692 UINTN
693 EFIAPI
694 AsciiBSPrint (
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 **/
739 UINTN
740 EFIAPI
741 AsciiSPrint (
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 **/
787 UINTN
788 EFIAPI
789 AsciiVSPrintUnicodeFormat (
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 **/
833 UINTN
834 EFIAPI
835 AsciiBSPrintUnicodeFormat (
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 **/
882 UINTN
883 EFIAPI
884 AsciiSPrintUnicodeFormat (
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 **/
935 UINTN
936 EFIAPI
937 AsciiValueToString (
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 **/
996 RETURN_STATUS
997 EFIAPI
998 AsciiValueToStringS (
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 **/
1023 UINTN
1024 EFIAPI
1025 SPrintLength (
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 **/
1045 UINTN
1046 EFIAPI
1047 SPrintLengthAsciiFormat (
1048   IN  CONST CHAR8   *FormatString,
1049   IN  VA_LIST       Marker
1050   );
1051 
1052 #endif
1053