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