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