MdePkg/BasePrintLib: Add safe print functions [A|U]ValueToStringS
[mirror_edk2.git] / MdePkg / Include / Library / PrintLib.h
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 /**
495 Converts a decimal value to a Null-terminated Unicode string.
496
497 Converts the decimal number specified by Value to a Null-terminated Unicode
498 string specified by Buffer containing at most Width characters. No padding of spaces
499 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
500 The number of Unicode characters in Buffer is returned, not including the Null-terminator.
501 If the conversion contains more than Width characters, then only the first
502 Width characters are returned, and the total number of characters
503 required to perform the conversion is returned.
504 Additional conversion parameters are specified in Flags.
505
506 The Flags bit LEFT_JUSTIFY is always ignored.
507 All conversions are left justified in Buffer.
508 If Width is 0, PREFIX_ZERO is ignored in Flags.
509 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
510 are inserted every 3rd digit starting from the right.
511 If RADIX_HEX is set in Flags, then the output buffer will be
512 formatted in hexadecimal format.
513 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
514 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
515 then Buffer is padded with '0' characters so the combination of the optional '-'
516 sign character, '0' characters, digit characters for Value, and the Null-terminator
517 add up to Width characters.
518 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
519 If Buffer is NULL, then ASSERT().
520 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
521 If unsupported bits are set in Flags, then ASSERT().
522 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
523 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
524
525 @param Buffer The pointer to the output buffer for the produced Null-terminated
526 Unicode string.
527 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
528 @param Value The 64-bit signed value to convert to a string.
529 @param Width The maximum number of Unicode characters to place in Buffer, not including
530 the Null-terminator.
531
532 @return The number of Unicode characters in Buffer, not including the Null-terminator.
533
534 **/
535 UINTN
536 EFIAPI
537 UnicodeValueToString (
538 IN OUT CHAR16 *Buffer,
539 IN UINTN Flags,
540 IN INT64 Value,
541 IN UINTN Width
542 );
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 **/
595 RETURN_STATUS
596 EFIAPI
597 UnicodeValueToStringS (
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 **/
642 UINTN
643 EFIAPI
644 AsciiVSPrint (
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 **/
686 UINTN
687 EFIAPI
688 AsciiBSPrint (
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 **/
733 UINTN
734 EFIAPI
735 AsciiSPrint (
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 **/
781 UINTN
782 EFIAPI
783 AsciiVSPrintUnicodeFormat (
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 **/
827 UINTN
828 EFIAPI
829 AsciiBSPrintUnicodeFormat (
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 **/
876 UINTN
877 EFIAPI
878 AsciiSPrintUnicodeFormat (
879 OUT CHAR8 *StartOfBuffer,
880 IN UINTN BufferSize,
881 IN CONST CHAR16 *FormatString,
882 ...
883 );
884
885 /**
886 Converts a decimal value to a Null-terminated ASCII string.
887
888 Converts the decimal number specified by Value to a Null-terminated ASCII string
889 specified by Buffer containing at most Width characters. No padding of spaces
890 is ever performed.
891 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
892 The number of ASCII characters in Buffer is returned, not including the Null-terminator.
893 If the conversion contains more than Width characters, then only the first Width
894 characters are returned, and the total number of characters required to perform
895 the conversion is returned.
896 Additional conversion parameters are specified in Flags.
897 The Flags bit LEFT_JUSTIFY is always ignored.
898 All conversions are left justified in Buffer.
899 If Width is 0, PREFIX_ZERO is ignored in Flags.
900 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
901 are inserted every 3rd digit starting from the right.
902 If RADIX_HEX is set in Flags, then the output buffer will be
903 formatted in hexadecimal format.
904 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
905 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
906 then Buffer is padded with '0' characters so the combination of the optional '-'
907 sign character, '0' characters, digit characters for Value, and the Null-terminator
908 add up to Width characters.
909
910 If Buffer is NULL, then ASSERT().
911 If unsupported bits are set in Flags, then ASSERT().
912 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
913 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
914
915 @param Buffer A pointer to the output buffer for the produced Null-terminated
916 ASCII string.
917 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
918 @param Value The 64-bit signed value to convert to a string.
919 @param Width The maximum number of ASCII characters to place in Buffer, not including
920 the Null-terminator.
921
922 @return The number of ASCII characters in Buffer, not including the Null-terminator.
923
924 **/
925 UINTN
926 EFIAPI
927 AsciiValueToString (
928 OUT CHAR8 *Buffer,
929 IN UINTN Flags,
930 IN INT64 Value,
931 IN UINTN Width
932 );
933
934 /**
935 Converts a decimal value to a Null-terminated Ascii string.
936
937 Converts the decimal number specified by Value to a Null-terminated Ascii
938 string specified by Buffer containing at most Width characters. No padding of
939 spaces is ever performed. If Width is 0 then a width of
940 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
941 Width characters, then only the first Width characters are placed in Buffer.
942 Additional conversion parameters are specified in Flags.
943
944 The Flags bit LEFT_JUSTIFY is always ignored.
945 All conversions are left justified in Buffer.
946 If Width is 0, PREFIX_ZERO is ignored in Flags.
947 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
948 commas are inserted every 3rd digit starting from the right.
949 If RADIX_HEX is set in Flags, then the output buffer will be formatted in
950 hexadecimal format.
951 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
952 Buffer is a '-'.
953 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
954 Buffer is padded with '0' characters so the combination of the optional '-'
955 sign character, '0' characters, digit characters for Value, and the
956 Null-terminator add up to Width characters.
957
958 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
959 If an error would be returned, then the function will also ASSERT().
960
961 @param Buffer The pointer to the output buffer for the produced
962 Null-terminated Ascii string.
963 @param BufferSize The size of Buffer in bytes, including the
964 Null-terminator.
965 @param Flags The bitmask of flags that specify left justification,
966 zero pad, and commas.
967 @param Value The 64-bit signed value to convert to a string.
968 @param Width The maximum number of Ascii characters to place in
969 Buffer, not including the Null-terminator.
970
971 @retval RETURN_SUCCESS The decimal value is converted.
972 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted
973 value.
974 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
975 If PcdMaximumAsciiStringLength is not
976 zero, and BufferSize is greater than
977 PcdMaximumAsciiStringLength.
978 If unsupported bits are set in Flags.
979 If both COMMA_TYPE and RADIX_HEX are set in
980 Flags.
981 If Width >= MAXIMUM_VALUE_CHARACTERS.
982
983 **/
984 RETURN_STATUS
985 EFIAPI
986 AsciiValueToStringS (
987 IN OUT CHAR8 *Buffer,
988 IN UINTN BufferSize,
989 IN UINTN Flags,
990 IN INT64 Value,
991 IN UINTN Width
992 );
993
994 /**
995 Returns the number of characters that would be produced by if the formatted
996 output were produced not including the Null-terminator.
997
998 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
999
1000 If FormatString is NULL, then ASSERT() and 0 is returned.
1001 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
1002 than PcdMaximumUnicodeStringLength Unicode characters not including the
1003 Null-terminator, then ASSERT() and 0 is returned.
1004
1005 @param[in] FormatString A Null-terminated Unicode format string.
1006 @param[in] Marker VA_LIST marker for the variable argument list.
1007
1008 @return The number of characters that would be produced, not including the
1009 Null-terminator.
1010 **/
1011 UINTN
1012 EFIAPI
1013 SPrintLength (
1014 IN CONST CHAR16 *FormatString,
1015 IN VA_LIST Marker
1016 );
1017
1018 /**
1019 Returns the number of characters that would be produced by if the formatted
1020 output were produced not including the Null-terminator.
1021
1022 If FormatString is NULL, then ASSERT() and 0 is returned.
1023 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
1024 than PcdMaximumAsciiStringLength Ascii characters not including the
1025 Null-terminator, then ASSERT() and 0 is returned.
1026
1027 @param[in] FormatString A Null-terminated ASCII format string.
1028 @param[in] Marker VA_LIST marker for the variable argument list.
1029
1030 @return The number of characters that would be produced, not including the
1031 Null-terminator.
1032 **/
1033 UINTN
1034 EFIAPI
1035 SPrintLengthAsciiFormat (
1036 IN CONST CHAR8 *FormatString,
1037 IN VA_LIST Marker
1038 );
1039
1040 #endif