VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdePkg/Include/Library/PrintLib.h@ 99396

Last change on this file since 99396 was 89983, checked in by vboxsync, 4 years ago

Devices/EFI: Merge edk-stable202105 and openssl 1.1.1j and make it build, bugref:4643
  • Property svn:eol-style set to native
File size: 38.8 KB
Line 
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/**
489 Converts a decimal value to a Null-terminated Unicode string.
490
491 Converts the decimal number specified by Value to a Null-terminated Unicode
492 string specified by Buffer containing at most Width characters. No padding of
493 spaces is ever performed. If Width is 0 then a width of
494 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
495 Width characters, then only the first Width characters are placed in Buffer.
496 Additional conversion parameters are specified in Flags.
497
498 The Flags bit LEFT_JUSTIFY is always ignored.
499 All conversions are left justified in Buffer.
500 If Width is 0, PREFIX_ZERO is ignored in Flags.
501 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
502 commas are inserted every 3rd digit starting from the right.
503 If RADIX_HEX is set in Flags, then the output buffer will be formatted in
504 hexadecimal format.
505 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
506 Buffer is a '-'.
507 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
508 Buffer is padded with '0' characters so the combination of the optional '-'
509 sign character, '0' characters, digit characters for Value, and the
510 Null-terminator add up to Width characters.
511
512 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
513 If an error would be returned, then the function will also ASSERT().
514
515 @param Buffer The pointer to the output buffer for the produced
516 Null-terminated Unicode string.
517 @param BufferSize The size of Buffer in bytes, including the
518 Null-terminator.
519 @param Flags The bitmask of flags that specify left justification,
520 zero pad, and commas.
521 @param Value The 64-bit signed value to convert to a string.
522 @param Width The maximum number of Unicode characters to place in
523 Buffer, not including the Null-terminator.
524
525 @retval RETURN_SUCCESS The decimal value is converted.
526 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted
527 value.
528 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
529 If PcdMaximumUnicodeStringLength is not
530 zero, and BufferSize is greater than
531 (PcdMaximumUnicodeStringLength *
532 sizeof (CHAR16) + 1).
533 If unsupported bits are set in Flags.
534 If both COMMA_TYPE and RADIX_HEX are set in
535 Flags.
536 If Width >= MAXIMUM_VALUE_CHARACTERS.
537
538**/
539RETURN_STATUS
540EFIAPI
541UnicodeValueToStringS (
542 IN OUT CHAR16 *Buffer,
543 IN UINTN BufferSize,
544 IN UINTN Flags,
545 IN INT64 Value,
546 IN UINTN Width
547 );
548
549/**
550 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
551 ASCII format string and a VA_LIST argument list.
552
553 This function is similar as vsnprintf_s defined in C11.
554
555 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
556 and BufferSize.
557 The ASCII string is produced by parsing the format string specified by FormatString.
558 Arguments are pulled from the variable argument list specified by Marker based on
559 the contents of the format string.
560 The number of ASCII characters in the produced output buffer is returned not including
561 the Null-terminator.
562
563 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
564 unmodified and 0 is returned.
565 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
566 unmodified and 0 is returned.
567 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
568 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
569 is unmodified and 0 is returned.
570 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
571 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
572 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
573
574 If BufferSize is 0, then no output buffer is produced and 0 is returned.
575
576 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
577 ASCII string.
578 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
579 @param FormatString A Null-terminated ASCII format string.
580 @param Marker VA_LIST marker for the variable argument list.
581
582 @return The number of ASCII characters in the produced output buffer not including the
583 Null-terminator.
584
585**/
586UINTN
587EFIAPI
588AsciiVSPrint (
589 OUT CHAR8 *StartOfBuffer,
590 IN UINTN BufferSize,
591 IN CONST CHAR8 *FormatString,
592 IN VA_LIST Marker
593 );
594
595/**
596 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
597 ASCII format string and a BASE_LIST argument list.
598
599 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
600 and BufferSize.
601 The ASCII string is produced by parsing the format string specified by FormatString.
602 Arguments are pulled from the variable argument list specified by Marker based on
603 the contents of the format string.
604 The number of ASCII characters in the produced output buffer is returned not including
605 the Null-terminator.
606
607 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
608 unmodified and 0 is returned.
609 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
610 unmodified and 0 is returned.
611 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
612 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
613 is unmodified and 0 is returned.
614 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
615 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
616 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
617
618 If BufferSize is 0, then no output buffer is produced and 0 is returned.
619
620 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
621 ASCII string.
622 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
623 @param FormatString A Null-terminated ASCII format string.
624 @param Marker BASE_LIST marker for the variable argument list.
625
626 @return The number of ASCII characters in the produced output buffer not including the
627 Null-terminator.
628
629**/
630UINTN
631EFIAPI
632AsciiBSPrint (
633 OUT CHAR8 *StartOfBuffer,
634 IN UINTN BufferSize,
635 IN CONST CHAR8 *FormatString,
636 IN BASE_LIST Marker
637 );
638
639/**
640 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
641 ASCII format string and variable argument list.
642
643 This function is similar as snprintf_s defined in C11.
644
645 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
646 and BufferSize.
647 The ASCII string is produced by parsing the format string specified by FormatString.
648 Arguments are pulled from the variable argument list based on the contents of the
649 format string.
650 The number of ASCII characters in the produced output buffer is returned not including
651 the Null-terminator.
652
653 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
654 unmodified and 0 is returned.
655 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
656 unmodified and 0 is returned.
657 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
658 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
659 is unmodified and 0 is returned.
660 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
661 PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
662 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
663
664 If BufferSize is 0, then no output buffer is produced and 0 is returned.
665
666 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
667 ASCII string.
668 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
669 @param FormatString A Null-terminated ASCII format string.
670 @param ... Variable argument list whose contents are accessed based on the
671 format string specified by FormatString.
672
673 @return The number of ASCII characters in the produced output buffer not including the
674 Null-terminator.
675
676**/
677UINTN
678EFIAPI
679AsciiSPrint (
680 OUT CHAR8 *StartOfBuffer,
681 IN UINTN BufferSize,
682 IN CONST CHAR8 *FormatString,
683 ...
684 );
685
686/**
687 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
688 Unicode format string and a VA_LIST argument list.
689
690 This function is similar as vsnprintf_s defined in C11.
691
692 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
693 and BufferSize.
694 The ASCII string is produced by parsing the format string specified by FormatString.
695 Arguments are pulled from the variable argument list specified by Marker based on
696 the contents of the format string.
697 The number of ASCII characters in the produced output buffer is returned not including
698 the Null-terminator.
699
700 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
701
702 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
703 unmodified and 0 is returned.
704 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
705 unmodified and 0 is returned.
706 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
707 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
708 is unmodified and 0 is returned.
709 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
710 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
711 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
712
713 If BufferSize is 0, then no output buffer is produced and 0 is returned.
714
715 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
716 ASCII string.
717 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
718 @param FormatString A Null-terminated Unicode format string.
719 @param Marker VA_LIST marker for the variable argument list.
720
721 @return The number of ASCII characters in the produced output buffer not including the
722 Null-terminator.
723
724**/
725UINTN
726EFIAPI
727AsciiVSPrintUnicodeFormat (
728 OUT CHAR8 *StartOfBuffer,
729 IN UINTN BufferSize,
730 IN CONST CHAR16 *FormatString,
731 IN VA_LIST Marker
732 );
733
734/**
735 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
736 Unicode format string and a BASE_LIST argument list.
737
738 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
739 and BufferSize.
740 The ASCII string is produced by parsing the format string specified by FormatString.
741 Arguments are pulled from the variable argument list specified by Marker based on
742 the contents of the format string.
743 The number of ASCII characters in the produced output buffer is returned not including
744 the Null-terminator.
745
746 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
747
748 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
749 unmodified and 0 is returned.
750 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
751 unmodified and 0 is returned.
752 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
753 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
754 is unmodified and 0 is returned.
755 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
756 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
757 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
758
759 If BufferSize is 0, then no output buffer is produced and 0 is returned.
760
761 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
762 ASCII string.
763 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
764 @param FormatString A Null-terminated Unicode format string.
765 @param Marker BASE_LIST marker for the variable argument list.
766
767 @return The number of ASCII characters in the produced output buffer not including the
768 Null-terminator.
769
770**/
771UINTN
772EFIAPI
773AsciiBSPrintUnicodeFormat (
774 OUT CHAR8 *StartOfBuffer,
775 IN UINTN BufferSize,
776 IN CONST CHAR16 *FormatString,
777 IN BASE_LIST Marker
778 );
779
780/**
781 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
782 Unicode format string and variable argument list.
783
784 This function is similar as snprintf_s defined in C11.
785
786 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
787 and BufferSize.
788 The ASCII string is produced by parsing the format string specified by FormatString.
789 Arguments are pulled from the variable argument list based on the contents of the
790 format string.
791 The number of ASCII characters in the produced output buffer is returned not including
792 the Null-terminator.
793
794 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
795
796 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
797 unmodified and 0 is returned.
798 If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
799 unmodified and 0 is returned.
800 If PcdMaximumAsciiStringLength is not zero, and BufferSize >
801 (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
802 is unmodified and 0 is returned.
803 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
804 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
805 ASSERT(). Also, the output buffer is unmodified and 0 is returned.
806
807 If BufferSize is 0, then no output buffer is produced and 0 is returned.
808
809 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
810 ASCII string.
811 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
812 @param FormatString A Null-terminated Unicode format string.
813 @param ... Variable argument list whose contents are accessed based on the
814 format string specified by FormatString.
815
816 @return The number of ASCII characters in the produced output buffer not including the
817 Null-terminator.
818
819**/
820UINTN
821EFIAPI
822AsciiSPrintUnicodeFormat (
823 OUT CHAR8 *StartOfBuffer,
824 IN UINTN BufferSize,
825 IN CONST CHAR16 *FormatString,
826 ...
827 );
828
829
830/**
831 Converts a decimal value to a Null-terminated Ascii string.
832
833 Converts the decimal number specified by Value to a Null-terminated Ascii
834 string specified by Buffer containing at most Width characters. No padding of
835 spaces is ever performed. If Width is 0 then a width of
836 MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
837 Width characters, then only the first Width characters are placed in Buffer.
838 Additional conversion parameters are specified in Flags.
839
840 The Flags bit LEFT_JUSTIFY is always ignored.
841 All conversions are left justified in Buffer.
842 If Width is 0, PREFIX_ZERO is ignored in Flags.
843 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
844 commas are inserted every 3rd digit starting from the right.
845 If RADIX_HEX is set in Flags, then the output buffer will be formatted in
846 hexadecimal format.
847 If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
848 Buffer is a '-'.
849 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
850 Buffer is padded with '0' characters so the combination of the optional '-'
851 sign character, '0' characters, digit characters for Value, and the
852 Null-terminator add up to Width characters.
853
854 If an error would be returned, then the function will ASSERT().
855
856 @param Buffer The pointer to the output buffer for the produced
857 Null-terminated Ascii string.
858 @param BufferSize The size of Buffer in bytes, including the
859 Null-terminator.
860 @param Flags The bitmask of flags that specify left justification,
861 zero pad, and commas.
862 @param Value The 64-bit signed value to convert to a string.
863 @param Width The maximum number of Ascii characters to place in
864 Buffer, not including the Null-terminator.
865
866 @retval RETURN_SUCCESS The decimal value is converted.
867 @retval RETURN_BUFFER_TOO_SMALL If BufferSize cannot hold the converted
868 value.
869 @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
870 If PcdMaximumAsciiStringLength is not
871 zero, and BufferSize is greater than
872 PcdMaximumAsciiStringLength.
873 If unsupported bits are set in Flags.
874 If both COMMA_TYPE and RADIX_HEX are set in
875 Flags.
876 If Width >= MAXIMUM_VALUE_CHARACTERS.
877
878**/
879RETURN_STATUS
880EFIAPI
881AsciiValueToStringS (
882 IN OUT CHAR8 *Buffer,
883 IN UINTN BufferSize,
884 IN UINTN Flags,
885 IN INT64 Value,
886 IN UINTN Width
887 );
888
889/**
890 Returns the number of characters that would be produced by if the formatted
891 output were produced not including the Null-terminator.
892
893 If FormatString is not aligned on a 16-bit boundary, then ASSERT().
894
895 If FormatString is NULL, then ASSERT() and 0 is returned.
896 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more
897 than PcdMaximumUnicodeStringLength Unicode characters not including the
898 Null-terminator, then ASSERT() and 0 is returned.
899
900 @param[in] FormatString A Null-terminated Unicode format string.
901 @param[in] Marker VA_LIST marker for the variable argument list.
902
903 @return The number of characters that would be produced, not including the
904 Null-terminator.
905**/
906UINTN
907EFIAPI
908SPrintLength (
909 IN CONST CHAR16 *FormatString,
910 IN VA_LIST Marker
911 );
912
913/**
914 Returns the number of characters that would be produced by if the formatted
915 output were produced not including the Null-terminator.
916
917 If FormatString is NULL, then ASSERT() and 0 is returned.
918 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more
919 than PcdMaximumAsciiStringLength Ascii characters not including the
920 Null-terminator, then ASSERT() and 0 is returned.
921
922 @param[in] FormatString A Null-terminated ASCII format string.
923 @param[in] Marker VA_LIST marker for the variable argument list.
924
925 @return The number of characters that would be produced, not including the
926 Null-terminator.
927**/
928UINTN
929EFIAPI
930SPrintLengthAsciiFormat (
931 IN CONST CHAR8 *FormatString,
932 IN VA_LIST Marker
933 );
934
935#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette