]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PrintLib.h
2 Provides services to print a formatted string to a buffer. All combinations of
3 Unicode and ASCII strings are supported.
5 Copyright (c) 2006 - 2008, Intel Corporation
6 All rights reserved. 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
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.
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. A normal text character '\n' must
19 always be converted to '\n\r'. This does not follow the ANSI C standard for
20 sprint(). The format of argument descriptors is described below. The ANSI C
21 standard for sprint() has been followed for some of the format types, and has
22 not been followed for others. The exceptions are noted below.
24 %[flags][width][.precision]type
28 - The field is left justified. If not flag is not specified, then the
29 field is right justified.
31 - Prefix a space character to a number. Only valid for types X, x, and d.
33 - Prefix a plus character to a number. Only valid for types X, x, and d.
34 If both space and + are specified, then space is ignored.
36 - Pad with 0 characters to the left of a number. Only valid for types
39 - Place a comma every 3rd digit of the number. Only valid for type d.
40 If 0 is also specified, then 0 is ignored.
42 - The number being printed is a UINT64. Only valid for types X, x, and d.
43 If this flag is not specified, then the number being printed is a int.
44 - NOTE: All invalid flags are ignored.
49 - The width of the field is specified by a UINTN argument in the
52 - The number specified as a decimal value represents the width of
54 - NOTE: If [width] is not specified, then a field width of 0 is assumed.
59 - The prevision of the field is specified by a UINTN argument in the
62 - The number specified as a decimal value represents the precision of
64 - NOTE: If [.precision] is not specified, then a precision of 0 is assumed.
71 - The argument is a Unicode character. ASCII characters can be printed
72 using this type too by making sure bits 8..15 of the argument are set to 0.
74 - The argument is a hexadecimal number. The characters used are 0..9 and
75 A..F. If the flag 'L' is not specified, then the argument is assumed
76 to be an int. This does not follow ANSI C.
78 - The argument is a hexadecimal number and the number is padded with
79 zeros. This is equivalent to a format string of "0x". If the flag
80 'L' is not specified, then the argument is assumed to be an int.
81 This does not follow ANSI C.
83 - The argument is a decimal number. If the flag 'L' is not specified,
84 then the argument is assumed to be an int.
86 - The argument is a pointer that is a (VOID *), and it is printed as a
87 hexadecimal number The characters used are 0..9 and A..F.
89 - The argument is a pointer to an ASCII string.
90 This does not follow ANSI C.
92 - The argument is a pointer to a Unicode string.
93 This does not follow ANSI C.
95 - The argument is a pointer to a GUID structure. The GUID is printed
96 in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
97 This does not follow ANSI C.
99 - The argument is a pointer to an EFI_TIME structure. The time and
100 date are printed in the format "mm/dd/yyyy hh:mm" where mm is the
101 month zero padded, dd is the day zero padded, yyyy is the year zero
102 padded, hh is the hour zero padded, and mm is minutes zero padded.
103 This does not follow ANSI C.
105 - The argument is a RETURN_STATUS value. This value is converted to
106 a string following the table below. This does not follow ANSI C.
111 - RETURN_INVALID_PARAMETER
112 - "Invalid Parameter"
115 - RETURN_BAD_BUFFER_SIZE
117 - RETURN_BUFFER_TOO_SMALL
121 - RETURN_DEVICE_ERROR
123 - RETURN_WRITE_PROTECTED
125 - RETURN_OUT_OF_RESOURCES
127 - RETURN_VOLUME_CORRUPTED
133 - RETURN_MEDIA_CHANGED
137 - RETURN_ACCESS_DENIED
147 - RETURN_ALREADY_STARTED
155 - RETURN_PROTOCOL_ERROR
157 - RETURN_WARN_UNKNOWN_GLYPH
158 - "Warning Unknown Glyph"
159 - RETURN_WARN_DELETE_FAILURE
160 - "Warning Delete Failure"
161 - RETURN_WARN_WRITE_FAILURE
162 - "Warning Write Failure"
163 - RETURN_WARN_BUFFER_TOO_SMALL
164 - "Warning Buffer Too Small"
168 #ifndef __PRINT_LIB_H__
169 #define __PRINT_LIB_H__
172 /// Define the maximum number of characters that are required to
173 /// encode a decimal, hexadecimal, GUID, or TIME value with a NULL
176 /// Maximum Length Decimal String = 28
177 /// "-9,223,372,036,854,775,808"
178 /// Maximum Length Hexadecimal String = 17
179 /// "FFFFFFFFFFFFFFFF"
180 /// Maximum Length GUID = 37
181 /// "00000000-0000-0000-0000-000000000000"
182 /// Maximum Length TIME = 18
183 /// "12/12/2006 12:12"
185 #define MAXIMUM_VALUE_CHARACTERS 38
188 /// Flags bitmask values use in UnicodeValueToString() and
189 /// AsciiValueToString()
191 #define LEFT_JUSTIFY 0x01
192 #define COMMA_TYPE 0x08
193 #define PREFIX_ZERO 0x20
194 #define RADIX_HEX 0x80
197 Produces a Null-terminated Unicode string in an output buffer based on
198 a Null-terminated Unicode format string and a VA_LIST argument list
200 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
202 The Unicode string is produced by parsing the format string specified by FormatString.
203 Arguments are pulled from the variable argument list specified by Marker based on the
204 contents of the format string.
205 The number of Unicode characters in the produced output buffer is returned not including
207 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
209 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
210 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
211 If BufferSize > 1 and FormatString is NULL, then ASSERT().
212 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
213 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
214 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
216 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
217 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
218 Null-terminator, then ASSERT().
220 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
222 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
223 @param FormatString Null-terminated Unicode format string.
224 @param Marker VA_LIST marker for the variable argument list.
226 @return The number of Unicode characters in the produced output buffer not including the
233 OUT CHAR16
*StartOfBuffer
,
235 IN CONST CHAR16
*FormatString
,
240 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
241 Unicode format string and variable argument list.
243 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
245 The Unicode string is produced by parsing the format string specified by FormatString.
246 Arguments are pulled from the variable argument list based on the contents of the format string.
247 The number of Unicode characters in the produced output buffer is returned not including
249 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
251 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
252 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
253 If BufferSize > 1 and FormatString is NULL, then ASSERT().
254 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
255 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
256 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
258 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
259 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
260 Null-terminator, then ASSERT().
262 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
264 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
265 @param FormatString Null-terminated Unicode format string.
266 @param ... Variable argument list whose contents are accessed based on the
267 format string specified by FormatString.
269 @return The number of Unicode characters in the produced output buffer not including the
276 OUT CHAR16
*StartOfBuffer
,
278 IN CONST CHAR16
*FormatString
,
283 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
284 ASCII format string and a VA_LIST argument list
286 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
288 The Unicode string is produced by parsing the format string specified by FormatString.
289 Arguments are pulled from the variable argument list specified by Marker based on the
290 contents of the format string.
291 The number of Unicode characters in the produced output buffer is returned not including
293 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
295 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
296 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
297 If BufferSize > 1 and FormatString is NULL, then ASSERT().
298 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
299 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
301 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
302 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
303 Null-terminator, then ASSERT().
305 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
307 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
308 @param FormatString Null-terminated ASCII format string.
309 @param Marker VA_LIST marker for the variable argument list.
311 @return The number of Unicode characters in the produced output buffer not including the
317 UnicodeVSPrintAsciiFormat (
318 OUT CHAR16
*StartOfBuffer
,
320 IN CONST CHAR8
*FormatString
,
325 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
326 ASCII format string and variable argument list.
328 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
330 The Unicode string is produced by parsing the format string specified by FormatString.
331 Arguments are pulled from the variable argument list based on the contents of the
333 The number of Unicode characters in the produced output buffer is returned not including
335 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
337 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
338 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
339 If BufferSize > 1 and FormatString is NULL, then ASSERT().
340 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
341 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
343 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
344 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
345 Null-terminator, then ASSERT().
347 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
349 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
350 @param FormatString Null-terminated ASCII format string.
351 @param ... Variable argument list whose contents are accessed based on the
352 format string specified by FormatString.
354 @return The number of Unicode characters in the produced output buffer not including the
360 UnicodeSPrintAsciiFormat (
361 OUT CHAR16
*StartOfBuffer
,
363 IN CONST CHAR8
*FormatString
,
368 Converts a decimal value to a Null-terminated Unicode string.
370 Converts the decimal number specified by Value to a Null-terminated Unicode
371 string specified by Buffer containing at most Width characters. No padding of spaces
372 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
373 The number of Unicode characters in Buffer is returned not including the Null-terminator.
374 If the conversion contains more than Width characters, then only the first
375 Width characters are returned, and the total number of characters
376 required to perform the conversion is returned.
377 Additional conversion parameters are specified in Flags.
379 The Flags bit LEFT_JUSTIFY is always ignored.
380 All conversions are left justified in Buffer.
381 If Width is 0, PREFIX_ZERO is ignored in Flags.
382 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
383 are inserted every 3rd digit starting from the right.
384 If HEX_RADIX is set in Flags, then the output buffer will be
385 formatted in hexadecimal format.
386 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
387 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
388 then Buffer is padded with '0' characters so the combination of the optional '-'
389 sign character, '0' characters, digit characters for Value, and the Null-terminator
390 add up to Width characters.
391 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
392 If Buffer is NULL, then ASSERT().
393 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
394 If unsupported bits are set in Flags, then ASSERT().
395 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
396 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
398 @param Buffer Pointer to the output buffer for the produced Null-terminated
400 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
401 @param Value The 64-bit signed value to convert to a string.
402 @param Width The maximum number of Unicode characters to place in Buffer, not including
405 @return The number of Unicode characters in Buffer not including the Null-terminator.
410 UnicodeValueToString (
411 IN OUT CHAR16
*Buffer
,
418 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
419 ASCII format string and a VA_LIST argument list.
421 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
423 The ASCII string is produced by parsing the format string specified by FormatString.
424 Arguments are pulled from the variable argument list specified by Marker based on
425 the contents of the format string.
426 The number of ASCII characters in the produced output buffer is returned not including
428 If BufferSize is 0, then no output buffer is produced and 0 is returned.
430 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
431 If BufferSize > 0 and FormatString is NULL, then ASSERT().
432 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
433 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
435 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
436 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
437 Null-terminator, then ASSERT().
439 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
441 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
442 @param FormatString Null-terminated ASCII format string.
443 @param Marker VA_LIST marker for the variable argument list.
445 @return The number of ASCII characters in the produced output buffer not including the
452 OUT CHAR8
*StartOfBuffer
,
454 IN CONST CHAR8
*FormatString
,
459 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
460 ASCII format string and variable argument list.
462 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
464 The ASCII string is produced by parsing the format string specified by FormatString.
465 Arguments are pulled from the variable argument list based on the contents of the
467 The number of ASCII characters in the produced output buffer is returned not including
469 If BufferSize is 0, then no output buffer is produced and 0 is returned.
471 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
472 If BufferSize > 0 and FormatString is NULL, then ASSERT().
473 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
474 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
476 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
477 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
478 Null-terminator, then ASSERT().
480 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
482 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
483 @param FormatString Null-terminated ASCII format string.
484 @param ... Variable argument list whose contents are accessed based on the
485 format string specified by FormatString.
487 @return The number of ASCII characters in the produced output buffer not including the
494 OUT CHAR8
*StartOfBuffer
,
496 IN CONST CHAR8
*FormatString
,
501 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
502 Unicode format string and a VA_LIST argument list.
504 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
506 The ASCII string is produced by parsing the format string specified by FormatString.
507 Arguments are pulled from the variable argument list specified by Marker based on
508 the contents of the format string.
509 The number of ASCII characters in the produced output buffer is returned not including
511 If BufferSize is 0, then no output buffer is produced and 0 is returned.
513 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
514 If BufferSize > 0 and FormatString is NULL, then ASSERT().
515 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
516 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
517 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
519 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
520 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
521 Null-terminator, then ASSERT().
523 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
525 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
526 @param FormatString Null-terminated Unicode format string.
527 @param Marker VA_LIST marker for the variable argument list.
529 @return The number of ASCII characters in the produced output buffer not including the
535 AsciiVSPrintUnicodeFormat (
536 OUT CHAR8
*StartOfBuffer
,
538 IN CONST CHAR16
*FormatString
,
543 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
544 Unicode format string and variable argument list.
546 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
548 The ASCII string is produced by parsing the format string specified by FormatString.
549 Arguments are pulled from the variable argument list based on the contents of the
551 The number of ASCII characters in the produced output buffer is returned not including
553 If BufferSize is 0, then no output buffer is produced and 0 is returned.
555 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
556 If BufferSize > 0 and FormatString is NULL, then ASSERT().
557 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
558 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
559 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
561 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
562 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
563 Null-terminator, then ASSERT().
565 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
567 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
568 @param FormatString Null-terminated Unicode format string.
569 @param ... Variable argument list whose contents are accessed based on the
570 format string specified by FormatString.
572 @return The number of ASCII characters in the produced output buffer not including the
578 AsciiSPrintUnicodeFormat (
579 OUT CHAR8
*StartOfBuffer
,
581 IN CONST CHAR16
*FormatString
,
586 Converts a decimal value to a Null-terminated ASCII string.
588 Converts the decimal number specified by Value to a Null-terminated ASCII string
589 specified by Buffer containing at most Width characters. No padding of spaces
591 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
592 The number of ASCII characters in Buffer is returned not including the Null-terminator.
593 If the conversion contains more than Width characters, then only the first Width
594 characters are returned, and the total number of characters required to perform
595 the conversion is returned.
596 Additional conversion parameters are specified in Flags.
597 The Flags bit LEFT_JUSTIFY is always ignored.
598 All conversions are left justified in Buffer.
599 If Width is 0, PREFIX_ZERO is ignored in Flags.
600 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
601 are inserted every 3rd digit starting from the right.
602 If HEX_RADIX is set in Flags, then the output buffer will be
603 formatted in hexadecimal format.
604 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
605 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
606 then Buffer is padded with '0' characters so the combination of the optional '-'
607 sign character, '0' characters, digit characters for Value, and the Null-terminator
608 add up to Width characters.
610 If Buffer is NULL, then ASSERT().
611 If unsupported bits are set in Flags, then ASSERT().
612 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
613 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
615 @param Buffer Pointer to the output buffer for the produced Null-terminated
617 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
618 @param Value The 64-bit signed value to convert to a string.
619 @param Width The maximum number of ASCII characters to place in Buffer, not including
622 @return The number of ASCII characters in Buffer not including the Null-terminator.