MdePkg/BasePrintLib: Add safe print functions [A|U]ValueToStringS
[mirror_edk2.git] / MdePkg / Library / BasePrintLib / PrintLib.c
1 /** @file
2 Base Print Library instance implementation.
3
4 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
5 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. 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 **/
15
16 #include "PrintLibInternal.h"
17
18 //
19 // Declare a VA_LIST global variable that is used in calls to BasePrintLibSPrintMarker()
20 // when the BASE_LIST parameter is valid and the VA_LIST parameter is ignored.
21 // A NULL VA_LIST can not be passed into BasePrintLibSPrintMarker() because some
22 // compilers define VA_LIST to be a structure.
23 //
24 VA_LIST gNullVaList;
25
26 #define ASSERT_UNICODE_BUFFER(Buffer) ASSERT ((((UINTN) (Buffer)) & 0x01) == 0)
27
28 /**
29 Produces a Null-terminated Unicode string in an output buffer based on
30 a Null-terminated Unicode format string and a VA_LIST argument list.
31
32 This function is similar as vsnprintf_s defined in C11.
33
34 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
35 and BufferSize.
36 The Unicode string is produced by parsing the format string specified by FormatString.
37 Arguments are pulled from the variable argument list specified by Marker based on the
38 contents of the format string.
39 The number of Unicode characters in the produced output buffer is returned not including
40 the Null-terminator.
41
42 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
43 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
44
45 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
46 unmodified and 0 is returned.
47 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
48 unmodified and 0 is returned.
49 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
50 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
51 buffer is unmodified and 0 is returned.
52 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
53 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
54 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
55
56 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
57
58 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
59 Unicode string.
60 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
61 @param FormatString A Null-terminated Unicode format string.
62 @param Marker VA_LIST marker for the variable argument list.
63
64 @return The number of Unicode characters in the produced output buffer not including the
65 Null-terminator.
66
67 **/
68 UINTN
69 EFIAPI
70 UnicodeVSPrint (
71 OUT CHAR16 *StartOfBuffer,
72 IN UINTN BufferSize,
73 IN CONST CHAR16 *FormatString,
74 IN VA_LIST Marker
75 )
76 {
77 ASSERT_UNICODE_BUFFER (StartOfBuffer);
78 ASSERT_UNICODE_BUFFER (FormatString);
79 return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);
80 }
81
82 /**
83 Produces a Null-terminated Unicode string in an output buffer based on
84 a Null-terminated Unicode format string and a BASE_LIST argument list.
85
86 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
87 and BufferSize.
88 The Unicode string is produced by parsing the format string specified by FormatString.
89 Arguments are pulled from the variable argument list specified by Marker based on the
90 contents of the format string.
91 The number of Unicode characters in the produced output buffer is returned not including
92 the Null-terminator.
93
94 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
95 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
96
97 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
98 unmodified and 0 is returned.
99 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
100 unmodified and 0 is returned.
101 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
102 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
103 buffer is unmodified and 0 is returned.
104 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
105 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
106 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
107
108 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
109
110 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
111 Unicode string.
112 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
113 @param FormatString A Null-terminated Unicode format string.
114 @param Marker BASE_LIST marker for the variable argument list.
115
116 @return The number of Unicode characters in the produced output buffer not including the
117 Null-terminator.
118
119 **/
120 UINTN
121 EFIAPI
122 UnicodeBSPrint (
123 OUT CHAR16 *StartOfBuffer,
124 IN UINTN BufferSize,
125 IN CONST CHAR16 *FormatString,
126 IN BASE_LIST Marker
127 )
128 {
129 ASSERT_UNICODE_BUFFER (StartOfBuffer);
130 ASSERT_UNICODE_BUFFER (FormatString);
131 return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, gNullVaList, Marker);
132 }
133
134 /**
135 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
136 Unicode format string and variable argument list.
137
138 This function is similar as snprintf_s defined in C11.
139
140 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
141 and BufferSize.
142 The Unicode string is produced by parsing the format string specified by FormatString.
143 Arguments are pulled from the variable argument list based on the contents of the format string.
144 The number of Unicode characters in the produced output buffer is returned not including
145 the Null-terminator.
146
147 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
148 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
149
150 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
151 unmodified and 0 is returned.
152 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
153 unmodified and 0 is returned.
154 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
155 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
156 buffer is unmodified and 0 is returned.
157 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
158 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
159 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
160
161 If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
162
163 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
164 Unicode string.
165 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
166 @param FormatString A Null-terminated Unicode format string.
167 @param ... Variable argument list whose contents are accessed based on the
168 format string specified by FormatString.
169
170 @return The number of Unicode characters in the produced output buffer not including the
171 Null-terminator.
172
173 **/
174 UINTN
175 EFIAPI
176 UnicodeSPrint (
177 OUT CHAR16 *StartOfBuffer,
178 IN UINTN BufferSize,
179 IN CONST CHAR16 *FormatString,
180 ...
181 )
182 {
183 VA_LIST Marker;
184 UINTN NumberOfPrinted;
185
186 VA_START (Marker, FormatString);
187 NumberOfPrinted = UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
188 VA_END (Marker);
189 return NumberOfPrinted;
190 }
191
192 /**
193 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
194 ASCII format string and a VA_LIST argument list.
195
196 This function is similar as vsnprintf_s defined in C11.
197
198 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
199 and BufferSize.
200 The Unicode string is produced by parsing the format string specified by FormatString.
201 Arguments are pulled from the variable argument list specified by Marker based on the
202 contents of the format string.
203 The number of Unicode characters in the produced output buffer is returned not including
204 the Null-terminator.
205
206 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
207
208 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
209 unmodified and 0 is returned.
210 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
211 unmodified and 0 is returned.
212 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
213 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
214 buffer is unmodified and 0 is returned.
215 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
216 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
217 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
218
219 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
220
221 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
222 Unicode string.
223 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
224 @param FormatString A Null-terminated ASCII format string.
225 @param Marker VA_LIST marker for the variable argument list.
226
227 @return The number of Unicode characters in the produced output buffer not including the
228 Null-terminator.
229
230 **/
231 UINTN
232 EFIAPI
233 UnicodeVSPrintAsciiFormat (
234 OUT CHAR16 *StartOfBuffer,
235 IN UINTN BufferSize,
236 IN CONST CHAR8 *FormatString,
237 IN VA_LIST Marker
238 )
239 {
240 ASSERT_UNICODE_BUFFER (StartOfBuffer);
241 return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE, FormatString, Marker, NULL);
242 }
243
244 /**
245 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
246 ASCII format string and a BASE_LIST argument list.
247
248 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
249 and BufferSize.
250 The Unicode string is produced by parsing the format string specified by FormatString.
251 Arguments are pulled from the variable argument list specified by Marker based on the
252 contents of the format string.
253 The number of Unicode characters in the produced output buffer is returned not including
254 the Null-terminator.
255
256 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
257
258 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
259 unmodified and 0 is returned.
260 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
261 unmodified and 0 is returned.
262 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
263 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
264 buffer is unmodified and 0 is returned.
265 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
266 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
267 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
268
269 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
270
271 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
272 Unicode string.
273 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
274 @param FormatString A Null-terminated ASCII format string.
275 @param Marker BASE_LIST marker for the variable argument list.
276
277 @return The number of Unicode characters in the produced output buffer not including the
278 Null-terminator.
279
280 **/
281 UINTN
282 EFIAPI
283 UnicodeBSPrintAsciiFormat (
284 OUT CHAR16 *StartOfBuffer,
285 IN UINTN BufferSize,
286 IN CONST CHAR8 *FormatString,
287 IN BASE_LIST Marker
288 )
289 {
290 ASSERT_UNICODE_BUFFER (StartOfBuffer);
291 return BasePrintLibSPrintMarker ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE, FormatString, gNullVaList, Marker);
292 }
293
294 /**
295 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
296 ASCII format string and variable argument list.
297
298 This function is similar as snprintf_s defined in C11.
299
300 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
301 and BufferSize.
302 The Unicode string is produced by parsing the format string specified by FormatString.
303 Arguments are pulled from the variable argument list based on the contents of the
304 format string.
305 The number of Unicode characters in the produced output buffer is returned not including
306 the Null-terminator.
307
308 If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
309
310 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
311 unmodified and 0 is returned.
312 If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
313 unmodified and 0 is returned.
314 If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
315 (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
316 buffer is unmodified and 0 is returned.
317 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
318 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
319 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
320
321 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
322
323 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
324 Unicode string.
325 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
326 @param FormatString A Null-terminated ASCII format string.
327 @param ... Variable argument list whose contents are accessed based on the
328 format string specified by FormatString.
329
330 @return The number of Unicode characters in the produced output buffer not including the
331 Null-terminator.
332
333 **/
334 UINTN
335 EFIAPI
336 UnicodeSPrintAsciiFormat (
337 OUT CHAR16 *StartOfBuffer,
338 IN UINTN BufferSize,
339 IN CONST CHAR8 *FormatString,
340 ...
341 )
342 {
343 VA_LIST Marker;
344 UINTN NumberOfPrinted;
345
346 VA_START (Marker, FormatString);
347 NumberOfPrinted = UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);
348 VA_END (Marker);
349 return NumberOfPrinted;
350 }
351
352 /**
353 Converts a decimal value to a Null-terminated Unicode string.
354
355 Converts the decimal number specified by Value to a Null-terminated Unicode
356 string specified by Buffer containing at most Width characters. No padding of spaces
357 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
358 The number of Unicode characters in Buffer is returned not including the Null-terminator.
359 If the conversion contains more than Width characters, then only the first
360 Width characters are returned, and the total number of characters
361 required to perform the conversion is returned.
362 Additional conversion parameters are specified in Flags.
363
364 The Flags bit LEFT_JUSTIFY is always ignored.
365 All conversions are left justified in Buffer.
366 If Width is 0, PREFIX_ZERO is ignored in Flags.
367 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
368 are inserted every 3rd digit starting from the right.
369 If RADIX_HEX is set in Flags, then the output buffer will be
370 formatted in hexadecimal format.
371 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
372 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
373 then Buffer is padded with '0' characters so the combination of the optional '-'
374 sign character, '0' characters, digit characters for Value, and the Null-terminator
375 add up to Width characters.
376 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
377 If Buffer is NULL, then ASSERT().
378 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
379 If unsupported bits are set in Flags, then ASSERT().
380 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
381 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
382
383 @param Buffer The pointer to the output buffer for the produced Null-terminated
384 Unicode string.
385 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
386 @param Value The 64-bit signed value to convert to a string.
387 @param Width The maximum number of Unicode characters to place in Buffer, not including
388 the Null-terminator.
389
390 @return The number of Unicode characters in Buffer not including the Null-terminator.
391
392 **/
393 UINTN
394 EFIAPI
395 UnicodeValueToString (
396 IN OUT CHAR16 *Buffer,
397 IN UINTN Flags,
398 IN INT64 Value,
399 IN UINTN Width
400 )
401 {
402 ASSERT_UNICODE_BUFFER(Buffer);
403 return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
404 }
405
406 /**
407 Converts a decimal value to a Null-terminated Unicode string.
408
409 Converts the decimal number specified by Value to a Null-terminated Unicode
410 string specified by Buffer containing at most Width characters. No padding of
411 spaces is ever performed. If Width is 0 then a width of
412 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
413 Width characters, then only the first Width characters are placed in Buffer.
414 Additional conversion parameters are specified in Flags.
415
416 The Flags bit LEFT_JUSTIFY is always ignored.
417 All conversions are left justified in Buffer.
418 If Width is 0, PREFIX_ZERO is ignored in Flags.
419 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
420 commas are inserted every 3rd digit starting from the right.
421 If RADIX_HEX is set in Flags, then the output buffer will be formatted in
422 hexadecimal format.
423 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
424 Buffer is a '-'.
425 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
426 Buffer is padded with '0' characters so the combination of the optional '-'
427 sign character, '0' characters, digit characters for Value, and the
428 Null-terminator add up to Width characters.
429
430 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
431 If an error would be returned, then the function will also ASSERT().
432
433 @param Buffer The pointer to the output buffer for the produced
434 Null-terminated Unicode string.
435 @param BufferSize The size of Buffer in bytes, including the
436 Null-terminator.
437 @param Flags The bitmask of flags that specify left justification,
438 zero pad, and commas.
439 @param Value The 64-bit signed value to convert to a string.
440 @param Width The maximum number of Unicode characters to place in
441 Buffer, not including the Null-terminator.
442
443 @retval RETURN_SUCCESS The decimal value is converted.
444 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted
445 value.
446 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
447 If PcdMaximumUnicodeStringLength is not
448 zero, and BufferSize is greater than
449 (PcdMaximumUnicodeStringLength *
450 sizeof (CHAR16) + 1).
451 If unsupported bits are set in Flags.
452 If both COMMA_TYPE and RADIX_HEX are set in
453 Flags.
454 If Width >= MAXIMUM_VALUE_CHARACTERS.
455
456 **/
457 RETURN_STATUS
458 EFIAPI
459 UnicodeValueToStringS (
460 IN OUT CHAR16 *Buffer,
461 IN UINTN BufferSize,
462 IN UINTN Flags,
463 IN INT64 Value,
464 IN UINTN Width
465 )
466 {
467 ASSERT_UNICODE_BUFFER(Buffer);
468 return BasePrintLibConvertValueToStringS ((CHAR8 *)Buffer, BufferSize, Flags, Value, Width, 2);
469 }
470
471 /**
472 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
473 ASCII format string and a VA_LIST argument list.
474
475 This function is similar as vsnprintf_s defined in C11.
476
477 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
478 and BufferSize.
479 The ASCII string is produced by parsing the format string specified by FormatString.
480 Arguments are pulled from the variable argument list specified by Marker based on
481 the contents of the format string.
482 The number of ASCII characters in the produced output buffer is returned not including
483 the Null-terminator.
484
485 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
486 unmodified and 0 is returned.
487 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
488 unmodified and 0 is returned.
489 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
490 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
491 is unmodified and 0 is returned.
492 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
493 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
494 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
495
496 If BufferSize is 0, then no output buffer is produced and 0 is returned.
497
498 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
499 ASCII string.
500 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
501 @param FormatString A Null-terminated ASCII format string.
502 @param Marker VA_LIST marker for the variable argument list.
503
504 @return The number of ASCII characters in the produced output buffer not including the
505 Null-terminator.
506
507 **/
508 UINTN
509 EFIAPI
510 AsciiVSPrint (
511 OUT CHAR8 *StartOfBuffer,
512 IN UINTN BufferSize,
513 IN CONST CHAR8 *FormatString,
514 IN VA_LIST Marker
515 )
516 {
517 return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, Marker, NULL);
518 }
519
520 /**
521 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
522 ASCII format string and a BASE_LIST argument list.
523
524 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
525 and BufferSize.
526 The ASCII string is produced by parsing the format string specified by FormatString.
527 Arguments are pulled from the variable argument list specified by Marker based on
528 the contents of the format string.
529 The number of ASCII characters in the produced output buffer is returned not including
530 the Null-terminator.
531
532 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
533 unmodified and 0 is returned.
534 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
535 unmodified and 0 is returned.
536 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
537 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
538 is unmodified and 0 is returned.
539 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
540 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
541 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
542
543 If BufferSize is 0, then no output buffer is produced and 0 is returned.
544
545 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
546 ASCII string.
547 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
548 @param FormatString A Null-terminated ASCII format string.
549 @param Marker BASE_LIST marker for the variable argument list.
550
551 @return The number of ASCII characters in the produced output buffer not including the
552 Null-terminator.
553
554 **/
555 UINTN
556 EFIAPI
557 AsciiBSPrint (
558 OUT CHAR8 *StartOfBuffer,
559 IN UINTN BufferSize,
560 IN CONST CHAR8 *FormatString,
561 IN BASE_LIST Marker
562 )
563 {
564 return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, 0, FormatString, gNullVaList, Marker);
565 }
566
567 /**
568 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
569 ASCII format string and variable argument list.
570
571 This function is similar as snprintf_s defined in C11.
572
573 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
574 and BufferSize.
575 The ASCII string is produced by parsing the format string specified by FormatString.
576 Arguments are pulled from the variable argument list based on the contents of the
577 format string.
578 The number of ASCII characters in the produced output buffer is returned not including
579 the Null-terminator.
580
581 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
582 unmodified and 0 is returned.
583 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
584 unmodified and 0 is returned.
585 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
586 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
587 is unmodified and 0 is returned.
588 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
589 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
590 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
591
592 If BufferSize is 0, then no output buffer is produced and 0 is returned.
593
594 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
595 ASCII string.
596 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
597 @param FormatString A Null-terminated ASCII format string.
598 @param ... Variable argument list whose contents are accessed based on the
599 format string specified by FormatString.
600
601 @return The number of ASCII characters in the produced output buffer not including the
602 Null-terminator.
603
604 **/
605 UINTN
606 EFIAPI
607 AsciiSPrint (
608 OUT CHAR8 *StartOfBuffer,
609 IN UINTN BufferSize,
610 IN CONST CHAR8 *FormatString,
611 ...
612 )
613 {
614 VA_LIST Marker;
615 UINTN NumberOfPrinted;
616
617 VA_START (Marker, FormatString);
618 NumberOfPrinted = AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
619 VA_END (Marker);
620 return NumberOfPrinted;
621 }
622
623 /**
624 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
625 Unicode format string and a VA_LIST argument list.
626
627 This function is similar as vsnprintf_s defined in C11.
628
629 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
630 and BufferSize.
631 The ASCII string is produced by parsing the format string specified by FormatString.
632 Arguments are pulled from the variable argument list specified by Marker based on
633 the contents of the format string.
634 The number of ASCII characters in the produced output buffer is returned not including
635 the Null-terminator.
636
637 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
638
639 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
640 unmodified and 0 is returned.
641 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
642 unmodified and 0 is returned.
643 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
644 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
645 is unmodified and 0 is returned.
646 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
647 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
648 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
649
650 If BufferSize is 0, then no output buffer is produced and 0 is returned.
651
652 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
653 ASCII string.
654 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
655 @param FormatString A Null-terminated Unicode format string.
656 @param Marker VA_LIST marker for the variable argument list.
657
658 @return The number of ASCII characters in the produced output buffer not including the
659 Null-terminator.
660
661 **/
662 UINTN
663 EFIAPI
664 AsciiVSPrintUnicodeFormat (
665 OUT CHAR8 *StartOfBuffer,
666 IN UINTN BufferSize,
667 IN CONST CHAR16 *FormatString,
668 IN VA_LIST Marker
669 )
670 {
671 ASSERT_UNICODE_BUFFER (FormatString);
672 return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker, NULL);
673 }
674
675 /**
676 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
677 Unicode format string and a BASE_LIST argument list.
678
679 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
680 and BufferSize.
681 The ASCII string is produced by parsing the format string specified by FormatString.
682 Arguments are pulled from the variable argument list specified by Marker based on
683 the contents of the format string.
684 The number of ASCII characters in the produced output buffer is returned not including
685 the Null-terminator.
686
687 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
688
689 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
690 unmodified and 0 is returned.
691 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
692 unmodified and 0 is returned.
693 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
694 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
695 is unmodified and 0 is returned.
696 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
697 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
698 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
699
700 If BufferSize is 0, then no output buffer is produced and 0 is returned.
701
702 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
703 ASCII string.
704 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
705 @param FormatString A Null-terminated Unicode format string.
706 @param Marker BASE_LIST marker for the variable argument list.
707
708 @return The number of ASCII characters in the produced output buffer not including the
709 Null-terminator.
710
711 **/
712 UINTN
713 EFIAPI
714 AsciiBSPrintUnicodeFormat (
715 OUT CHAR8 *StartOfBuffer,
716 IN UINTN BufferSize,
717 IN CONST CHAR16 *FormatString,
718 IN BASE_LIST Marker
719 )
720 {
721 ASSERT_UNICODE_BUFFER (FormatString);
722 return BasePrintLibSPrintMarker (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, gNullVaList, Marker);
723 }
724
725 /**
726 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
727 Unicode format string and variable argument list.
728
729 This function is similar as snprintf_s defined in C11.
730
731 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
732 and BufferSize.
733 The ASCII string is produced by parsing the format string specified by FormatString.
734 Arguments are pulled from the variable argument list based on the contents of the
735 format string.
736 The number of ASCII characters in the produced output buffer is returned not including
737 the Null-terminator.
738
739 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
740
741 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
742 unmodified and 0 is returned.
743 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
744 unmodified and 0 is returned.
745 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
746 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
747 is unmodified and 0 is returned.
748 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
749 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
750 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
751
752 If BufferSize is 0, then no output buffer is produced and 0 is returned.
753
754 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
755 ASCII string.
756 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
757 @param FormatString A Null-terminated Unicode format string.
758 @param ... Variable argument list whose contents are accessed based on the
759 format string specified by FormatString.
760
761 @return The number of ASCII characters in the produced output buffer not including the
762 Null-terminator.
763
764 **/
765 UINTN
766 EFIAPI
767 AsciiSPrintUnicodeFormat (
768 OUT CHAR8 *StartOfBuffer,
769 IN UINTN BufferSize,
770 IN CONST CHAR16 *FormatString,
771 ...
772 )
773 {
774 VA_LIST Marker;
775 UINTN NumberOfPrinted;
776
777 VA_START (Marker, FormatString);
778 NumberOfPrinted = AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
779 VA_END (Marker);
780 return NumberOfPrinted;
781 }
782
783
784 /**
785 Converts a decimal value to a Null-terminated ASCII string.
786
787 Converts the decimal number specified by Value to a Null-terminated ASCII string
788 specified by Buffer containing at most Width characters. No padding of spaces
789 is ever performed.
790 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
791 The number of ASCII characters in Buffer is returned not including the Null-terminator.
792 If the conversion contains more than Width characters, then only the first Width
793 characters are returned, and the total number of characters required to perform
794 the conversion is returned.
795 Additional conversion parameters are specified in Flags.
796 The Flags bit LEFT_JUSTIFY is always ignored.
797 All conversions are left justified in Buffer.
798 If Width is 0, PREFIX_ZERO is ignored in Flags.
799 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
800 are inserted every 3rd digit starting from the right.
801 If RADIX_HEX is set in Flags, then the output buffer will be
802 formatted in hexadecimal format.
803 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
804 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
805 then Buffer is padded with '0' characters so the combination of the optional '-'
806 sign character, '0' characters, digit characters for Value, and the Null-terminator
807 add up to Width characters.
808
809 If Buffer is NULL, then ASSERT().
810 If unsupported bits are set in Flags, then ASSERT().
811 If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
812 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
813
814 @param Buffer The pointer to the output buffer for the produced Null-terminated
815 ASCII string.
816 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
817 @param Value The 64-bit signed value to convert to a string.
818 @param Width The maximum number of ASCII characters to place in Buffer, not including
819 the Null-terminator.
820
821 @return The number of ASCII characters in Buffer not including the Null-terminator.
822
823 **/
824 UINTN
825 EFIAPI
826 AsciiValueToString (
827 OUT CHAR8 *Buffer,
828 IN UINTN Flags,
829 IN INT64 Value,
830 IN UINTN Width
831 )
832 {
833 return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);
834 }
835
836 /**
837 Converts a decimal value to a Null-terminated Ascii string.
838
839 Converts the decimal number specified by Value to a Null-terminated Ascii
840 string specified by Buffer containing at most Width characters. No padding of
841 spaces is ever performed. If Width is 0 then a width of
842 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
843 Width characters, then only the first Width characters are placed in Buffer.
844 Additional conversion parameters are specified in Flags.
845
846 The Flags bit LEFT_JUSTIFY is always ignored.
847 All conversions are left justified in Buffer.
848 If Width is 0, PREFIX_ZERO is ignored in Flags.
849 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
850 commas are inserted every 3rd digit starting from the right.
851 If RADIX_HEX is set in Flags, then the output buffer will be formatted in
852 hexadecimal format.
853 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
854 Buffer is a '-'.
855 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
856 Buffer is padded with '0' characters so the combination of the optional '-'
857 sign character, '0' characters, digit characters for Value, and the
858 Null-terminator add up to Width characters.
859
860 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
861 If an error would be returned, then the function will also ASSERT().
862
863 @param Buffer The pointer to the output buffer for the produced
864 Null-terminated Ascii string.
865 @param BufferSize The size of Buffer in bytes, including the
866 Null-terminator.
867 @param Flags The bitmask of flags that specify left justification,
868 zero pad, and commas.
869 @param Value The 64-bit signed value to convert to a string.
870 @param Width The maximum number of Ascii characters to place in
871 Buffer, not including the Null-terminator.
872
873 @retval RETURN_SUCCESS The decimal value is converted.
874 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted
875 value.
876 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
877 If PcdMaximumAsciiStringLength is not
878 zero, and BufferSize is greater than
879 PcdMaximumAsciiStringLength.
880 If unsupported bits are set in Flags.
881 If both COMMA_TYPE and RADIX_HEX are set in
882 Flags.
883 If Width >= MAXIMUM_VALUE_CHARACTERS.
884
885 **/
886 RETURN_STATUS
887 EFIAPI
888 AsciiValueToStringS (
889 IN OUT CHAR8 *Buffer,
890 IN UINTN BufferSize,
891 IN UINTN Flags,
892 IN INT64 Value,
893 IN UINTN Width
894 )
895 {
896 return BasePrintLibConvertValueToStringS (Buffer, BufferSize, Flags, Value, Width, 1);
897 }
898
899 /**
900 Returns the number of characters that would be produced by if the formatted
901 output were produced not including the Null-terminator.
902
903 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
904
905 If FormatString is NULL, then ASSERT() and 0 is returned.
906 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
907 than PcdMaximumUnicodeStringLength Unicode characters not including the
908 Null-terminator, then ASSERT() and 0 is returned.
909
910 @param[in] FormatString A Null-terminated Unicode format string.
911 @param[in] Marker VA_LIST marker for the variable argument list.
912
913 @return The number of characters that would be produced, not including the
914 Null-terminator.
915 **/
916 UINTN
917 EFIAPI
918 SPrintLength (
919 IN CONST CHAR16 *FormatString,
920 IN VA_LIST Marker
921 )
922 {
923 ASSERT_UNICODE_BUFFER (FormatString);
924 return BasePrintLibSPrintMarker (NULL, 0, FORMAT_UNICODE | OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
925 }
926
927 /**
928 Returns the number of characters that would be produced by if the formatted
929 output were produced not including the Null-terminator.
930
931 If FormatString is NULL, then ASSERT() and 0 is returned.
932 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
933 than PcdMaximumAsciiStringLength Ascii characters not including the
934 Null-terminator, then ASSERT() and 0 is returned.
935
936 @param[in] FormatString A Null-terminated ASCII format string.
937 @param[in] Marker VA_LIST marker for the variable argument list.
938
939 @return The number of characters that would be produced, not including the
940 Null-terminator.
941 **/
942 UINTN
943 EFIAPI
944 SPrintLengthAsciiFormat (
945 IN CONST CHAR8 *FormatString,
946 IN VA_LIST Marker
947 )
948 {
949 return BasePrintLibSPrintMarker (NULL, 0, OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);
950 }