MdePkg/BaseLib: Add bit field population calculating methods
[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h
CommitLineData
ac644614 1/** @file\r
50a64e5b 2 Provides string functions, linked list functions, math functions, synchronization\r
ae591c14 3 functions, file path functions, and CPU architecture-specific functions.\r
ac644614 4\r
9095d37b 5Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
9df063a0
HT
6Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
7This program and the accompanying materials\r
50a64e5b 8are licensed and made available under the terms and conditions of the BSD License\r
9which accompanies this distribution. The full text of the license may be found at\r
af2dc6a7 10http://opensource.org/licenses/bsd-license.php.\r
ac644614 11\r
50a64e5b 12THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
13WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
ac644614 14\r
15**/\r
16\r
17#ifndef __BASE_LIB__\r
18#define __BASE_LIB__\r
19\r
1106ffe1 20//\r
1a2f870c 21// Definitions for architecture-specific types\r
1106ffe1 22//\r
ac644614 23#if defined (MDE_CPU_IA32)\r
fc30687f 24///\r
af2dc6a7 25/// The IA-32 architecture context buffer used by SetJump() and LongJump().\r
fc30687f 26///\r
ac644614 27typedef struct {\r
28 UINT32 Ebx;\r
29 UINT32 Esi;\r
30 UINT32 Edi;\r
31 UINT32 Ebp;\r
32 UINT32 Esp;\r
33 UINT32 Eip;\r
34} BASE_LIBRARY_JUMP_BUFFER;\r
35\r
36#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4\r
37\r
aa4df547 38#endif // defined (MDE_CPU_IA32)\r
39\r
40#if defined (MDE_CPU_IPF)\r
ac644614 41\r
fc30687f 42///\r
af2dc6a7 43/// The Itanium architecture context buffer used by SetJump() and LongJump().\r
fc30687f 44///\r
ac644614 45typedef struct {\r
46 UINT64 F2[2];\r
47 UINT64 F3[2];\r
48 UINT64 F4[2];\r
49 UINT64 F5[2];\r
50 UINT64 F16[2];\r
51 UINT64 F17[2];\r
52 UINT64 F18[2];\r
53 UINT64 F19[2];\r
54 UINT64 F20[2];\r
55 UINT64 F21[2];\r
56 UINT64 F22[2];\r
57 UINT64 F23[2];\r
58 UINT64 F24[2];\r
59 UINT64 F25[2];\r
60 UINT64 F26[2];\r
61 UINT64 F27[2];\r
62 UINT64 F28[2];\r
63 UINT64 F29[2];\r
64 UINT64 F30[2];\r
65 UINT64 F31[2];\r
66 UINT64 R4;\r
67 UINT64 R5;\r
68 UINT64 R6;\r
69 UINT64 R7;\r
70 UINT64 SP;\r
71 UINT64 BR0;\r
72 UINT64 BR1;\r
73 UINT64 BR2;\r
74 UINT64 BR3;\r
75 UINT64 BR4;\r
76 UINT64 BR5;\r
77 UINT64 InitialUNAT;\r
78 UINT64 AfterSpillUNAT;\r
79 UINT64 PFS;\r
80 UINT64 BSP;\r
81 UINT64 Predicates;\r
82 UINT64 LoopCount;\r
83 UINT64 FPSR;\r
84} BASE_LIBRARY_JUMP_BUFFER;\r
85\r
86#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10\r
87\r
aa4df547 88#endif // defined (MDE_CPU_IPF)\r
89\r
90#if defined (MDE_CPU_X64)\r
fc30687f 91///\r
af2dc6a7 92/// The x64 architecture context buffer used by SetJump() and LongJump().\r
fc30687f 93///\r
ac644614 94typedef struct {\r
95 UINT64 Rbx;\r
96 UINT64 Rsp;\r
97 UINT64 Rbp;\r
98 UINT64 Rdi;\r
99 UINT64 Rsi;\r
100 UINT64 R12;\r
101 UINT64 R13;\r
102 UINT64 R14;\r
103 UINT64 R15;\r
104 UINT64 Rip;\r
9b9641c6 105 UINT64 MxCsr;\r
af2dc6a7 106 UINT8 XmmBuffer[160]; ///< XMM6-XMM15.\r
ac644614 107} BASE_LIBRARY_JUMP_BUFFER;\r
108\r
109#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8\r
110\r
aa4df547 111#endif // defined (MDE_CPU_X64)\r
112\r
113#if defined (MDE_CPU_EBC)\r
fc30687f 114///\r
af2dc6a7 115/// The EBC context buffer used by SetJump() and LongJump().\r
fc30687f 116///\r
ac644614 117typedef struct {\r
118 UINT64 R0;\r
119 UINT64 R1;\r
120 UINT64 R2;\r
121 UINT64 R3;\r
122 UINT64 IP;\r
123} BASE_LIBRARY_JUMP_BUFFER;\r
124\r
125#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8\r
126\r
aa4df547 127#endif // defined (MDE_CPU_EBC)\r
ac644614 128\r
ebd04fc2 129#if defined (MDE_CPU_ARM)\r
130\r
131typedef struct {\r
af2dc6a7 132 UINT32 R3; ///< A copy of R13.\r
01a54966 133 UINT32 R4;\r
134 UINT32 R5;\r
135 UINT32 R6;\r
136 UINT32 R7;\r
137 UINT32 R8;\r
138 UINT32 R9;\r
139 UINT32 R10;\r
140 UINT32 R11;\r
141 UINT32 R12;\r
142 UINT32 R14;\r
ebd04fc2 143} BASE_LIBRARY_JUMP_BUFFER;\r
144\r
145#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4\r
146\r
147#endif // defined (MDE_CPU_ARM)\r
148\r
807e2604
HL
149#if defined (MDE_CPU_AARCH64)\r
150typedef struct {\r
151 // GP regs\r
152 UINT64 X19;\r
153 UINT64 X20;\r
154 UINT64 X21;\r
155 UINT64 X22;\r
156 UINT64 X23;\r
157 UINT64 X24;\r
158 UINT64 X25;\r
159 UINT64 X26;\r
160 UINT64 X27;\r
161 UINT64 X28;\r
162 UINT64 FP;\r
163 UINT64 LR;\r
164 UINT64 IP0;\r
165\r
166 // FP regs\r
167 UINT64 D8;\r
168 UINT64 D9;\r
169 UINT64 D10;\r
170 UINT64 D11;\r
171 UINT64 D12;\r
172 UINT64 D13;\r
173 UINT64 D14;\r
174 UINT64 D15;\r
175} BASE_LIBRARY_JUMP_BUFFER;\r
176\r
177#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8\r
178\r
179#endif // defined (MDE_CPU_AARCH64)\r
180\r
181\r
ac644614 182//\r
183// String Services\r
184//\r
185\r
c058d59f
JY
186\r
187/**\r
188 Returns the length of a Null-terminated Unicode string.\r
189\r
328f84b1
JY
190 This function is similar as strlen_s defined in C11.\r
191\r
c058d59f
JY
192 If String is not aligned on a 16-bit boundary, then ASSERT().\r
193\r
194 @param String A pointer to a Null-terminated Unicode string.\r
195 @param MaxSize The maximum number of Destination Unicode\r
196 char, including terminating null char.\r
197\r
198 @retval 0 If String is NULL.\r
199 @retval MaxSize If there is no null character in the first MaxSize characters of String.\r
200 @return The number of characters that percede the terminating null character.\r
201\r
202**/\r
203UINTN\r
204EFIAPI\r
205StrnLenS (\r
206 IN CONST CHAR16 *String,\r
207 IN UINTN MaxSize\r
208 );\r
209\r
b590e43a
HW
210/**\r
211 Returns the size of a Null-terminated Unicode string in bytes, including the\r
212 Null terminator.\r
213\r
214 This function returns the size of the Null-terminated Unicode string\r
215 specified by String in bytes, including the Null terminator.\r
216\r
217 If String is not aligned on a 16-bit boundary, then ASSERT().\r
218\r
219 @param String A pointer to a Null-terminated Unicode string.\r
220 @param MaxSize The maximum number of Destination Unicode\r
221 char, including the Null terminator.\r
222\r
223 @retval 0 If String is NULL.\r
224 @retval (sizeof (CHAR16) * (MaxSize + 1))\r
225 If there is no Null terminator in the first MaxSize characters of\r
226 String.\r
227 @return The size of the Null-terminated Unicode string in bytes, including\r
228 the Null terminator.\r
229\r
230**/\r
231UINTN\r
232EFIAPI\r
233StrnSizeS (\r
234 IN CONST CHAR16 *String,\r
235 IN UINTN MaxSize\r
236 );\r
237\r
c058d59f
JY
238/**\r
239 Copies the string pointed to by Source (including the terminating null char)\r
240 to the array pointed to by Destination.\r
241\r
328f84b1
JY
242 This function is similar as strcpy_s defined in C11.\r
243\r
c058d59f
JY
244 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
245 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
0e93edbb 246 If an error would be returned, then the function will also ASSERT().\r
c058d59f 247\r
328f84b1
JY
248 If an error is returned, then the Destination is unmodified.\r
249\r
c058d59f
JY
250 @param Destination A pointer to a Null-terminated Unicode string.\r
251 @param DestMax The maximum number of Destination Unicode\r
252 char, including terminating null char.\r
253 @param Source A pointer to a Null-terminated Unicode string.\r
254\r
255 @retval RETURN_SUCCESS String is copied.\r
256 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
257 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
258 If Source is NULL.\r
259 If PcdMaximumUnicodeStringLength is not zero,\r
9095d37b 260 and DestMax is greater than\r
c058d59f
JY
261 PcdMaximumUnicodeStringLength.\r
262 If DestMax is 0.\r
263 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
264**/\r
265RETURN_STATUS\r
266EFIAPI\r
267StrCpyS (\r
268 OUT CHAR16 *Destination,\r
269 IN UINTN DestMax,\r
270 IN CONST CHAR16 *Source\r
271 );\r
272\r
273/**\r
274 Copies not more than Length successive char from the string pointed to by\r
275 Source to the array pointed to by Destination. If no null char is copied from\r
276 Source, then Destination[Length] is always set to null.\r
277\r
328f84b1
JY
278 This function is similar as strncpy_s defined in C11.\r
279\r
c058d59f
JY
280 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().\r
281 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
0e93edbb 282 If an error would be returned, then the function will also ASSERT().\r
c058d59f 283\r
328f84b1
JY
284 If an error is returned, then the Destination is unmodified.\r
285\r
c058d59f
JY
286 @param Destination A pointer to a Null-terminated Unicode string.\r
287 @param DestMax The maximum number of Destination Unicode\r
288 char, including terminating null char.\r
289 @param Source A pointer to a Null-terminated Unicode string.\r
290 @param Length The maximum number of Unicode characters to copy.\r
291\r
292 @retval RETURN_SUCCESS String is copied.\r
9095d37b 293 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than\r
c058d59f
JY
294 MIN(StrLen(Source), Length).\r
295 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
296 If Source is NULL.\r
297 If PcdMaximumUnicodeStringLength is not zero,\r
9095d37b 298 and DestMax is greater than\r
c058d59f
JY
299 PcdMaximumUnicodeStringLength.\r
300 If DestMax is 0.\r
301 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
302**/\r
303RETURN_STATUS\r
304EFIAPI\r
305StrnCpyS (\r
306 OUT CHAR16 *Destination,\r
307 IN UINTN DestMax,\r
308 IN CONST CHAR16 *Source,\r
309 IN UINTN Length\r
310 );\r
311\r
312/**\r
313 Appends a copy of the string pointed to by Source (including the terminating\r
314 null char) to the end of the string pointed to by Destination.\r
315\r
328f84b1
JY
316 This function is similar as strcat_s defined in C11.\r
317\r
c058d59f
JY
318 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
319 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
0e93edbb 320 If an error would be returned, then the function will also ASSERT().\r
c058d59f 321\r
328f84b1
JY
322 If an error is returned, then the Destination is unmodified.\r
323\r
c058d59f
JY
324 @param Destination A pointer to a Null-terminated Unicode string.\r
325 @param DestMax The maximum number of Destination Unicode\r
326 char, including terminating null char.\r
327 @param Source A pointer to a Null-terminated Unicode string.\r
328\r
329 @retval RETURN_SUCCESS String is appended.\r
9095d37b 330 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
c058d59f
JY
331 StrLen(Destination).\r
332 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
333 greater than StrLen(Source).\r
334 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
335 If Source is NULL.\r
336 If PcdMaximumUnicodeStringLength is not zero,\r
9095d37b 337 and DestMax is greater than\r
c058d59f
JY
338 PcdMaximumUnicodeStringLength.\r
339 If DestMax is 0.\r
340 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
341**/\r
342RETURN_STATUS\r
343EFIAPI\r
344StrCatS (\r
345 IN OUT CHAR16 *Destination,\r
346 IN UINTN DestMax,\r
347 IN CONST CHAR16 *Source\r
348 );\r
349\r
350/**\r
351 Appends not more than Length successive char from the string pointed to by\r
352 Source to the end of the string pointed to by Destination. If no null char is\r
353 copied from Source, then Destination[StrLen(Destination) + Length] is always\r
354 set to null.\r
355\r
328f84b1
JY
356 This function is similar as strncat_s defined in C11.\r
357\r
c058d59f 358 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
0e93edbb
JY
359 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
360 If an error would be returned, then the function will also ASSERT().\r
c058d59f 361\r
328f84b1
JY
362 If an error is returned, then the Destination is unmodified.\r
363\r
c058d59f
JY
364 @param Destination A pointer to a Null-terminated Unicode string.\r
365 @param DestMax The maximum number of Destination Unicode\r
366 char, including terminating null char.\r
367 @param Source A pointer to a Null-terminated Unicode string.\r
368 @param Length The maximum number of Unicode characters to copy.\r
369\r
370 @retval RETURN_SUCCESS String is appended.\r
371 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
372 StrLen(Destination).\r
373 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
374 greater than MIN(StrLen(Source), Length).\r
375 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
376 If Source is NULL.\r
377 If PcdMaximumUnicodeStringLength is not zero,\r
9095d37b 378 and DestMax is greater than\r
c058d59f
JY
379 PcdMaximumUnicodeStringLength.\r
380 If DestMax is 0.\r
381 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
382**/\r
383RETURN_STATUS\r
384EFIAPI\r
385StrnCatS (\r
386 IN OUT CHAR16 *Destination,\r
387 IN UINTN DestMax,\r
388 IN CONST CHAR16 *Source,\r
389 IN UINTN Length\r
390 );\r
391\r
d8af3301
HW
392/**\r
393 Convert a Null-terminated Unicode decimal string to a value of type UINTN.\r
394\r
395 This function outputs a value of type UINTN by interpreting the contents of\r
396 the Unicode string specified by String as a decimal number. The format of the\r
397 input Unicode string String is:\r
398\r
399 [spaces] [decimal digits].\r
400\r
401 The valid decimal digit character is in the range [0-9]. The function will\r
402 ignore the pad space, which includes spaces or tab characters, before\r
403 [decimal digits]. The running zero in the beginning of [decimal digits] will\r
404 be ignored. Then, the function stops at the first character that is a not a\r
405 valid decimal character or a Null-terminator, whichever one comes first.\r
406\r
407 If String is NULL, then ASSERT().\r
408 If Data is NULL, then ASSERT().\r
409 If String is not aligned in a 16-bit boundary, then ASSERT().\r
410 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
411 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
412 Null-terminator, then ASSERT().\r
413\r
414 If String has no valid decimal digits in the above format, then 0 is stored\r
415 at the location pointed to by Data.\r
416 If the number represented by String exceeds the range defined by UINTN, then\r
417 MAX_UINTN is stored at the location pointed to by Data.\r
418\r
419 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
420 is stored at the location pointed to by EndPointer. If String has no valid\r
421 decimal digits right after the optional pad spaces, the value of String is\r
422 stored at the location pointed to by EndPointer.\r
423\r
424 @param String Pointer to a Null-terminated Unicode string.\r
425 @param EndPointer Pointer to character that stops scan.\r
426 @param Data Pointer to the converted value.\r
427\r
428 @retval RETURN_SUCCESS Value is translated from String.\r
429 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
430 If Data is NULL.\r
431 If PcdMaximumUnicodeStringLength is not\r
432 zero, and String contains more than\r
433 PcdMaximumUnicodeStringLength Unicode\r
434 characters, not including the\r
435 Null-terminator.\r
436 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
437 the range defined by UINTN.\r
438\r
439**/\r
440RETURN_STATUS\r
441EFIAPI\r
442StrDecimalToUintnS (\r
443 IN CONST CHAR16 *String,\r
444 OUT CHAR16 **EndPointer, OPTIONAL\r
445 OUT UINTN *Data\r
446 );\r
447\r
448/**\r
449 Convert a Null-terminated Unicode decimal string to a value of type UINT64.\r
450\r
451 This function outputs a value of type UINT64 by interpreting the contents of\r
452 the Unicode string specified by String as a decimal number. The format of the\r
453 input Unicode string String is:\r
454\r
455 [spaces] [decimal digits].\r
456\r
457 The valid decimal digit character is in the range [0-9]. The function will\r
458 ignore the pad space, which includes spaces or tab characters, before\r
459 [decimal digits]. The running zero in the beginning of [decimal digits] will\r
460 be ignored. Then, the function stops at the first character that is a not a\r
461 valid decimal character or a Null-terminator, whichever one comes first.\r
462\r
463 If String is NULL, then ASSERT().\r
464 If Data is NULL, then ASSERT().\r
465 If String is not aligned in a 16-bit boundary, then ASSERT().\r
466 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
467 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
468 Null-terminator, then ASSERT().\r
469\r
470 If String has no valid decimal digits in the above format, then 0 is stored\r
471 at the location pointed to by Data.\r
472 If the number represented by String exceeds the range defined by UINT64, then\r
473 MAX_UINT64 is stored at the location pointed to by Data.\r
474\r
475 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
476 is stored at the location pointed to by EndPointer. If String has no valid\r
477 decimal digits right after the optional pad spaces, the value of String is\r
478 stored at the location pointed to by EndPointer.\r
479\r
480 @param String Pointer to a Null-terminated Unicode string.\r
481 @param EndPointer Pointer to character that stops scan.\r
482 @param Data Pointer to the converted value.\r
483\r
484 @retval RETURN_SUCCESS Value is translated from String.\r
485 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
486 If Data is NULL.\r
487 If PcdMaximumUnicodeStringLength is not\r
488 zero, and String contains more than\r
489 PcdMaximumUnicodeStringLength Unicode\r
490 characters, not including the\r
491 Null-terminator.\r
492 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
493 the range defined by UINT64.\r
494\r
495**/\r
496RETURN_STATUS\r
497EFIAPI\r
498StrDecimalToUint64S (\r
499 IN CONST CHAR16 *String,\r
500 OUT CHAR16 **EndPointer, OPTIONAL\r
501 OUT UINT64 *Data\r
502 );\r
503\r
504/**\r
505 Convert a Null-terminated Unicode hexadecimal string to a value of type\r
506 UINTN.\r
507\r
508 This function outputs a value of type UINTN by interpreting the contents of\r
509 the Unicode string specified by String as a hexadecimal number. The format of\r
510 the input Unicode string String is:\r
511\r
512 [spaces][zeros][x][hexadecimal digits].\r
513\r
514 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
515 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.\r
516 If "x" appears in the input string, it must be prefixed with at least one 0.\r
517 The function will ignore the pad space, which includes spaces or tab\r
518 characters, before [zeros], [x] or [hexadecimal digit]. The running zero\r
519 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts\r
520 after [x] or the first valid hexadecimal digit. Then, the function stops at\r
521 the first character that is a not a valid hexadecimal character or NULL,\r
522 whichever one comes first.\r
523\r
524 If String is NULL, then ASSERT().\r
525 If Data is NULL, then ASSERT().\r
526 If String is not aligned in a 16-bit boundary, then ASSERT().\r
527 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
528 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
529 Null-terminator, then ASSERT().\r
530\r
531 If String has no valid hexadecimal digits in the above format, then 0 is\r
532 stored at the location pointed to by Data.\r
533 If the number represented by String exceeds the range defined by UINTN, then\r
534 MAX_UINTN is stored at the location pointed to by Data.\r
535\r
536 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
537 is stored at the location pointed to by EndPointer. If String has no valid\r
538 hexadecimal digits right after the optional pad spaces, the value of String\r
539 is stored at the location pointed to by EndPointer.\r
540\r
541 @param String Pointer to a Null-terminated Unicode string.\r
542 @param EndPointer Pointer to character that stops scan.\r
543 @param Data Pointer to the converted value.\r
544\r
545 @retval RETURN_SUCCESS Value is translated from String.\r
546 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
547 If Data is NULL.\r
548 If PcdMaximumUnicodeStringLength is not\r
549 zero, and String contains more than\r
550 PcdMaximumUnicodeStringLength Unicode\r
551 characters, not including the\r
552 Null-terminator.\r
553 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
554 the range defined by UINTN.\r
555\r
556**/\r
557RETURN_STATUS\r
558EFIAPI\r
559StrHexToUintnS (\r
560 IN CONST CHAR16 *String,\r
561 OUT CHAR16 **EndPointer, OPTIONAL\r
562 OUT UINTN *Data\r
563 );\r
564\r
565/**\r
566 Convert a Null-terminated Unicode hexadecimal string to a value of type\r
567 UINT64.\r
568\r
569 This function outputs a value of type UINT64 by interpreting the contents of\r
570 the Unicode string specified by String as a hexadecimal number. The format of\r
571 the input Unicode string String is:\r
572\r
573 [spaces][zeros][x][hexadecimal digits].\r
574\r
575 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
576 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.\r
577 If "x" appears in the input string, it must be prefixed with at least one 0.\r
578 The function will ignore the pad space, which includes spaces or tab\r
579 characters, before [zeros], [x] or [hexadecimal digit]. The running zero\r
580 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts\r
581 after [x] or the first valid hexadecimal digit. Then, the function stops at\r
582 the first character that is a not a valid hexadecimal character or NULL,\r
583 whichever one comes first.\r
584\r
585 If String is NULL, then ASSERT().\r
586 If Data is NULL, then ASSERT().\r
587 If String is not aligned in a 16-bit boundary, then ASSERT().\r
588 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
589 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
590 Null-terminator, then ASSERT().\r
591\r
592 If String has no valid hexadecimal digits in the above format, then 0 is\r
593 stored at the location pointed to by Data.\r
594 If the number represented by String exceeds the range defined by UINT64, then\r
595 MAX_UINT64 is stored at the location pointed to by Data.\r
596\r
597 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
598 is stored at the location pointed to by EndPointer. If String has no valid\r
599 hexadecimal digits right after the optional pad spaces, the value of String\r
600 is stored at the location pointed to by EndPointer.\r
601\r
602 @param String Pointer to a Null-terminated Unicode string.\r
603 @param EndPointer Pointer to character that stops scan.\r
604 @param Data Pointer to the converted value.\r
605\r
606 @retval RETURN_SUCCESS Value is translated from String.\r
607 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
608 If Data is NULL.\r
609 If PcdMaximumUnicodeStringLength is not\r
610 zero, and String contains more than\r
611 PcdMaximumUnicodeStringLength Unicode\r
612 characters, not including the\r
613 Null-terminator.\r
614 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
615 the range defined by UINT64.\r
616\r
617**/\r
618RETURN_STATUS\r
619EFIAPI\r
620StrHexToUint64S (\r
621 IN CONST CHAR16 *String,\r
622 OUT CHAR16 **EndPointer, OPTIONAL\r
623 OUT UINT64 *Data\r
624 );\r
625\r
c058d59f
JY
626/**\r
627 Returns the length of a Null-terminated Ascii string.\r
628\r
328f84b1
JY
629 This function is similar as strlen_s defined in C11.\r
630\r
c058d59f
JY
631 @param String A pointer to a Null-terminated Ascii string.\r
632 @param MaxSize The maximum number of Destination Ascii\r
633 char, including terminating null char.\r
634\r
635 @retval 0 If String is NULL.\r
636 @retval MaxSize If there is no null character in the first MaxSize characters of String.\r
637 @return The number of characters that percede the terminating null character.\r
638\r
639**/\r
640UINTN\r
641EFIAPI\r
642AsciiStrnLenS (\r
643 IN CONST CHAR8 *String,\r
644 IN UINTN MaxSize\r
645 );\r
646\r
b590e43a
HW
647/**\r
648 Returns the size of a Null-terminated Ascii string in bytes, including the\r
649 Null terminator.\r
650\r
651 This function returns the size of the Null-terminated Ascii string specified\r
652 by String in bytes, including the Null terminator.\r
653\r
654 @param String A pointer to a Null-terminated Ascii string.\r
655 @param MaxSize The maximum number of Destination Ascii\r
656 char, including the Null terminator.\r
657\r
658 @retval 0 If String is NULL.\r
659 @retval (sizeof (CHAR8) * (MaxSize + 1))\r
660 If there is no Null terminator in the first MaxSize characters of\r
661 String.\r
662 @return The size of the Null-terminated Ascii string in bytes, including the\r
663 Null terminator.\r
664\r
665**/\r
666UINTN\r
667EFIAPI\r
668AsciiStrnSizeS (\r
669 IN CONST CHAR8 *String,\r
670 IN UINTN MaxSize\r
671 );\r
672\r
c058d59f
JY
673/**\r
674 Copies the string pointed to by Source (including the terminating null char)\r
675 to the array pointed to by Destination.\r
676\r
328f84b1
JY
677 This function is similar as strcpy_s defined in C11.\r
678\r
0e93edbb
JY
679 If an error would be returned, then the function will also ASSERT().\r
680\r
328f84b1
JY
681 If an error is returned, then the Destination is unmodified.\r
682\r
c058d59f
JY
683 @param Destination A pointer to a Null-terminated Ascii string.\r
684 @param DestMax The maximum number of Destination Ascii\r
685 char, including terminating null char.\r
686 @param Source A pointer to a Null-terminated Ascii string.\r
687\r
688 @retval RETURN_SUCCESS String is copied.\r
689 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
690 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
691 If Source is NULL.\r
692 If PcdMaximumAsciiStringLength is not zero,\r
9095d37b 693 and DestMax is greater than\r
c058d59f
JY
694 PcdMaximumAsciiStringLength.\r
695 If DestMax is 0.\r
696 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
697**/\r
698RETURN_STATUS\r
699EFIAPI\r
700AsciiStrCpyS (\r
701 OUT CHAR8 *Destination,\r
702 IN UINTN DestMax,\r
703 IN CONST CHAR8 *Source\r
704 );\r
705\r
706/**\r
707 Copies not more than Length successive char from the string pointed to by\r
708 Source to the array pointed to by Destination. If no null char is copied from\r
709 Source, then Destination[Length] is always set to null.\r
710\r
328f84b1
JY
711 This function is similar as strncpy_s defined in C11.\r
712\r
0e93edbb
JY
713 If an error would be returned, then the function will also ASSERT().\r
714\r
328f84b1
JY
715 If an error is returned, then the Destination is unmodified.\r
716\r
c058d59f
JY
717 @param Destination A pointer to a Null-terminated Ascii string.\r
718 @param DestMax The maximum number of Destination Ascii\r
719 char, including terminating null char.\r
720 @param Source A pointer to a Null-terminated Ascii string.\r
721 @param Length The maximum number of Ascii characters to copy.\r
722\r
723 @retval RETURN_SUCCESS String is copied.\r
9095d37b 724 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than\r
c058d59f
JY
725 MIN(StrLen(Source), Length).\r
726 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
727 If Source is NULL.\r
728 If PcdMaximumAsciiStringLength is not zero,\r
9095d37b 729 and DestMax is greater than\r
c058d59f
JY
730 PcdMaximumAsciiStringLength.\r
731 If DestMax is 0.\r
732 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
733**/\r
734RETURN_STATUS\r
735EFIAPI\r
736AsciiStrnCpyS (\r
737 OUT CHAR8 *Destination,\r
738 IN UINTN DestMax,\r
739 IN CONST CHAR8 *Source,\r
740 IN UINTN Length\r
741 );\r
742\r
743/**\r
744 Appends a copy of the string pointed to by Source (including the terminating\r
745 null char) to the end of the string pointed to by Destination.\r
746\r
328f84b1
JY
747 This function is similar as strcat_s defined in C11.\r
748\r
0e93edbb
JY
749 If an error would be returned, then the function will also ASSERT().\r
750\r
328f84b1
JY
751 If an error is returned, then the Destination is unmodified.\r
752\r
c058d59f
JY
753 @param Destination A pointer to a Null-terminated Ascii string.\r
754 @param DestMax The maximum number of Destination Ascii\r
755 char, including terminating null char.\r
756 @param Source A pointer to a Null-terminated Ascii string.\r
757\r
758 @retval RETURN_SUCCESS String is appended.\r
9095d37b 759 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
c058d59f
JY
760 StrLen(Destination).\r
761 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
762 greater than StrLen(Source).\r
763 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
764 If Source is NULL.\r
765 If PcdMaximumAsciiStringLength is not zero,\r
9095d37b 766 and DestMax is greater than\r
c058d59f
JY
767 PcdMaximumAsciiStringLength.\r
768 If DestMax is 0.\r
769 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
770**/\r
771RETURN_STATUS\r
772EFIAPI\r
773AsciiStrCatS (\r
774 IN OUT CHAR8 *Destination,\r
775 IN UINTN DestMax,\r
776 IN CONST CHAR8 *Source\r
777 );\r
778\r
779/**\r
780 Appends not more than Length successive char from the string pointed to by\r
781 Source to the end of the string pointed to by Destination. If no null char is\r
782 copied from Source, then Destination[StrLen(Destination) + Length] is always\r
783 set to null.\r
784\r
328f84b1
JY
785 This function is similar as strncat_s defined in C11.\r
786\r
0e93edbb
JY
787 If an error would be returned, then the function will also ASSERT().\r
788\r
328f84b1
JY
789 If an error is returned, then the Destination is unmodified.\r
790\r
c058d59f
JY
791 @param Destination A pointer to a Null-terminated Ascii string.\r
792 @param DestMax The maximum number of Destination Ascii\r
793 char, including terminating null char.\r
794 @param Source A pointer to a Null-terminated Ascii string.\r
795 @param Length The maximum number of Ascii characters to copy.\r
796\r
797 @retval RETURN_SUCCESS String is appended.\r
798 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
799 StrLen(Destination).\r
800 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
801 greater than MIN(StrLen(Source), Length).\r
802 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
803 If Source is NULL.\r
804 If PcdMaximumAsciiStringLength is not zero,\r
9095d37b 805 and DestMax is greater than\r
c058d59f
JY
806 PcdMaximumAsciiStringLength.\r
807 If DestMax is 0.\r
808 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
809**/\r
810RETURN_STATUS\r
811EFIAPI\r
812AsciiStrnCatS (\r
813 IN OUT CHAR8 *Destination,\r
814 IN UINTN DestMax,\r
815 IN CONST CHAR8 *Source,\r
816 IN UINTN Length\r
817 );\r
818\r
d8af3301
HW
819/**\r
820 Convert a Null-terminated Ascii decimal string to a value of type UINTN.\r
821\r
822 This function outputs a value of type UINTN by interpreting the contents of\r
823 the Ascii string specified by String as a decimal number. The format of the\r
824 input Ascii string String is:\r
825\r
826 [spaces] [decimal digits].\r
827\r
828 The valid decimal digit character is in the range [0-9]. The function will\r
829 ignore the pad space, which includes spaces or tab characters, before\r
830 [decimal digits]. The running zero in the beginning of [decimal digits] will\r
831 be ignored. Then, the function stops at the first character that is a not a\r
832 valid decimal character or a Null-terminator, whichever one comes first.\r
833\r
834 If String is NULL, then ASSERT().\r
835 If Data is NULL, then ASSERT().\r
836 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
837 PcdMaximumAsciiStringLength Ascii characters, not including the\r
838 Null-terminator, then ASSERT().\r
839\r
840 If String has no valid decimal digits in the above format, then 0 is stored\r
841 at the location pointed to by Data.\r
842 If the number represented by String exceeds the range defined by UINTN, then\r
843 MAX_UINTN is stored at the location pointed to by Data.\r
844\r
845 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
846 is stored at the location pointed to by EndPointer. If String has no valid\r
847 decimal digits right after the optional pad spaces, the value of String is\r
848 stored at the location pointed to by EndPointer.\r
849\r
850 @param String Pointer to a Null-terminated Ascii string.\r
851 @param EndPointer Pointer to character that stops scan.\r
852 @param Data Pointer to the converted value.\r
853\r
854 @retval RETURN_SUCCESS Value is translated from String.\r
855 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
856 If Data is NULL.\r
857 If PcdMaximumAsciiStringLength is not zero,\r
858 and String contains more than\r
859 PcdMaximumAsciiStringLength Ascii\r
860 characters, not including the\r
861 Null-terminator.\r
862 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
863 the range defined by UINTN.\r
864\r
865**/\r
866RETURN_STATUS\r
867EFIAPI\r
868AsciiStrDecimalToUintnS (\r
869 IN CONST CHAR8 *String,\r
870 OUT CHAR8 **EndPointer, OPTIONAL\r
871 OUT UINTN *Data\r
872 );\r
873\r
874/**\r
875 Convert a Null-terminated Ascii decimal string to a value of type UINT64.\r
876\r
877 This function outputs a value of type UINT64 by interpreting the contents of\r
878 the Ascii string specified by String as a decimal number. The format of the\r
879 input Ascii string String is:\r
880\r
881 [spaces] [decimal digits].\r
882\r
883 The valid decimal digit character is in the range [0-9]. The function will\r
884 ignore the pad space, which includes spaces or tab characters, before\r
885 [decimal digits]. The running zero in the beginning of [decimal digits] will\r
886 be ignored. Then, the function stops at the first character that is a not a\r
887 valid decimal character or a Null-terminator, whichever one comes first.\r
888\r
889 If String is NULL, then ASSERT().\r
890 If Data is NULL, then ASSERT().\r
891 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
892 PcdMaximumAsciiStringLength Ascii characters, not including the\r
893 Null-terminator, then ASSERT().\r
894\r
895 If String has no valid decimal digits in the above format, then 0 is stored\r
896 at the location pointed to by Data.\r
897 If the number represented by String exceeds the range defined by UINT64, then\r
898 MAX_UINT64 is stored at the location pointed to by Data.\r
899\r
900 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
901 is stored at the location pointed to by EndPointer. If String has no valid\r
902 decimal digits right after the optional pad spaces, the value of String is\r
903 stored at the location pointed to by EndPointer.\r
904\r
905 @param String Pointer to a Null-terminated Ascii string.\r
906 @param EndPointer Pointer to character that stops scan.\r
907 @param Data Pointer to the converted value.\r
908\r
909 @retval RETURN_SUCCESS Value is translated from String.\r
910 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
911 If Data is NULL.\r
912 If PcdMaximumAsciiStringLength is not zero,\r
913 and String contains more than\r
914 PcdMaximumAsciiStringLength Ascii\r
915 characters, not including the\r
916 Null-terminator.\r
917 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
918 the range defined by UINT64.\r
919\r
920**/\r
921RETURN_STATUS\r
922EFIAPI\r
923AsciiStrDecimalToUint64S (\r
924 IN CONST CHAR8 *String,\r
925 OUT CHAR8 **EndPointer, OPTIONAL\r
926 OUT UINT64 *Data\r
927 );\r
928\r
929/**\r
930 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.\r
931\r
932 This function outputs a value of type UINTN by interpreting the contents of\r
933 the Ascii string specified by String as a hexadecimal number. The format of\r
934 the input Ascii string String is:\r
935\r
936 [spaces][zeros][x][hexadecimal digits].\r
937\r
938 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
939 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If\r
940 "x" appears in the input string, it must be prefixed with at least one 0. The\r
941 function will ignore the pad space, which includes spaces or tab characters,\r
942 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or\r
943 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or\r
944 the first valid hexadecimal digit. Then, the function stops at the first\r
945 character that is a not a valid hexadecimal character or Null-terminator,\r
946 whichever on comes first.\r
947\r
948 If String is NULL, then ASSERT().\r
949 If Data is NULL, then ASSERT().\r
950 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
951 PcdMaximumAsciiStringLength Ascii characters, not including the\r
952 Null-terminator, then ASSERT().\r
953\r
954 If String has no valid hexadecimal digits in the above format, then 0 is\r
955 stored at the location pointed to by Data.\r
956 If the number represented by String exceeds the range defined by UINTN, then\r
957 MAX_UINTN is stored at the location pointed to by Data.\r
958\r
959 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
960 is stored at the location pointed to by EndPointer. If String has no valid\r
961 hexadecimal digits right after the optional pad spaces, the value of String\r
962 is stored at the location pointed to by EndPointer.\r
963\r
964 @param String Pointer to a Null-terminated Ascii string.\r
965 @param EndPointer Pointer to character that stops scan.\r
966 @param Data Pointer to the converted value.\r
967\r
968 @retval RETURN_SUCCESS Value is translated from String.\r
969 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
970 If Data is NULL.\r
971 If PcdMaximumAsciiStringLength is not zero,\r
972 and String contains more than\r
973 PcdMaximumAsciiStringLength Ascii\r
974 characters, not including the\r
975 Null-terminator.\r
976 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
977 the range defined by UINTN.\r
978\r
979**/\r
980RETURN_STATUS\r
981EFIAPI\r
982AsciiStrHexToUintnS (\r
983 IN CONST CHAR8 *String,\r
984 OUT CHAR8 **EndPointer, OPTIONAL\r
985 OUT UINTN *Data\r
986 );\r
987\r
988/**\r
989 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.\r
990\r
991 This function outputs a value of type UINT64 by interpreting the contents of\r
992 the Ascii string specified by String as a hexadecimal number. The format of\r
993 the input Ascii string String is:\r
994\r
995 [spaces][zeros][x][hexadecimal digits].\r
996\r
997 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
998 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If\r
999 "x" appears in the input string, it must be prefixed with at least one 0. The\r
1000 function will ignore the pad space, which includes spaces or tab characters,\r
1001 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or\r
1002 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or\r
1003 the first valid hexadecimal digit. Then, the function stops at the first\r
1004 character that is a not a valid hexadecimal character or Null-terminator,\r
1005 whichever on comes first.\r
1006\r
1007 If String is NULL, then ASSERT().\r
1008 If Data is NULL, then ASSERT().\r
1009 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
1010 PcdMaximumAsciiStringLength Ascii characters, not including the\r
1011 Null-terminator, then ASSERT().\r
1012\r
1013 If String has no valid hexadecimal digits in the above format, then 0 is\r
1014 stored at the location pointed to by Data.\r
1015 If the number represented by String exceeds the range defined by UINT64, then\r
1016 MAX_UINT64 is stored at the location pointed to by Data.\r
1017\r
1018 If EndPointer is not NULL, a pointer to the character that stopped the scan\r
1019 is stored at the location pointed to by EndPointer. If String has no valid\r
1020 hexadecimal digits right after the optional pad spaces, the value of String\r
1021 is stored at the location pointed to by EndPointer.\r
1022\r
1023 @param String Pointer to a Null-terminated Ascii string.\r
1024 @param EndPointer Pointer to character that stops scan.\r
1025 @param Data Pointer to the converted value.\r
1026\r
1027 @retval RETURN_SUCCESS Value is translated from String.\r
1028 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
1029 If Data is NULL.\r
1030 If PcdMaximumAsciiStringLength is not zero,\r
1031 and String contains more than\r
1032 PcdMaximumAsciiStringLength Ascii\r
1033 characters, not including the\r
1034 Null-terminator.\r
1035 @retval RETURN_UNSUPPORTED If the number represented by String exceeds\r
1036 the range defined by UINT64.\r
1037\r
1038**/\r
1039RETURN_STATUS\r
1040EFIAPI\r
1041AsciiStrHexToUint64S (\r
1042 IN CONST CHAR8 *String,\r
1043 OUT CHAR8 **EndPointer, OPTIONAL\r
1044 OUT UINT64 *Data\r
1045 );\r
1046\r
c058d59f 1047\r
1bb390f1
ED
1048#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
1049\r
ac644614 1050/**\r
ae591c14 1051 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1052\r
ac644614 1053 Copies one Null-terminated Unicode string to another Null-terminated Unicode\r
1054 string and returns the new Unicode string.\r
1055\r
1056 This function copies the contents of the Unicode string Source to the Unicode\r
1057 string Destination, and returns Destination. If Source and Destination\r
1058 overlap, then the results are undefined.\r
1059\r
1060 If Destination is NULL, then ASSERT().\r
1061 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
1062 If Source is NULL, then ASSERT().\r
1063 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
1064 If Source and Destination overlap, then ASSERT().\r
1065 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
1066 PcdMaximumUnicodeStringLength Unicode characters not including the\r
1067 Null-terminator, then ASSERT().\r
1068\r
af2dc6a7 1069 @param Destination The pointer to a Null-terminated Unicode string.\r
1070 @param Source The pointer to a Null-terminated Unicode string.\r
ac644614 1071\r
9aa049d9 1072 @return Destination.\r
ac644614 1073\r
1074**/\r
1075CHAR16 *\r
1076EFIAPI\r
1077StrCpy (\r
1078 OUT CHAR16 *Destination,\r
1079 IN CONST CHAR16 *Source\r
1080 );\r
1081\r
1082\r
1083/**\r
ae591c14 1084 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1085\r
9095d37b 1086 Copies up to a specified length from one Null-terminated Unicode string to\r
17f695ed 1087 another Null-terminated Unicode string and returns the new Unicode string.\r
ac644614 1088\r
1089 This function copies the contents of the Unicode string Source to the Unicode\r
1090 string Destination, and returns Destination. At most, Length Unicode\r
1091 characters are copied from Source to Destination. If Length is 0, then\r
1092 Destination is returned unmodified. If Length is greater that the number of\r
1093 Unicode characters in Source, then Destination is padded with Null Unicode\r
1094 characters. If Source and Destination overlap, then the results are\r
1095 undefined.\r
1096\r
1097 If Length > 0 and Destination is NULL, then ASSERT().\r
1098 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().\r
1099 If Length > 0 and Source is NULL, then ASSERT().\r
77f863ee 1100 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
ac644614 1101 If Source and Destination overlap, then ASSERT().\r
9095d37b 1102 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than\r
50c247fd 1103 PcdMaximumUnicodeStringLength, then ASSERT().\r
ac644614 1104 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
50c247fd 1105 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
1106 then ASSERT().\r
ac644614 1107\r
af2dc6a7 1108 @param Destination The pointer to a Null-terminated Unicode string.\r
1109 @param Source The pointer to a Null-terminated Unicode string.\r
1110 @param Length The maximum number of Unicode characters to copy.\r
ac644614 1111\r
9aa049d9 1112 @return Destination.\r
ac644614 1113\r
1114**/\r
1115CHAR16 *\r
1116EFIAPI\r
1117StrnCpy (\r
1118 OUT CHAR16 *Destination,\r
1119 IN CONST CHAR16 *Source,\r
1120 IN UINTN Length\r
1121 );\r
de4f7f52 1122#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
ac644614 1123\r
1124/**\r
1125 Returns the length of a Null-terminated Unicode string.\r
1126\r
1127 This function returns the number of Unicode characters in the Null-terminated\r
1128 Unicode string specified by String.\r
1129\r
1130 If String is NULL, then ASSERT().\r
1131 If String is not aligned on a 16-bit boundary, then ASSERT().\r
1132 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1133 PcdMaximumUnicodeStringLength Unicode characters not including the\r
1134 Null-terminator, then ASSERT().\r
1135\r
1136 @param String Pointer to a Null-terminated Unicode string.\r
1137\r
1138 @return The length of String.\r
1139\r
1140**/\r
1141UINTN\r
1142EFIAPI\r
1143StrLen (\r
1144 IN CONST CHAR16 *String\r
1145 );\r
1146\r
1147\r
1148/**\r
1149 Returns the size of a Null-terminated Unicode string in bytes, including the\r
1150 Null terminator.\r
1151\r
9095d37b 1152 This function returns the size, in bytes, of the Null-terminated Unicode string\r
17f695ed 1153 specified by String.\r
ac644614 1154\r
1155 If String is NULL, then ASSERT().\r
1156 If String is not aligned on a 16-bit boundary, then ASSERT().\r
1157 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1158 PcdMaximumUnicodeStringLength Unicode characters not including the\r
1159 Null-terminator, then ASSERT().\r
1160\r
af2dc6a7 1161 @param String The pointer to a Null-terminated Unicode string.\r
ac644614 1162\r
1163 @return The size of String.\r
1164\r
1165**/\r
1166UINTN\r
1167EFIAPI\r
1168StrSize (\r
1169 IN CONST CHAR16 *String\r
1170 );\r
1171\r
1172\r
1173/**\r
1174 Compares two Null-terminated Unicode strings, and returns the difference\r
1175 between the first mismatched Unicode characters.\r
1176\r
1177 This function compares the Null-terminated Unicode string FirstString to the\r
1178 Null-terminated Unicode string SecondString. If FirstString is identical to\r
1179 SecondString, then 0 is returned. Otherwise, the value returned is the first\r
1180 mismatched Unicode character in SecondString subtracted from the first\r
1181 mismatched Unicode character in FirstString.\r
1182\r
1183 If FirstString is NULL, then ASSERT().\r
1184 If FirstString is not aligned on a 16-bit boundary, then ASSERT().\r
1185 If SecondString is NULL, then ASSERT().\r
1186 If SecondString is not aligned on a 16-bit boundary, then ASSERT().\r
1187 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
1188 than PcdMaximumUnicodeStringLength Unicode characters not including the\r
1189 Null-terminator, then ASSERT().\r
1190 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
af2dc6a7 1191 than PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1192 Null-terminator, then ASSERT().\r
1193\r
af2dc6a7 1194 @param FirstString The pointer to a Null-terminated Unicode string.\r
1195 @param SecondString The pointer to a Null-terminated Unicode string.\r
ac644614 1196\r
1106ffe1 1197 @retval 0 FirstString is identical to SecondString.\r
1198 @return others FirstString is not identical to SecondString.\r
ac644614 1199\r
1200**/\r
1201INTN\r
1202EFIAPI\r
1203StrCmp (\r
1204 IN CONST CHAR16 *FirstString,\r
1205 IN CONST CHAR16 *SecondString\r
1206 );\r
1207\r
1208\r
1209/**\r
17f695ed 1210 Compares up to a specified length the contents of two Null-terminated Unicode strings,\r
1211 and returns the difference between the first mismatched Unicode characters.\r
9095d37b 1212\r
ac644614 1213 This function compares the Null-terminated Unicode string FirstString to the\r
1214 Null-terminated Unicode string SecondString. At most, Length Unicode\r
1215 characters will be compared. If Length is 0, then 0 is returned. If\r
1216 FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
1217 value returned is the first mismatched Unicode character in SecondString\r
1218 subtracted from the first mismatched Unicode character in FirstString.\r
1219\r
1220 If Length > 0 and FirstString is NULL, then ASSERT().\r
77f863ee 1221 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().\r
ac644614 1222 If Length > 0 and SecondString is NULL, then ASSERT().\r
77f863ee 1223 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().\r
50c247fd 1224 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than\r
1225 PcdMaximumUnicodeStringLength, then ASSERT().\r
1226 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than\r
1227 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
1228 then ASSERT().\r
1229 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than\r
1230 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,\r
1231 then ASSERT().\r
ac644614 1232\r
af2dc6a7 1233 @param FirstString The pointer to a Null-terminated Unicode string.\r
1234 @param SecondString The pointer to a Null-terminated Unicode string.\r
1235 @param Length The maximum number of Unicode characters to compare.\r
ac644614 1236\r
1106ffe1 1237 @retval 0 FirstString is identical to SecondString.\r
1238 @return others FirstString is not identical to SecondString.\r
ac644614 1239\r
1240**/\r
1241INTN\r
1242EFIAPI\r
1243StrnCmp (\r
1244 IN CONST CHAR16 *FirstString,\r
1245 IN CONST CHAR16 *SecondString,\r
1246 IN UINTN Length\r
1247 );\r
1248\r
1249\r
1bb390f1
ED
1250#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
1251\r
ac644614 1252/**\r
ae591c14 1253 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1254\r
ac644614 1255 Concatenates one Null-terminated Unicode string to another Null-terminated\r
1256 Unicode string, and returns the concatenated Unicode string.\r
1257\r
1258 This function concatenates two Null-terminated Unicode strings. The contents\r
1259 of Null-terminated Unicode string Source are concatenated to the end of\r
1260 Null-terminated Unicode string Destination. The Null-terminated concatenated\r
1261 Unicode String is returned. If Source and Destination overlap, then the\r
1262 results are undefined.\r
1263\r
1264 If Destination is NULL, then ASSERT().\r
77f863ee 1265 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
ac644614 1266 If Source is NULL, then ASSERT().\r
77f863ee 1267 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
ac644614 1268 If Source and Destination overlap, then ASSERT().\r
1269 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
af2dc6a7 1270 than PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1271 Null-terminator, then ASSERT().\r
1272 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
af2dc6a7 1273 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1274 Null-terminator, then ASSERT().\r
1275 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
1276 and Source results in a Unicode string with more than\r
af2dc6a7 1277 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1278 Null-terminator, then ASSERT().\r
1279\r
af2dc6a7 1280 @param Destination The pointer to a Null-terminated Unicode string.\r
1281 @param Source The pointer to a Null-terminated Unicode string.\r
ac644614 1282\r
9aa049d9 1283 @return Destination.\r
ac644614 1284\r
1285**/\r
1286CHAR16 *\r
1287EFIAPI\r
1288StrCat (\r
1289 IN OUT CHAR16 *Destination,\r
1290 IN CONST CHAR16 *Source\r
1291 );\r
1292\r
1293\r
1294/**\r
ae591c14 1295 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1296\r
9095d37b
LG
1297 Concatenates up to a specified length one Null-terminated Unicode to the end\r
1298 of another Null-terminated Unicode string, and returns the concatenated\r
ac644614 1299 Unicode string.\r
1300\r
1301 This function concatenates two Null-terminated Unicode strings. The contents\r
1302 of Null-terminated Unicode string Source are concatenated to the end of\r
1303 Null-terminated Unicode string Destination, and Destination is returned. At\r
1304 most, Length Unicode characters are concatenated from Source to the end of\r
1305 Destination, and Destination is always Null-terminated. If Length is 0, then\r
1306 Destination is returned unmodified. If Source and Destination overlap, then\r
1307 the results are undefined.\r
1308\r
1309 If Destination is NULL, then ASSERT().\r
1310 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().\r
1311 If Length > 0 and Source is NULL, then ASSERT().\r
1312 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
1313 If Source and Destination overlap, then ASSERT().\r
9095d37b 1314 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than\r
50c247fd 1315 PcdMaximumUnicodeStringLength, then ASSERT().\r
ac644614 1316 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
50c247fd 1317 than PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1318 Null-terminator, then ASSERT().\r
1319 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
50c247fd 1320 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
ac644614 1321 Null-terminator, then ASSERT().\r
1322 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
50c247fd 1323 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength\r
1324 Unicode characters, not including the Null-terminator, then ASSERT().\r
ac644614 1325\r
af2dc6a7 1326 @param Destination The pointer to a Null-terminated Unicode string.\r
1327 @param Source The pointer to a Null-terminated Unicode string.\r
1328 @param Length The maximum number of Unicode characters to concatenate from\r
ac644614 1329 Source.\r
1330\r
9aa049d9 1331 @return Destination.\r
ac644614 1332\r
1333**/\r
1334CHAR16 *\r
1335EFIAPI\r
1336StrnCat (\r
1337 IN OUT CHAR16 *Destination,\r
1338 IN CONST CHAR16 *Source,\r
1339 IN UINTN Length\r
1340 );\r
de4f7f52 1341#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
ac644614 1342\r
1343/**\r
9aa049d9 1344 Returns the first occurrence of a Null-terminated Unicode sub-string\r
ac644614 1345 in a Null-terminated Unicode string.\r
1346\r
1347 This function scans the contents of the Null-terminated Unicode string\r
1348 specified by String and returns the first occurrence of SearchString.\r
1349 If SearchString is not found in String, then NULL is returned. If\r
af2dc6a7 1350 the length of SearchString is zero, then String is returned.\r
ac644614 1351\r
1352 If String is NULL, then ASSERT().\r
1353 If String is not aligned on a 16-bit boundary, then ASSERT().\r
1354 If SearchString is NULL, then ASSERT().\r
1355 If SearchString is not aligned on a 16-bit boundary, then ASSERT().\r
1356\r
1357 If PcdMaximumUnicodeStringLength is not zero, and SearchString\r
1358 or String contains more than PcdMaximumUnicodeStringLength Unicode\r
af2dc6a7 1359 characters, not including the Null-terminator, then ASSERT().\r
ac644614 1360\r
af2dc6a7 1361 @param String The pointer to a Null-terminated Unicode string.\r
1362 @param SearchString The pointer to a Null-terminated Unicode string to search for.\r
ac644614 1363\r
1364 @retval NULL If the SearchString does not appear in String.\r
1106ffe1 1365 @return others If there is a match.\r
ac644614 1366\r
1367**/\r
1368CHAR16 *\r
1369EFIAPI\r
1370StrStr (\r
17f695ed 1371 IN CONST CHAR16 *String,\r
1372 IN CONST CHAR16 *SearchString\r
ac644614 1373 );\r
1374\r
1375/**\r
1376 Convert a Null-terminated Unicode decimal string to a value of\r
1377 type UINTN.\r
1378\r
1379 This function returns a value of type UINTN by interpreting the contents\r
1380 of the Unicode string specified by String as a decimal number. The format\r
1381 of the input Unicode string String is:\r
1382\r
1383 [spaces] [decimal digits].\r
1384\r
1385 The valid decimal digit character is in the range [0-9]. The\r
1386 function will ignore the pad space, which includes spaces or\r
1387 tab characters, before [decimal digits]. The running zero in the\r
1388 beginning of [decimal digits] will be ignored. Then, the function\r
1389 stops at the first character that is a not a valid decimal character\r
1390 or a Null-terminator, whichever one comes first.\r
1391\r
1392 If String is NULL, then ASSERT().\r
1393 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1394 If String has only pad spaces, then 0 is returned.\r
1395 If String has no pad spaces or valid decimal digits,\r
1396 then 0 is returned.\r
1397 If the number represented by String overflows according\r
ea2e0921 1398 to the range defined by UINTN, then MAX_UINTN is returned.\r
ac644614 1399\r
1400 If PcdMaximumUnicodeStringLength is not zero, and String contains\r
1401 more than PcdMaximumUnicodeStringLength Unicode characters not including\r
1402 the Null-terminator, then ASSERT().\r
1403\r
af2dc6a7 1404 @param String The pointer to a Null-terminated Unicode string.\r
ac644614 1405\r
38bbd3d9 1406 @retval Value translated from String.\r
ac644614 1407\r
1408**/\r
1409UINTN\r
1410EFIAPI\r
1411StrDecimalToUintn (\r
17f695ed 1412 IN CONST CHAR16 *String\r
ac644614 1413 );\r
1414\r
1415/**\r
1416 Convert a Null-terminated Unicode decimal string to a value of\r
1417 type UINT64.\r
1418\r
1419 This function returns a value of type UINT64 by interpreting the contents\r
1420 of the Unicode string specified by String as a decimal number. The format\r
1421 of the input Unicode string String is:\r
1422\r
1423 [spaces] [decimal digits].\r
1424\r
1425 The valid decimal digit character is in the range [0-9]. The\r
1426 function will ignore the pad space, which includes spaces or\r
1427 tab characters, before [decimal digits]. The running zero in the\r
1428 beginning of [decimal digits] will be ignored. Then, the function\r
1429 stops at the first character that is a not a valid decimal character\r
1430 or a Null-terminator, whichever one comes first.\r
1431\r
1432 If String is NULL, then ASSERT().\r
1433 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1434 If String has only pad spaces, then 0 is returned.\r
1435 If String has no pad spaces or valid decimal digits,\r
1436 then 0 is returned.\r
1437 If the number represented by String overflows according\r
ea2e0921 1438 to the range defined by UINT64, then MAX_UINT64 is returned.\r
ac644614 1439\r
1440 If PcdMaximumUnicodeStringLength is not zero, and String contains\r
1441 more than PcdMaximumUnicodeStringLength Unicode characters not including\r
1442 the Null-terminator, then ASSERT().\r
1443\r
af2dc6a7 1444 @param String The pointer to a Null-terminated Unicode string.\r
ac644614 1445\r
38bbd3d9 1446 @retval Value translated from String.\r
ac644614 1447\r
1448**/\r
1449UINT64\r
1450EFIAPI\r
1451StrDecimalToUint64 (\r
17f695ed 1452 IN CONST CHAR16 *String\r
ac644614 1453 );\r
9095d37b 1454\r
ac644614 1455\r
1456/**\r
1457 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.\r
1458\r
1459 This function returns a value of type UINTN by interpreting the contents\r
1460 of the Unicode string specified by String as a hexadecimal number.\r
1461 The format of the input Unicode string String is:\r
1462\r
1463 [spaces][zeros][x][hexadecimal digits].\r
1464\r
1465 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
1466 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.\r
1467 If "x" appears in the input string, it must be prefixed with at least one 0.\r
1468 The function will ignore the pad space, which includes spaces or tab characters,\r
1469 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or\r
1470 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the\r
9095d37b 1471 first valid hexadecimal digit. Then, the function stops at the first character\r
af2dc6a7 1472 that is a not a valid hexadecimal character or NULL, whichever one comes first.\r
ac644614 1473\r
1474 If String is NULL, then ASSERT().\r
1475 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1476 If String has only pad spaces, then zero is returned.\r
1477 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,\r
1478 then zero is returned.\r
1479 If the number represented by String overflows according to the range defined by\r
ea2e0921 1480 UINTN, then MAX_UINTN is returned.\r
ac644614 1481\r
1482 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1483 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,\r
1484 then ASSERT().\r
1485\r
af2dc6a7 1486 @param String The pointer to a Null-terminated Unicode string.\r
ac644614 1487\r
38bbd3d9 1488 @retval Value translated from String.\r
ac644614 1489\r
1490**/\r
1491UINTN\r
1492EFIAPI\r
1493StrHexToUintn (\r
17f695ed 1494 IN CONST CHAR16 *String\r
ac644614 1495 );\r
1496\r
1497\r
1498/**\r
1499 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.\r
1500\r
1501 This function returns a value of type UINT64 by interpreting the contents\r
1502 of the Unicode string specified by String as a hexadecimal number.\r
1503 The format of the input Unicode string String is\r
1504\r
1505 [spaces][zeros][x][hexadecimal digits].\r
1506\r
1507 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
1508 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.\r
1509 If "x" appears in the input string, it must be prefixed with at least one 0.\r
1510 The function will ignore the pad space, which includes spaces or tab characters,\r
1511 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or\r
1512 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the\r
1513 first valid hexadecimal digit. Then, the function stops at the first character that is\r
1514 a not a valid hexadecimal character or NULL, whichever one comes first.\r
1515\r
1516 If String is NULL, then ASSERT().\r
1517 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1518 If String has only pad spaces, then zero is returned.\r
1519 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,\r
1520 then zero is returned.\r
1521 If the number represented by String overflows according to the range defined by\r
ea2e0921 1522 UINT64, then MAX_UINT64 is returned.\r
ac644614 1523\r
1524 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1525 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,\r
1526 then ASSERT().\r
1527\r
af2dc6a7 1528 @param String The pointer to a Null-terminated Unicode string.\r
ac644614 1529\r
38bbd3d9 1530 @retval Value translated from String.\r
ac644614 1531\r
1532**/\r
1533UINT64\r
1534EFIAPI\r
1535StrHexToUint64 (\r
17f695ed 1536 IN CONST CHAR16 *String\r
ac644614 1537 );\r
1538\r
36396ea2
RN
1539/**\r
1540 Convert a Null-terminated Unicode string to IPv6 address and prefix length.\r
1541\r
1542 This function outputs a value of type IPv6_ADDRESS and may output a value\r
1543 of type UINT8 by interpreting the contents of the Unicode string specified\r
1544 by String. The format of the input Unicode string String is as follows:\r
1545\r
1546 X:X:X:X:X:X:X:X[/P]\r
1547\r
1548 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and\r
1549 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low\r
1550 memory address and high byte is stored in high memory address. P contains decimal\r
1551 digit characters in the range [0-9]. The running zero in the beginning of P will\r
1552 be ignored. /P is optional.\r
1553\r
1554 When /P is not in the String, the function stops at the first character that is\r
1555 not a valid hexadecimal digit character after eight X's are converted.\r
1556\r
1557 When /P is in the String, the function stops at the first character that is not\r
1558 a valid decimal digit character after P is converted.\r
1559\r
1560 "::" can be used to compress one or more groups of X when X contains only 0.\r
1561 The "::" can only appear once in the String.\r
1562\r
1563 If String is NULL, then ASSERT().\r
1564\r
1565 If Address is NULL, then ASSERT().\r
1566\r
1567 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1568\r
1569 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1570 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
1571 Null-terminator, then ASSERT().\r
1572\r
1573 If EndPointer is not NULL and Address is translated from String, a pointer\r
1574 to the character that stopped the scan is stored at the location pointed to\r
1575 by EndPointer.\r
1576\r
1577 @param String Pointer to a Null-terminated Unicode string.\r
1578 @param EndPointer Pointer to character that stops scan.\r
1579 @param Address Pointer to the converted IPv6 address.\r
1580 @param PrefixLength Pointer to the converted IPv6 address prefix\r
1581 length. MAX_UINT8 is returned when /P is\r
1582 not in the String.\r
1583\r
1584 @retval RETURN_SUCCESS Address is translated from String.\r
1585 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
1586 If Data is NULL.\r
1587 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal\r
1588 digit characters.\r
1589 If String contains "::" and number of X\r
1590 is not less than 8.\r
1591 If P starts with character that is not a\r
1592 valid decimal digit character.\r
1593 If the decimal number converted from P\r
1594 exceeds 128.\r
1595\r
1596**/\r
1597RETURN_STATUS\r
1598EFIAPI\r
1599StrToIpv6Address (\r
1600 IN CONST CHAR16 *String,\r
1601 OUT CHAR16 **EndPointer, OPTIONAL\r
1602 OUT IPv6_ADDRESS *Address,\r
1603 OUT UINT8 *PrefixLength OPTIONAL\r
1604 );\r
1605\r
1606/**\r
1607 Convert a Null-terminated Unicode string to IPv4 address and prefix length.\r
1608\r
1609 This function outputs a value of type IPv4_ADDRESS and may output a value\r
1610 of type UINT8 by interpreting the contents of the Unicode string specified\r
1611 by String. The format of the input Unicode string String is as follows:\r
1612\r
1613 D.D.D.D[/P]\r
1614\r
1615 D and P are decimal digit characters in the range [0-9]. The running zero in\r
1616 the beginning of D and P will be ignored. /P is optional.\r
1617\r
1618 When /P is not in the String, the function stops at the first character that is\r
1619 not a valid decimal digit character after four D's are converted.\r
1620\r
1621 When /P is in the String, the function stops at the first character that is not\r
1622 a valid decimal digit character after P is converted.\r
1623\r
1624 If String is NULL, then ASSERT().\r
1625\r
1626 If Address is NULL, then ASSERT().\r
1627\r
1628 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1629\r
1630 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
1631 PcdMaximumUnicodeStringLength Unicode characters, not including the\r
1632 Null-terminator, then ASSERT().\r
1633\r
1634 If EndPointer is not NULL and Address is translated from String, a pointer\r
1635 to the character that stopped the scan is stored at the location pointed to\r
1636 by EndPointer.\r
1637\r
1638 @param String Pointer to a Null-terminated Unicode string.\r
1639 @param EndPointer Pointer to character that stops scan.\r
1640 @param Address Pointer to the converted IPv4 address.\r
1641 @param PrefixLength Pointer to the converted IPv4 address prefix\r
1642 length. MAX_UINT8 is returned when /P is\r
1643 not in the String.\r
1644\r
1645 @retval RETURN_SUCCESS Address is translated from String.\r
1646 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
1647 If Data is NULL.\r
1648 @retval RETURN_UNSUPPORTED If String is not in the correct format.\r
1649 If any decimal number converted from D\r
1650 exceeds 255.\r
1651 If the decimal number converted from P\r
1652 exceeds 32.\r
1653\r
1654**/\r
1655RETURN_STATUS\r
1656EFIAPI\r
1657StrToIpv4Address (\r
1658 IN CONST CHAR16 *String,\r
1659 OUT CHAR16 **EndPointer, OPTIONAL\r
1660 OUT IPv4_ADDRESS *Address,\r
1661 OUT UINT8 *PrefixLength OPTIONAL\r
1662 );\r
1663\r
1664#define GUID_STRING_LENGTH 36\r
1665\r
1666/**\r
1667 Convert a Null-terminated Unicode GUID string to a value of type\r
1668 EFI_GUID.\r
1669\r
1670 This function outputs a GUID value by interpreting the contents of\r
1671 the Unicode string specified by String. The format of the input\r
1672 Unicode string String consists of 36 characters, as follows:\r
1673\r
1674 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp\r
1675\r
1676 The pairs aa - pp are two characters in the range [0-9], [a-f] and\r
1677 [A-F], with each pair representing a single byte hexadecimal value.\r
1678\r
1679 The mapping between String and the EFI_GUID structure is as follows:\r
1680 aa Data1[24:31]\r
1681 bb Data1[16:23]\r
1682 cc Data1[8:15]\r
1683 dd Data1[0:7]\r
1684 ee Data2[8:15]\r
1685 ff Data2[0:7]\r
1686 gg Data3[8:15]\r
1687 hh Data3[0:7]\r
1688 ii Data4[0:7]\r
1689 jj Data4[8:15]\r
1690 kk Data4[16:23]\r
1691 ll Data4[24:31]\r
1692 mm Data4[32:39]\r
1693 nn Data4[40:47]\r
1694 oo Data4[48:55]\r
1695 pp Data4[56:63]\r
1696\r
1697 If String is NULL, then ASSERT().\r
1698 If Guid is NULL, then ASSERT().\r
1699 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1700\r
1701 @param String Pointer to a Null-terminated Unicode string.\r
1702 @param Guid Pointer to the converted GUID.\r
1703\r
1704 @retval RETURN_SUCCESS Guid is translated from String.\r
1705 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
1706 If Data is NULL.\r
1707 @retval RETURN_UNSUPPORTED If String is not as the above format.\r
1708\r
1709**/\r
1710RETURN_STATUS\r
1711EFIAPI\r
1712StrToGuid (\r
1713 IN CONST CHAR16 *String,\r
1714 OUT GUID *Guid\r
1715 );\r
1716\r
1717/**\r
1718 Convert a Null-terminated Unicode hexadecimal string to a byte array.\r
1719\r
1720 This function outputs a byte array by interpreting the contents of\r
1721 the Unicode string specified by String in hexadecimal format. The format of\r
1722 the input Unicode string String is:\r
1723\r
1724 [XX]*\r
1725\r
1726 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].\r
1727 The function decodes every two hexadecimal digit characters as one byte. The\r
1728 decoding stops after Length of characters and outputs Buffer containing\r
1729 (Length / 2) bytes.\r
1730\r
1731 If String is not aligned in a 16-bit boundary, then ASSERT().\r
1732\r
1733 If String is NULL, then ASSERT().\r
1734\r
1735 If Buffer is NULL, then ASSERT().\r
1736\r
1737 If Length is not multiple of 2, then ASSERT().\r
1738\r
1739 If PcdMaximumUnicodeStringLength is not zero and Length is greater than\r
1740 PcdMaximumUnicodeStringLength, then ASSERT().\r
1741\r
1742 If MaxBufferSize is less than (Length / 2), then ASSERT().\r
1743\r
1744 @param String Pointer to a Null-terminated Unicode string.\r
1745 @param Length The number of Unicode characters to decode.\r
1746 @param Buffer Pointer to the converted bytes array.\r
1747 @param MaxBufferSize The maximum size of Buffer.\r
1748\r
1749 @retval RETURN_SUCCESS Buffer is translated from String.\r
1750 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
1751 If Data is NULL.\r
1752 If Length is not multiple of 2.\r
1753 If PcdMaximumUnicodeStringLength is not zero,\r
1754 and Length is greater than\r
1755 PcdMaximumUnicodeStringLength.\r
1756 @retval RETURN_UNSUPPORTED If Length of characters from String contain\r
1757 a character that is not valid hexadecimal\r
1758 digit characters, or a Null-terminator.\r
1759 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).\r
1760**/\r
1761RETURN_STATUS\r
1762EFIAPI\r
1763StrHexToBytes (\r
1764 IN CONST CHAR16 *String,\r
1765 IN UINTN Length,\r
1766 OUT UINT8 *Buffer,\r
1767 IN UINTN MaxBufferSize\r
1768 );\r
1769\r
415aa2f1
SZ
1770#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
1771\r
ac644614 1772/**\r
415aa2f1
SZ
1773 [ATTENTION] This function is deprecated for security reason.\r
1774\r
17f695ed 1775 Convert a Null-terminated Unicode string to a Null-terminated\r
ac644614 1776 ASCII string and returns the ASCII string.\r
1777\r
1778 This function converts the content of the Unicode string Source\r
1779 to the ASCII string Destination by copying the lower 8 bits of\r
1780 each Unicode character. It returns Destination.\r
1781\r
d3e0289c 1782 The caller is responsible to make sure Destination points to a buffer with size\r
1783 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.\r
1784\r
ac644614 1785 If any Unicode characters in Source contain non-zero value in\r
1786 the upper 8 bits, then ASSERT().\r
1787\r
1788 If Destination is NULL, then ASSERT().\r
1789 If Source is NULL, then ASSERT().\r
1790 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
1791 If Source and Destination overlap, then ASSERT().\r
1792\r
1793 If PcdMaximumUnicodeStringLength is not zero, and Source contains\r
1794 more than PcdMaximumUnicodeStringLength Unicode characters not including\r
1795 the Null-terminator, then ASSERT().\r
1796\r
1797 If PcdMaximumAsciiStringLength is not zero, and Source contains more\r
1798 than PcdMaximumAsciiStringLength Unicode characters not including the\r
1799 Null-terminator, then ASSERT().\r
1800\r
af2dc6a7 1801 @param Source The pointer to a Null-terminated Unicode string.\r
1802 @param Destination The pointer to a Null-terminated ASCII string.\r
ac644614 1803\r
9aa049d9 1804 @return Destination.\r
ac644614 1805\r
1806**/\r
1807CHAR8 *\r
1808EFIAPI\r
1809UnicodeStrToAsciiStr (\r
17f695ed 1810 IN CONST CHAR16 *Source,\r
1811 OUT CHAR8 *Destination\r
ac644614 1812 );\r
1813\r
de4f7f52 1814#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
415aa2f1 1815\r
3ab41b7a
JY
1816/**\r
1817 Convert a Null-terminated Unicode string to a Null-terminated\r
1818 ASCII string.\r
1819\r
1820 This function is similar to AsciiStrCpyS.\r
1821\r
1822 This function converts the content of the Unicode string Source\r
1823 to the ASCII string Destination by copying the lower 8 bits of\r
1824 each Unicode character. The function terminates the ASCII string\r
1825 Destination by appending a Null-terminator character at the end.\r
1826\r
1827 The caller is responsible to make sure Destination points to a buffer with size\r
1828 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.\r
1829\r
1830 If any Unicode characters in Source contain non-zero value in\r
1831 the upper 8 bits, then ASSERT().\r
1832\r
1833 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
1834 If an error would be returned, then the function will also ASSERT().\r
1835\r
1836 If an error is returned, then the Destination is unmodified.\r
1837\r
1838 @param Source The pointer to a Null-terminated Unicode string.\r
1839 @param Destination The pointer to a Null-terminated ASCII string.\r
1840 @param DestMax The maximum number of Destination Ascii\r
1841 char, including terminating null char.\r
1842\r
1843 @retval RETURN_SUCCESS String is converted.\r
1844 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
1845 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
1846 If Source is NULL.\r
1847 If PcdMaximumAsciiStringLength is not zero,\r
1848 and DestMax is greater than\r
1849 PcdMaximumAsciiStringLength.\r
1850 If PcdMaximumUnicodeStringLength is not zero,\r
1851 and DestMax is greater than\r
1852 PcdMaximumUnicodeStringLength.\r
1853 If DestMax is 0.\r
1854 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
1855\r
1856**/\r
1857RETURN_STATUS\r
1858EFIAPI\r
1859UnicodeStrToAsciiStrS (\r
1860 IN CONST CHAR16 *Source,\r
1861 OUT CHAR8 *Destination,\r
1862 IN UINTN DestMax\r
1863 );\r
ac644614 1864\r
02263214
HW
1865/**\r
1866 Convert not more than Length successive characters from a Null-terminated\r
1867 Unicode string to a Null-terminated Ascii string. If no null char is copied\r
1868 from Source, then Destination[Length] is always set to null.\r
1869\r
1870 This function converts not more than Length successive characters from the\r
1871 Unicode string Source to the Ascii string Destination by copying the lower 8\r
1872 bits of each Unicode character. The function terminates the Ascii string\r
1873 Destination by appending a Null-terminator character at the end.\r
1874\r
1875 The caller is responsible to make sure Destination points to a buffer with size\r
1876 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.\r
1877\r
1878 If any Unicode characters in Source contain non-zero value in the upper 8\r
1879 bits, then ASSERT().\r
1880 If Source is not aligned on a 16-bit boundary, then ASSERT().\r
1881 If an error would be returned, then the function will also ASSERT().\r
1882\r
1883 If an error is returned, then the Destination is unmodified.\r
1884\r
1885 @param Source The pointer to a Null-terminated Unicode string.\r
1886 @param Length The maximum number of Unicode characters to\r
1887 convert.\r
1888 @param Destination The pointer to a Null-terminated Ascii string.\r
1889 @param DestMax The maximum number of Destination Ascii\r
1890 char, including terminating null char.\r
1891 @param DestinationLength The number of Unicode characters converted.\r
1892\r
1893 @retval RETURN_SUCCESS String is converted.\r
1894 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
1895 If Source is NULL.\r
1896 If DestinationLength is NULL.\r
1897 If PcdMaximumAsciiStringLength is not zero,\r
1898 and Length or DestMax is greater than\r
1899 PcdMaximumAsciiStringLength.\r
1900 If PcdMaximumUnicodeStringLength is not\r
1901 zero, and Length or DestMax is greater than\r
1902 PcdMaximumUnicodeStringLength.\r
1903 If DestMax is 0.\r
1904 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than\r
1905 MIN(StrLen(Source), Length).\r
1906 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
1907\r
1908**/\r
1909RETURN_STATUS\r
1910EFIAPI\r
1911UnicodeStrnToAsciiStrS (\r
1912 IN CONST CHAR16 *Source,\r
1913 IN UINTN Length,\r
1914 OUT CHAR8 *Destination,\r
1915 IN UINTN DestMax,\r
1916 OUT UINTN *DestinationLength\r
1917 );\r
1918\r
1bb390f1
ED
1919#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
1920\r
ac644614 1921/**\r
ae591c14 1922 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1923\r
ac644614 1924 Copies one Null-terminated ASCII string to another Null-terminated ASCII\r
1925 string and returns the new ASCII string.\r
1926\r
1927 This function copies the contents of the ASCII string Source to the ASCII\r
1928 string Destination, and returns Destination. If Source and Destination\r
1929 overlap, then the results are undefined.\r
1930\r
1931 If Destination is NULL, then ASSERT().\r
1932 If Source is NULL, then ASSERT().\r
1933 If Source and Destination overlap, then ASSERT().\r
1934 If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
1935 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
1936 then ASSERT().\r
1937\r
af2dc6a7 1938 @param Destination The pointer to a Null-terminated ASCII string.\r
1939 @param Source The pointer to a Null-terminated ASCII string.\r
ac644614 1940\r
1941 @return Destination\r
1942\r
1943**/\r
1944CHAR8 *\r
1945EFIAPI\r
1946AsciiStrCpy (\r
1947 OUT CHAR8 *Destination,\r
1948 IN CONST CHAR8 *Source\r
1949 );\r
1950\r
1951\r
1952/**\r
ae591c14 1953 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 1954\r
9095d37b 1955 Copies up to a specified length one Null-terminated ASCII string to another\r
17f695ed 1956 Null-terminated ASCII string and returns the new ASCII string.\r
ac644614 1957\r
1958 This function copies the contents of the ASCII string Source to the ASCII\r
1959 string Destination, and returns Destination. At most, Length ASCII characters\r
1960 are copied from Source to Destination. If Length is 0, then Destination is\r
1961 returned unmodified. If Length is greater that the number of ASCII characters\r
1962 in Source, then Destination is padded with Null ASCII characters. If Source\r
1963 and Destination overlap, then the results are undefined.\r
1964\r
1965 If Destination is NULL, then ASSERT().\r
1966 If Source is NULL, then ASSERT().\r
1967 If Source and Destination overlap, then ASSERT().\r
9095d37b 1968 If PcdMaximumAsciiStringLength is not zero, and Length is greater than\r
50c247fd 1969 PcdMaximumAsciiStringLength, then ASSERT().\r
ac644614 1970 If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
50c247fd 1971 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r
ac644614 1972 then ASSERT().\r
1973\r
af2dc6a7 1974 @param Destination The pointer to a Null-terminated ASCII string.\r
1975 @param Source The pointer to a Null-terminated ASCII string.\r
1976 @param Length The maximum number of ASCII characters to copy.\r
ac644614 1977\r
1978 @return Destination\r
1979\r
1980**/\r
1981CHAR8 *\r
1982EFIAPI\r
1983AsciiStrnCpy (\r
1984 OUT CHAR8 *Destination,\r
1985 IN CONST CHAR8 *Source,\r
1986 IN UINTN Length\r
1987 );\r
de4f7f52 1988#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
ac644614 1989\r
1990/**\r
1991 Returns the length of a Null-terminated ASCII string.\r
1992\r
1993 This function returns the number of ASCII characters in the Null-terminated\r
1994 ASCII string specified by String.\r
1995\r
1996 If Length > 0 and Destination is NULL, then ASSERT().\r
1997 If Length > 0 and Source is NULL, then ASSERT().\r
1998 If PcdMaximumAsciiStringLength is not zero and String contains more than\r
1999 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2000 then ASSERT().\r
2001\r
af2dc6a7 2002 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2003\r
2004 @return The length of String.\r
2005\r
2006**/\r
2007UINTN\r
2008EFIAPI\r
2009AsciiStrLen (\r
2010 IN CONST CHAR8 *String\r
2011 );\r
2012\r
2013\r
2014/**\r
2015 Returns the size of a Null-terminated ASCII string in bytes, including the\r
2016 Null terminator.\r
2017\r
2018 This function returns the size, in bytes, of the Null-terminated ASCII string\r
2019 specified by String.\r
2020\r
2021 If String is NULL, then ASSERT().\r
2022 If PcdMaximumAsciiStringLength is not zero and String contains more than\r
2023 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2024 then ASSERT().\r
2025\r
af2dc6a7 2026 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2027\r
2028 @return The size of String.\r
2029\r
2030**/\r
2031UINTN\r
2032EFIAPI\r
2033AsciiStrSize (\r
2034 IN CONST CHAR8 *String\r
2035 );\r
2036\r
2037\r
2038/**\r
2039 Compares two Null-terminated ASCII strings, and returns the difference\r
2040 between the first mismatched ASCII characters.\r
2041\r
2042 This function compares the Null-terminated ASCII string FirstString to the\r
2043 Null-terminated ASCII string SecondString. If FirstString is identical to\r
2044 SecondString, then 0 is returned. Otherwise, the value returned is the first\r
2045 mismatched ASCII character in SecondString subtracted from the first\r
2046 mismatched ASCII character in FirstString.\r
2047\r
2048 If FirstString is NULL, then ASSERT().\r
2049 If SecondString is NULL, then ASSERT().\r
2050 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
2051 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2052 then ASSERT().\r
2053 If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
2054 than PcdMaximumAsciiStringLength ASCII characters not including the\r
2055 Null-terminator, then ASSERT().\r
2056\r
af2dc6a7 2057 @param FirstString The pointer to a Null-terminated ASCII string.\r
2058 @param SecondString The pointer to a Null-terminated ASCII string.\r
ac644614 2059\r
17f695ed 2060 @retval ==0 FirstString is identical to SecondString.\r
2061 @retval !=0 FirstString is not identical to SecondString.\r
ac644614 2062\r
2063**/\r
2064INTN\r
2065EFIAPI\r
2066AsciiStrCmp (\r
2067 IN CONST CHAR8 *FirstString,\r
2068 IN CONST CHAR8 *SecondString\r
2069 );\r
2070\r
2071\r
2072/**\r
2073 Performs a case insensitive comparison of two Null-terminated ASCII strings,\r
2074 and returns the difference between the first mismatched ASCII characters.\r
2075\r
2076 This function performs a case insensitive comparison of the Null-terminated\r
2077 ASCII string FirstString to the Null-terminated ASCII string SecondString. If\r
2078 FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
2079 value returned is the first mismatched lower case ASCII character in\r
2080 SecondString subtracted from the first mismatched lower case ASCII character\r
2081 in FirstString.\r
2082\r
2083 If FirstString is NULL, then ASSERT().\r
2084 If SecondString is NULL, then ASSERT().\r
2085 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
2086 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2087 then ASSERT().\r
2088 If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
2089 than PcdMaximumAsciiStringLength ASCII characters not including the\r
2090 Null-terminator, then ASSERT().\r
2091\r
af2dc6a7 2092 @param FirstString The pointer to a Null-terminated ASCII string.\r
2093 @param SecondString The pointer to a Null-terminated ASCII string.\r
ac644614 2094\r
17f695ed 2095 @retval ==0 FirstString is identical to SecondString using case insensitive\r
1106ffe1 2096 comparisons.\r
17f695ed 2097 @retval !=0 FirstString is not identical to SecondString using case\r
1106ffe1 2098 insensitive comparisons.\r
ac644614 2099\r
2100**/\r
2101INTN\r
2102EFIAPI\r
2103AsciiStriCmp (\r
2104 IN CONST CHAR8 *FirstString,\r
2105 IN CONST CHAR8 *SecondString\r
2106 );\r
2107\r
2108\r
2109/**\r
2110 Compares two Null-terminated ASCII strings with maximum lengths, and returns\r
2111 the difference between the first mismatched ASCII characters.\r
2112\r
2113 This function compares the Null-terminated ASCII string FirstString to the\r
2114 Null-terminated ASCII string SecondString. At most, Length ASCII characters\r
2115 will be compared. If Length is 0, then 0 is returned. If FirstString is\r
2116 identical to SecondString, then 0 is returned. Otherwise, the value returned\r
2117 is the first mismatched ASCII character in SecondString subtracted from the\r
2118 first mismatched ASCII character in FirstString.\r
2119\r
2120 If Length > 0 and FirstString is NULL, then ASSERT().\r
2121 If Length > 0 and SecondString is NULL, then ASSERT().\r
9095d37b 2122 If PcdMaximumAsciiStringLength is not zero, and Length is greater than\r
50c247fd 2123 PcdMaximumAsciiStringLength, then ASSERT().\r
2124 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than\r
2125 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r
ac644614 2126 then ASSERT().\r
50c247fd 2127 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than\r
2128 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r
ac644614 2129 then ASSERT().\r
2130\r
af2dc6a7 2131 @param FirstString The pointer to a Null-terminated ASCII string.\r
2132 @param SecondString The pointer to a Null-terminated ASCII string.\r
2133 @param Length The maximum number of ASCII characters for compare.\r
9095d37b 2134\r
17f695ed 2135 @retval ==0 FirstString is identical to SecondString.\r
2136 @retval !=0 FirstString is not identical to SecondString.\r
ac644614 2137\r
2138**/\r
2139INTN\r
2140EFIAPI\r
2141AsciiStrnCmp (\r
2142 IN CONST CHAR8 *FirstString,\r
2143 IN CONST CHAR8 *SecondString,\r
2144 IN UINTN Length\r
2145 );\r
2146\r
2147\r
1bb390f1
ED
2148#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
2149\r
ac644614 2150/**\r
ae591c14 2151 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 2152\r
ac644614 2153 Concatenates one Null-terminated ASCII string to another Null-terminated\r
2154 ASCII string, and returns the concatenated ASCII string.\r
2155\r
2156 This function concatenates two Null-terminated ASCII strings. The contents of\r
2157 Null-terminated ASCII string Source are concatenated to the end of Null-\r
2158 terminated ASCII string Destination. The Null-terminated concatenated ASCII\r
2159 String is returned.\r
2160\r
2161 If Destination is NULL, then ASSERT().\r
2162 If Source is NULL, then ASSERT().\r
2163 If PcdMaximumAsciiStringLength is not zero and Destination contains more than\r
2164 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2165 then ASSERT().\r
2166 If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
2167 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2168 then ASSERT().\r
2169 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and\r
2170 Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
2171 ASCII characters, then ASSERT().\r
2172\r
af2dc6a7 2173 @param Destination The pointer to a Null-terminated ASCII string.\r
2174 @param Source The pointer to a Null-terminated ASCII string.\r
ac644614 2175\r
2176 @return Destination\r
2177\r
2178**/\r
2179CHAR8 *\r
2180EFIAPI\r
2181AsciiStrCat (\r
2182 IN OUT CHAR8 *Destination,\r
2183 IN CONST CHAR8 *Source\r
2184 );\r
2185\r
2186\r
2187/**\r
ae591c14 2188 [ATTENTION] This function is deprecated for security reason.\r
1bb390f1 2189\r
9095d37b
LG
2190 Concatenates up to a specified length one Null-terminated ASCII string to\r
2191 the end of another Null-terminated ASCII string, and returns the\r
17f695ed 2192 concatenated ASCII string.\r
ac644614 2193\r
2194 This function concatenates two Null-terminated ASCII strings. The contents\r
2195 of Null-terminated ASCII string Source are concatenated to the end of Null-\r
2196 terminated ASCII string Destination, and Destination is returned. At most,\r
2197 Length ASCII characters are concatenated from Source to the end of\r
2198 Destination, and Destination is always Null-terminated. If Length is 0, then\r
2199 Destination is returned unmodified. If Source and Destination overlap, then\r
2200 the results are undefined.\r
2201\r
2202 If Length > 0 and Destination is NULL, then ASSERT().\r
2203 If Length > 0 and Source is NULL, then ASSERT().\r
2204 If Source and Destination overlap, then ASSERT().\r
50c247fd 2205 If PcdMaximumAsciiStringLength is not zero, and Length is greater than\r
2206 PcdMaximumAsciiStringLength, then ASSERT().\r
ac644614 2207 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than\r
50c247fd 2208 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r
ac644614 2209 then ASSERT().\r
2210 If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
50c247fd 2211 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,\r
ac644614 2212 then ASSERT().\r
2213 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and\r
2214 Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
50c247fd 2215 ASCII characters, not including the Null-terminator, then ASSERT().\r
ac644614 2216\r
af2dc6a7 2217 @param Destination The pointer to a Null-terminated ASCII string.\r
2218 @param Source The pointer to a Null-terminated ASCII string.\r
2219 @param Length The maximum number of ASCII characters to concatenate from\r
ac644614 2220 Source.\r
2221\r
2222 @return Destination\r
2223\r
2224**/\r
2225CHAR8 *\r
2226EFIAPI\r
2227AsciiStrnCat (\r
2228 IN OUT CHAR8 *Destination,\r
2229 IN CONST CHAR8 *Source,\r
2230 IN UINTN Length\r
2231 );\r
de4f7f52 2232#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
ac644614 2233\r
2234/**\r
9aa049d9 2235 Returns the first occurrence of a Null-terminated ASCII sub-string\r
ac644614 2236 in a Null-terminated ASCII string.\r
2237\r
2238 This function scans the contents of the ASCII string specified by String\r
2239 and returns the first occurrence of SearchString. If SearchString is not\r
2240 found in String, then NULL is returned. If the length of SearchString is zero,\r
2241 then String is returned.\r
2242\r
2243 If String is NULL, then ASSERT().\r
2244 If SearchString is NULL, then ASSERT().\r
2245\r
2246 If PcdMaximumAsciiStringLength is not zero, and SearchString or\r
2247 String contains more than PcdMaximumAsciiStringLength Unicode characters\r
2248 not including the Null-terminator, then ASSERT().\r
2249\r
af2dc6a7 2250 @param String The pointer to a Null-terminated ASCII string.\r
2251 @param SearchString The pointer to a Null-terminated ASCII string to search for.\r
ac644614 2252\r
2253 @retval NULL If the SearchString does not appear in String.\r
17f695ed 2254 @retval others If there is a match return the first occurrence of SearchingString.\r
9aa049d9 2255 If the length of SearchString is zero,return String.\r
ac644614 2256\r
2257**/\r
2258CHAR8 *\r
2259EFIAPI\r
2260AsciiStrStr (\r
17f695ed 2261 IN CONST CHAR8 *String,\r
2262 IN CONST CHAR8 *SearchString\r
ac644614 2263 );\r
2264\r
2265\r
2266/**\r
2267 Convert a Null-terminated ASCII decimal string to a value of type\r
2268 UINTN.\r
2269\r
2270 This function returns a value of type UINTN by interpreting the contents\r
2271 of the ASCII string String as a decimal number. The format of the input\r
2272 ASCII string String is:\r
2273\r
2274 [spaces] [decimal digits].\r
2275\r
2276 The valid decimal digit character is in the range [0-9]. The function will\r
2277 ignore the pad space, which includes spaces or tab characters, before the digits.\r
2278 The running zero in the beginning of [decimal digits] will be ignored. Then, the\r
2279 function stops at the first character that is a not a valid decimal character or\r
2280 Null-terminator, whichever on comes first.\r
2281\r
2282 If String has only pad spaces, then 0 is returned.\r
2283 If String has no pad spaces or valid decimal digits, then 0 is returned.\r
2284 If the number represented by String overflows according to the range defined by\r
ea2e0921 2285 UINTN, then MAX_UINTN is returned.\r
ac644614 2286 If String is NULL, then ASSERT().\r
2287 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
2288 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2289 then ASSERT().\r
2290\r
af2dc6a7 2291 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2292\r
af2dc6a7 2293 @retval The value translated from String.\r
ac644614 2294\r
2295**/\r
2296UINTN\r
2297EFIAPI\r
2298AsciiStrDecimalToUintn (\r
2299 IN CONST CHAR8 *String\r
2300 );\r
2301\r
2302\r
2303/**\r
2304 Convert a Null-terminated ASCII decimal string to a value of type\r
2305 UINT64.\r
2306\r
2307 This function returns a value of type UINT64 by interpreting the contents\r
2308 of the ASCII string String as a decimal number. The format of the input\r
2309 ASCII string String is:\r
2310\r
2311 [spaces] [decimal digits].\r
2312\r
2313 The valid decimal digit character is in the range [0-9]. The function will\r
2314 ignore the pad space, which includes spaces or tab characters, before the digits.\r
2315 The running zero in the beginning of [decimal digits] will be ignored. Then, the\r
2316 function stops at the first character that is a not a valid decimal character or\r
2317 Null-terminator, whichever on comes first.\r
2318\r
2319 If String has only pad spaces, then 0 is returned.\r
2320 If String has no pad spaces or valid decimal digits, then 0 is returned.\r
2321 If the number represented by String overflows according to the range defined by\r
ea2e0921 2322 UINT64, then MAX_UINT64 is returned.\r
ac644614 2323 If String is NULL, then ASSERT().\r
2324 If PcdMaximumAsciiStringLength is not zero, and String contains more than\r
2325 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2326 then ASSERT().\r
2327\r
af2dc6a7 2328 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2329\r
38bbd3d9 2330 @retval Value translated from String.\r
ac644614 2331\r
2332**/\r
2333UINT64\r
2334EFIAPI\r
2335AsciiStrDecimalToUint64 (\r
17f695ed 2336 IN CONST CHAR8 *String\r
ac644614 2337 );\r
2338\r
2339\r
2340/**\r
2341 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.\r
2342\r
2343 This function returns a value of type UINTN by interpreting the contents of\r
2344 the ASCII string String as a hexadecimal number. The format of the input ASCII\r
2345 string String is:\r
2346\r
2347 [spaces][zeros][x][hexadecimal digits].\r
2348\r
2349 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
2350 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"\r
2351 appears in the input string, it must be prefixed with at least one 0. The function\r
2352 will ignore the pad space, which includes spaces or tab characters, before [zeros],\r
2353 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]\r
2354 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal\r
2355 digit. Then, the function stops at the first character that is a not a valid\r
2356 hexadecimal character or Null-terminator, whichever on comes first.\r
2357\r
2358 If String has only pad spaces, then 0 is returned.\r
2359 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then\r
2360 0 is returned.\r
2361\r
2362 If the number represented by String overflows according to the range defined by UINTN,\r
ea2e0921 2363 then MAX_UINTN is returned.\r
ac644614 2364 If String is NULL, then ASSERT().\r
2365 If PcdMaximumAsciiStringLength is not zero,\r
2366 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including\r
2367 the Null-terminator, then ASSERT().\r
2368\r
af2dc6a7 2369 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2370\r
38bbd3d9 2371 @retval Value translated from String.\r
ac644614 2372\r
2373**/\r
2374UINTN\r
2375EFIAPI\r
2376AsciiStrHexToUintn (\r
17f695ed 2377 IN CONST CHAR8 *String\r
ac644614 2378 );\r
2379\r
2380\r
2381/**\r
2382 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.\r
2383\r
2384 This function returns a value of type UINT64 by interpreting the contents of\r
2385 the ASCII string String as a hexadecimal number. The format of the input ASCII\r
2386 string String is:\r
2387\r
2388 [spaces][zeros][x][hexadecimal digits].\r
2389\r
2390 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].\r
2391 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"\r
2392 appears in the input string, it must be prefixed with at least one 0. The function\r
2393 will ignore the pad space, which includes spaces or tab characters, before [zeros],\r
2394 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]\r
2395 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal\r
2396 digit. Then, the function stops at the first character that is a not a valid\r
2397 hexadecimal character or Null-terminator, whichever on comes first.\r
2398\r
2399 If String has only pad spaces, then 0 is returned.\r
2400 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then\r
2401 0 is returned.\r
2402\r
2403 If the number represented by String overflows according to the range defined by UINT64,\r
ea2e0921 2404 then MAX_UINT64 is returned.\r
ac644614 2405 If String is NULL, then ASSERT().\r
2406 If PcdMaximumAsciiStringLength is not zero,\r
2407 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including\r
2408 the Null-terminator, then ASSERT().\r
2409\r
af2dc6a7 2410 @param String The pointer to a Null-terminated ASCII string.\r
ac644614 2411\r
38bbd3d9 2412 @retval Value translated from String.\r
ac644614 2413\r
2414**/\r
2415UINT64\r
2416EFIAPI\r
2417AsciiStrHexToUint64 (\r
17f695ed 2418 IN CONST CHAR8 *String\r
ac644614 2419 );\r
2420\r
fb4dd857
RN
2421/**\r
2422 Convert a Null-terminated ASCII string to IPv6 address and prefix length.\r
2423\r
2424 This function outputs a value of type IPv6_ADDRESS and may output a value\r
2425 of type UINT8 by interpreting the contents of the ASCII string specified\r
2426 by String. The format of the input ASCII string String is as follows:\r
2427\r
2428 X:X:X:X:X:X:X:X[/P]\r
2429\r
2430 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and\r
2431 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low\r
2432 memory address and high byte is stored in high memory address. P contains decimal\r
2433 digit characters in the range [0-9]. The running zero in the beginning of P will\r
2434 be ignored. /P is optional.\r
2435\r
2436 When /P is not in the String, the function stops at the first character that is\r
2437 not a valid hexadecimal digit character after eight X's are converted.\r
2438\r
2439 When /P is in the String, the function stops at the first character that is not\r
2440 a valid decimal digit character after P is converted.\r
2441\r
2442 "::" can be used to compress one or more groups of X when X contains only 0.\r
2443 The "::" can only appear once in the String.\r
2444\r
2445 If String is NULL, then ASSERT().\r
2446\r
2447 If Address is NULL, then ASSERT().\r
2448\r
2449 If EndPointer is not NULL and Address is translated from String, a pointer\r
2450 to the character that stopped the scan is stored at the location pointed to\r
2451 by EndPointer.\r
2452\r
2453 @param String Pointer to a Null-terminated ASCII string.\r
2454 @param EndPointer Pointer to character that stops scan.\r
2455 @param Address Pointer to the converted IPv6 address.\r
2456 @param PrefixLength Pointer to the converted IPv6 address prefix\r
2457 length. MAX_UINT8 is returned when /P is\r
2458 not in the String.\r
2459\r
2460 @retval RETURN_SUCCESS Address is translated from String.\r
2461 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
2462 If Data is NULL.\r
2463 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal\r
2464 digit characters.\r
2465 If String contains "::" and number of X\r
2466 is not less than 8.\r
2467 If P starts with character that is not a\r
2468 valid decimal digit character.\r
2469 If the decimal number converted from P\r
2470 exceeds 128.\r
2471\r
2472**/\r
2473RETURN_STATUS\r
2474EFIAPI\r
2475AsciiStrToIpv6Address (\r
2476 IN CONST CHAR8 *String,\r
2477 OUT CHAR8 **EndPointer, OPTIONAL\r
2478 OUT IPv6_ADDRESS *Address,\r
2479 OUT UINT8 *PrefixLength OPTIONAL\r
2480 );\r
2481\r
2482/**\r
2483 Convert a Null-terminated ASCII string to IPv4 address and prefix length.\r
2484\r
2485 This function outputs a value of type IPv4_ADDRESS and may output a value\r
2486 of type UINT8 by interpreting the contents of the ASCII string specified\r
2487 by String. The format of the input ASCII string String is as follows:\r
2488\r
2489 D.D.D.D[/P]\r
2490\r
2491 D and P are decimal digit characters in the range [0-9]. The running zero in\r
2492 the beginning of D and P will be ignored. /P is optional.\r
2493\r
2494 When /P is not in the String, the function stops at the first character that is\r
2495 not a valid decimal digit character after four D's are converted.\r
2496\r
2497 When /P is in the String, the function stops at the first character that is not\r
2498 a valid decimal digit character after P is converted.\r
2499\r
2500 If String is NULL, then ASSERT().\r
2501\r
2502 If Address is NULL, then ASSERT().\r
2503\r
2504 If EndPointer is not NULL and Address is translated from String, a pointer\r
2505 to the character that stopped the scan is stored at the location pointed to\r
2506 by EndPointer.\r
2507\r
2508 @param String Pointer to a Null-terminated ASCII string.\r
2509 @param EndPointer Pointer to character that stops scan.\r
2510 @param Address Pointer to the converted IPv4 address.\r
2511 @param PrefixLength Pointer to the converted IPv4 address prefix\r
2512 length. MAX_UINT8 is returned when /P is\r
2513 not in the String.\r
2514\r
2515 @retval RETURN_SUCCESS Address is translated from String.\r
2516 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
2517 If Data is NULL.\r
2518 @retval RETURN_UNSUPPORTED If String is not in the correct format.\r
2519 If any decimal number converted from D\r
2520 exceeds 255.\r
2521 If the decimal number converted from P\r
2522 exceeds 32.\r
2523\r
2524**/\r
2525RETURN_STATUS\r
2526EFIAPI\r
2527AsciiStrToIpv4Address (\r
2528 IN CONST CHAR8 *String,\r
2529 OUT CHAR8 **EndPointer, OPTIONAL\r
2530 OUT IPv4_ADDRESS *Address,\r
2531 OUT UINT8 *PrefixLength OPTIONAL\r
2532 );\r
2533\r
2534/**\r
2535 Convert a Null-terminated ASCII GUID string to a value of type\r
2536 EFI_GUID.\r
2537\r
2538 This function outputs a GUID value by interpreting the contents of\r
2539 the ASCII string specified by String. The format of the input\r
2540 ASCII string String consists of 36 characters, as follows:\r
2541\r
2542 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp\r
2543\r
2544 The pairs aa - pp are two characters in the range [0-9], [a-f] and\r
2545 [A-F], with each pair representing a single byte hexadecimal value.\r
2546\r
2547 The mapping between String and the EFI_GUID structure is as follows:\r
2548 aa Data1[24:31]\r
2549 bb Data1[16:23]\r
2550 cc Data1[8:15]\r
2551 dd Data1[0:7]\r
2552 ee Data2[8:15]\r
2553 ff Data2[0:7]\r
2554 gg Data3[8:15]\r
2555 hh Data3[0:7]\r
2556 ii Data4[0:7]\r
2557 jj Data4[8:15]\r
2558 kk Data4[16:23]\r
2559 ll Data4[24:31]\r
2560 mm Data4[32:39]\r
2561 nn Data4[40:47]\r
2562 oo Data4[48:55]\r
2563 pp Data4[56:63]\r
2564\r
2565 If String is NULL, then ASSERT().\r
2566 If Guid is NULL, then ASSERT().\r
2567\r
2568 @param String Pointer to a Null-terminated ASCII string.\r
2569 @param Guid Pointer to the converted GUID.\r
2570\r
2571 @retval RETURN_SUCCESS Guid is translated from String.\r
2572 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
2573 If Data is NULL.\r
2574 @retval RETURN_UNSUPPORTED If String is not as the above format.\r
2575\r
2576**/\r
2577RETURN_STATUS\r
2578EFIAPI\r
2579AsciiStrToGuid (\r
2580 IN CONST CHAR8 *String,\r
2581 OUT GUID *Guid\r
2582 );\r
2583\r
2584/**\r
2585 Convert a Null-terminated ASCII hexadecimal string to a byte array.\r
2586\r
2587 This function outputs a byte array by interpreting the contents of\r
2588 the ASCII string specified by String in hexadecimal format. The format of\r
2589 the input ASCII string String is:\r
2590\r
2591 [XX]*\r
2592\r
2593 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].\r
2594 The function decodes every two hexadecimal digit characters as one byte. The\r
2595 decoding stops after Length of characters and outputs Buffer containing\r
2596 (Length / 2) bytes.\r
2597\r
2598 If String is NULL, then ASSERT().\r
2599\r
2600 If Buffer is NULL, then ASSERT().\r
2601\r
2602 If Length is not multiple of 2, then ASSERT().\r
2603\r
2604 If PcdMaximumAsciiStringLength is not zero and Length is greater than\r
2605 PcdMaximumAsciiStringLength, then ASSERT().\r
2606\r
2607 If MaxBufferSize is less than (Length / 2), then ASSERT().\r
2608\r
2609 @param String Pointer to a Null-terminated ASCII string.\r
2610 @param Length The number of ASCII characters to decode.\r
2611 @param Buffer Pointer to the converted bytes array.\r
2612 @param MaxBufferSize The maximum size of Buffer.\r
2613\r
2614 @retval RETURN_SUCCESS Buffer is translated from String.\r
2615 @retval RETURN_INVALID_PARAMETER If String is NULL.\r
2616 If Data is NULL.\r
2617 If Length is not multiple of 2.\r
2618 If PcdMaximumAsciiStringLength is not zero,\r
2619 and Length is greater than\r
2620 PcdMaximumAsciiStringLength.\r
2621 @retval RETURN_UNSUPPORTED If Length of characters from String contain\r
2622 a character that is not valid hexadecimal\r
2623 digit characters, or a Null-terminator.\r
2624 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).\r
2625**/\r
2626RETURN_STATUS\r
2627EFIAPI\r
2628AsciiStrHexToBytes (\r
2629 IN CONST CHAR8 *String,\r
2630 IN UINTN Length,\r
2631 OUT UINT8 *Buffer,\r
2632 IN UINTN MaxBufferSize\r
2633 );\r
2634\r
415aa2f1 2635#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
ac644614 2636\r
2637/**\r
415aa2f1
SZ
2638 [ATTENTION] This function is deprecated for security reason.\r
2639\r
ac644614 2640 Convert one Null-terminated ASCII string to a Null-terminated\r
2641 Unicode string and returns the Unicode string.\r
2642\r
2643 This function converts the contents of the ASCII string Source to the Unicode\r
2644 string Destination, and returns Destination. The function terminates the\r
2645 Unicode string Destination by appending a Null-terminator character at the end.\r
2646 The caller is responsible to make sure Destination points to a buffer with size\r
2647 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.\r
2648\r
2649 If Destination is NULL, then ASSERT().\r
2650 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
2651 If Source is NULL, then ASSERT().\r
2652 If Source and Destination overlap, then ASSERT().\r
2653 If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
2654 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
2655 then ASSERT().\r
2656 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
2657 PcdMaximumUnicodeStringLength ASCII characters not including the\r
2658 Null-terminator, then ASSERT().\r
2659\r
af2dc6a7 2660 @param Source The pointer to a Null-terminated ASCII string.\r
2661 @param Destination The pointer to a Null-terminated Unicode string.\r
ac644614 2662\r
9aa049d9 2663 @return Destination.\r
ac644614 2664\r
2665**/\r
2666CHAR16 *\r
2667EFIAPI\r
2668AsciiStrToUnicodeStr (\r
17f695ed 2669 IN CONST CHAR8 *Source,\r
2670 OUT CHAR16 *Destination\r
ac644614 2671 );\r
2672\r
de4f7f52 2673#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
415aa2f1 2674\r
3ab41b7a
JY
2675/**\r
2676 Convert one Null-terminated ASCII string to a Null-terminated\r
2677 Unicode string.\r
2678\r
2679 This function is similar to StrCpyS.\r
2680\r
2681 This function converts the contents of the ASCII string Source to the Unicode\r
2682 string Destination. The function terminates the Unicode string Destination by\r
2683 appending a Null-terminator character at the end.\r
2684\r
2685 The caller is responsible to make sure Destination points to a buffer with size\r
2686 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.\r
2687\r
2688 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
2689 If an error would be returned, then the function will also ASSERT().\r
2690\r
2691 If an error is returned, then the Destination is unmodified.\r
2692\r
2693 @param Source The pointer to a Null-terminated ASCII string.\r
2694 @param Destination The pointer to a Null-terminated Unicode string.\r
2695 @param DestMax The maximum number of Destination Unicode\r
2696 char, including terminating null char.\r
2697\r
2698 @retval RETURN_SUCCESS String is converted.\r
2699 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
2700 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
2701 If Source is NULL.\r
2702 If PcdMaximumUnicodeStringLength is not zero,\r
2703 and DestMax is greater than\r
2704 PcdMaximumUnicodeStringLength.\r
2705 If PcdMaximumAsciiStringLength is not zero,\r
2706 and DestMax is greater than\r
2707 PcdMaximumAsciiStringLength.\r
2708 If DestMax is 0.\r
2709 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
2710\r
2711**/\r
2712RETURN_STATUS\r
2713EFIAPI\r
2714AsciiStrToUnicodeStrS (\r
2715 IN CONST CHAR8 *Source,\r
2716 OUT CHAR16 *Destination,\r
2717 IN UINTN DestMax\r
2718 );\r
ac644614 2719\r
02263214
HW
2720/**\r
2721 Convert not more than Length successive characters from a Null-terminated\r
2722 Ascii string to a Null-terminated Unicode string. If no null char is copied\r
2723 from Source, then Destination[Length] is always set to null.\r
2724\r
2725 This function converts not more than Length successive characters from the\r
2726 Ascii string Source to the Unicode string Destination. The function\r
2727 terminates the Unicode string Destination by appending a Null-terminator\r
2728 character at the end.\r
2729\r
2730 The caller is responsible to make sure Destination points to a buffer with\r
2731 size not smaller than\r
2732 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.\r
2733\r
2734 If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
2735 If an error would be returned, then the function will also ASSERT().\r
2736\r
2737 If an error is returned, then Destination and DestinationLength are\r
2738 unmodified.\r
2739\r
2740 @param Source The pointer to a Null-terminated Ascii string.\r
2741 @param Length The maximum number of Ascii characters to convert.\r
2742 @param Destination The pointer to a Null-terminated Unicode string.\r
2743 @param DestMax The maximum number of Destination Unicode char,\r
2744 including terminating null char.\r
2745 @param DestinationLength The number of Ascii characters converted.\r
2746\r
2747 @retval RETURN_SUCCESS String is converted.\r
2748 @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
2749 If Source is NULL.\r
2750 If DestinationLength is NULL.\r
2751 If PcdMaximumUnicodeStringLength is not\r
2752 zero, and Length or DestMax is greater than\r
2753 PcdMaximumUnicodeStringLength.\r
2754 If PcdMaximumAsciiStringLength is not zero,\r
2755 and Length or DestMax is greater than\r
2756 PcdMaximumAsciiStringLength.\r
2757 If DestMax is 0.\r
2758 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than\r
2759 MIN(AsciiStrLen(Source), Length).\r
2760 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
2761\r
2762**/\r
2763RETURN_STATUS\r
2764EFIAPI\r
2765AsciiStrnToUnicodeStrS (\r
2766 IN CONST CHAR8 *Source,\r
2767 IN UINTN Length,\r
2768 OUT CHAR16 *Destination,\r
2769 IN UINTN DestMax,\r
2770 OUT UINTN *DestinationLength\r
2771 );\r
2772\r
ac644614 2773/**\r
2774 Converts an 8-bit value to an 8-bit BCD value.\r
2775\r
2776 Converts the 8-bit value specified by Value to BCD. The BCD value is\r
2777 returned.\r
2778\r
2779 If Value >= 100, then ASSERT().\r
2780\r
2781 @param Value The 8-bit value to convert to BCD. Range 0..99.\r
2782\r
9aa049d9 2783 @return The BCD value.\r
ac644614 2784\r
2785**/\r
2786UINT8\r
2787EFIAPI\r
2788DecimalToBcd8 (\r
2789 IN UINT8 Value\r
2790 );\r
2791\r
2792\r
2793/**\r
2794 Converts an 8-bit BCD value to an 8-bit value.\r
2795\r
2796 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit\r
2797 value is returned.\r
2798\r
2799 If Value >= 0xA0, then ASSERT().\r
2800 If (Value & 0x0F) >= 0x0A, then ASSERT().\r
2801\r
2802 @param Value The 8-bit BCD value to convert to an 8-bit value.\r
2803\r
2804 @return The 8-bit value is returned.\r
2805\r
2806**/\r
2807UINT8\r
2808EFIAPI\r
2809BcdToDecimal8 (\r
2810 IN UINT8 Value\r
2811 );\r
2812\r
ae591c14
DM
2813//\r
2814// File Path Manipulation Functions\r
2815//\r
2816\r
2817/**\r
6a623094 2818 Removes the last directory or file entry in a path.\r
ae591c14
DM
2819\r
2820 @param[in, out] Path The pointer to the path to modify.\r
2821\r
2822 @retval FALSE Nothing was found to remove.\r
2823 @retval TRUE A directory or file was removed.\r
2824**/\r
2825BOOLEAN\r
2826EFIAPI\r
2827PathRemoveLastItem(\r
2828 IN OUT CHAR16 *Path\r
2829 );\r
2830\r
2831/**\r
2832 Function to clean up paths.\r
2833 - Single periods in the path are removed.\r
2834 - Double periods in the path are removed along with a single parent directory.\r
2835 - Forward slashes L'/' are converted to backward slashes L'\'.\r
2836\r
2837 This will be done inline and the existing buffer may be larger than required\r
2838 upon completion.\r
2839\r
2840 @param[in] Path The pointer to the string containing the path.\r
2841\r
00b7cc0f 2842 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.\r
ae591c14
DM
2843**/\r
2844CHAR16*\r
2845EFIAPI\r
2846PathCleanUpDirectories(\r
2847 IN CHAR16 *Path\r
909ac47b 2848 );\r
ac644614 2849\r
2850//\r
2851// Linked List Functions and Macros\r
2852//\r
2853\r
2854/**\r
2855 Initializes the head node of a doubly linked list that is declared as a\r
2856 global variable in a module.\r
2857\r
2858 Initializes the forward and backward links of a new linked list. After\r
2859 initializing a linked list with this macro, the other linked list functions\r
2860 may be used to add and remove nodes from the linked list. This macro results\r
2861 in smaller executables by initializing the linked list in the data section,\r
2862 instead if calling the InitializeListHead() function to perform the\r
2863 equivalent operation.\r
2864\r
77f863ee 2865 @param ListHead The head note of a list to initialize.\r
ac644614 2866\r
2867**/\r
17f695ed 2868#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}\r
ac644614 2869\r
2870\r
d0aef615
MH
2871/**\r
2872 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked\r
2873 list.\r
2874\r
2875 If FirstEntry is NULL, then ASSERT().\r
2876 If FirstEntry->ForwardLink is NULL, then ASSERT().\r
2877 If FirstEntry->BackLink is NULL, then ASSERT().\r
2878 If SecondEntry is NULL, then ASSERT();\r
2879 If PcdMaximumLinkedListLength is not zero, and List contains more than\r
2880 PcdMaximumLinkedListLength nodes, then ASSERT().\r
2881\r
2882 @param FirstEntry A pointer to a node in a linked list.\r
2883 @param SecondEntry A pointer to the node to locate.\r
2884\r
2885 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.\r
2886 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,\r
2887 or FirstEntry is invalid.\r
2888\r
2889**/\r
2890BOOLEAN\r
2891EFIAPI\r
2892IsNodeInList (\r
2893 IN CONST LIST_ENTRY *FirstEntry,\r
2894 IN CONST LIST_ENTRY *SecondEntry\r
2895 );\r
2896\r
2897\r
ac644614 2898/**\r
2899 Initializes the head node of a doubly linked list, and returns the pointer to\r
2900 the head node of the doubly linked list.\r
2901\r
2902 Initializes the forward and backward links of a new linked list. After\r
2903 initializing a linked list with this function, the other linked list\r
2904 functions may be used to add and remove nodes from the linked list. It is up\r
2905 to the caller of this function to allocate the memory for ListHead.\r
2906\r
2907 If ListHead is NULL, then ASSERT().\r
2908\r
2909 @param ListHead A pointer to the head node of a new doubly linked list.\r
2910\r
2911 @return ListHead\r
2912\r
2913**/\r
2914LIST_ENTRY *\r
2915EFIAPI\r
2916InitializeListHead (\r
aa0583c7 2917 IN OUT LIST_ENTRY *ListHead\r
ac644614 2918 );\r
2919\r
2920\r
2921/**\r
2922 Adds a node to the beginning of a doubly linked list, and returns the pointer\r
2923 to the head node of the doubly linked list.\r
2924\r
2925 Adds the node Entry at the beginning of the doubly linked list denoted by\r
2926 ListHead, and returns ListHead.\r
2927\r
2928 If ListHead is NULL, then ASSERT().\r
2929 If Entry is NULL, then ASSERT().\r
17f695ed 2930 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
2931 InitializeListHead(), then ASSERT().\r
a71865b1 2932 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number\r
ac644614 2933 of nodes in ListHead, including the ListHead node, is greater than or\r
2934 equal to PcdMaximumLinkedListLength, then ASSERT().\r
2935\r
2936 @param ListHead A pointer to the head node of a doubly linked list.\r
2937 @param Entry A pointer to a node that is to be inserted at the beginning\r
2938 of a doubly linked list.\r
2939\r
2940 @return ListHead\r
2941\r
2942**/\r
2943LIST_ENTRY *\r
2944EFIAPI\r
2945InsertHeadList (\r
aa0583c7 2946 IN OUT LIST_ENTRY *ListHead,\r
2947 IN OUT LIST_ENTRY *Entry\r
ac644614 2948 );\r
2949\r
2950\r
2951/**\r
2952 Adds a node to the end of a doubly linked list, and returns the pointer to\r
2953 the head node of the doubly linked list.\r
2954\r
2955 Adds the node Entry to the end of the doubly linked list denoted by ListHead,\r
2956 and returns ListHead.\r
2957\r
2958 If ListHead is NULL, then ASSERT().\r
2959 If Entry is NULL, then ASSERT().\r
9095d37b 2960 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
17f695ed 2961 InitializeListHead(), then ASSERT().\r
a71865b1 2962 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number\r
ac644614 2963 of nodes in ListHead, including the ListHead node, is greater than or\r
2964 equal to PcdMaximumLinkedListLength, then ASSERT().\r
2965\r
2966 @param ListHead A pointer to the head node of a doubly linked list.\r
2967 @param Entry A pointer to a node that is to be added at the end of the\r
2968 doubly linked list.\r
2969\r
2970 @return ListHead\r
2971\r
2972**/\r
2973LIST_ENTRY *\r
2974EFIAPI\r
2975InsertTailList (\r
aa0583c7 2976 IN OUT LIST_ENTRY *ListHead,\r
2977 IN OUT LIST_ENTRY *Entry\r
ac644614 2978 );\r
2979\r
2980\r
2981/**\r
2982 Retrieves the first node of a doubly linked list.\r
2983\r
9095d37b 2984 Returns the first node of a doubly linked list. List must have been\r
17f695ed 2985 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
2986 If List is empty, then List is returned.\r
ac644614 2987\r
2988 If List is NULL, then ASSERT().\r
9095d37b 2989 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
17f695ed 2990 InitializeListHead(), then ASSERT().\r
a71865b1 2991 If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
ac644614 2992 in List, including the List node, is greater than or equal to\r
2993 PcdMaximumLinkedListLength, then ASSERT().\r
2994\r
2995 @param List A pointer to the head node of a doubly linked list.\r
2996\r
2997 @return The first node of a doubly linked list.\r
e01a125f 2998 @retval List The list is empty.\r
ac644614 2999\r
3000**/\r
3001LIST_ENTRY *\r
3002EFIAPI\r
3003GetFirstNode (\r
3004 IN CONST LIST_ENTRY *List\r
3005 );\r
3006\r
3007\r
3008/**\r
3009 Retrieves the next node of a doubly linked list.\r
3010\r
9095d37b 3011 Returns the node of a doubly linked list that follows Node.\r
17f695ed 3012 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()\r
3013 or InitializeListHead(). If List is empty, then List is returned.\r
ac644614 3014\r
3015 If List is NULL, then ASSERT().\r
3016 If Node is NULL, then ASSERT().\r
9095d37b 3017 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
17f695ed 3018 InitializeListHead(), then ASSERT().\r
a71865b1
LG
3019 If PcdMaximumLinkedListLength is not zero, and List contains more than\r
3020 PcdMaximumLinkedListLength nodes, then ASSERT().\r
1081f624 3021 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
ac644614 3022\r
3023 @param List A pointer to the head node of a doubly linked list.\r
3024 @param Node A pointer to a node in the doubly linked list.\r
3025\r
af2dc6a7 3026 @return The pointer to the next node if one exists. Otherwise List is returned.\r
ac644614 3027\r
3028**/\r
3029LIST_ENTRY *\r
3030EFIAPI\r
3031GetNextNode (\r
3032 IN CONST LIST_ENTRY *List,\r
3033 IN CONST LIST_ENTRY *Node\r
3034 );\r
3035\r
9095d37b 3036\r
cbca8de5 3037/**\r
3038 Retrieves the previous node of a doubly linked list.\r
9095d37b
LG
3039\r
3040 Returns the node of a doubly linked list that precedes Node.\r
cbca8de5 3041 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()\r
3042 or InitializeListHead(). If List is empty, then List is returned.\r
9095d37b 3043\r
cbca8de5 3044 If List is NULL, then ASSERT().\r
3045 If Node is NULL, then ASSERT().\r
9095d37b 3046 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
cbca8de5 3047 InitializeListHead(), then ASSERT().\r
a71865b1
LG
3048 If PcdMaximumLinkedListLength is not zero, and List contains more than\r
3049 PcdMaximumLinkedListLength nodes, then ASSERT().\r
cbca8de5 3050 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
9095d37b 3051\r
cbca8de5 3052 @param List A pointer to the head node of a doubly linked list.\r
3053 @param Node A pointer to a node in the doubly linked list.\r
9095d37b 3054\r
af2dc6a7 3055 @return The pointer to the previous node if one exists. Otherwise List is returned.\r
9095d37b 3056\r
cbca8de5 3057**/\r
3058LIST_ENTRY *\r
3059EFIAPI\r
3060GetPreviousNode (\r
3061 IN CONST LIST_ENTRY *List,\r
3062 IN CONST LIST_ENTRY *Node\r
3063 );\r
ac644614 3064\r
9095d37b 3065\r
ac644614 3066/**\r
3067 Checks to see if a doubly linked list is empty or not.\r
3068\r
3069 Checks to see if the doubly linked list is empty. If the linked list contains\r
3070 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.\r
3071\r
3072 If ListHead is NULL, then ASSERT().\r
9095d37b 3073 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
17f695ed 3074 InitializeListHead(), then ASSERT().\r
a71865b1 3075 If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
ac644614 3076 in List, including the List node, is greater than or equal to\r
3077 PcdMaximumLinkedListLength, then ASSERT().\r
3078\r
3079 @param ListHead A pointer to the head node of a doubly linked list.\r
3080\r
3081 @retval TRUE The linked list is empty.\r
3082 @retval FALSE The linked list is not empty.\r
3083\r
3084**/\r
3085BOOLEAN\r
3086EFIAPI\r
3087IsListEmpty (\r
3088 IN CONST LIST_ENTRY *ListHead\r
3089 );\r
3090\r
3091\r
3092/**\r
aa0583c7 3093 Determines if a node in a doubly linked list is the head node of a the same\r
3094 doubly linked list. This function is typically used to terminate a loop that\r
3095 traverses all the nodes in a doubly linked list starting with the head node.\r
ac644614 3096\r
aa0583c7 3097 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the\r
3098 nodes in the doubly linked list specified by List. List must have been\r
17f695ed 3099 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
ac644614 3100\r
3101 If List is NULL, then ASSERT().\r
3102 If Node is NULL, then ASSERT().\r
9095d37b 3103 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),\r
17f695ed 3104 then ASSERT().\r
a71865b1 3105 If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
ac644614 3106 in List, including the List node, is greater than or equal to\r
3107 PcdMaximumLinkedListLength, then ASSERT().\r
9095d37b 3108 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal\r
1081f624 3109 to List, then ASSERT().\r
ac644614 3110\r
3111 @param List A pointer to the head node of a doubly linked list.\r
3112 @param Node A pointer to a node in the doubly linked list.\r
3113\r
1955808d
LG
3114 @retval TRUE Node is the head of the doubly-linked list pointed by List.\r
3115 @retval FALSE Node is not the head of the doubly-linked list pointed by List.\r
ac644614 3116\r
3117**/\r
3118BOOLEAN\r
3119EFIAPI\r
3120IsNull (\r
3121 IN CONST LIST_ENTRY *List,\r
3122 IN CONST LIST_ENTRY *Node\r
3123 );\r
3124\r
3125\r
3126/**\r
3127 Determines if a node the last node in a doubly linked list.\r
3128\r
3129 Returns TRUE if Node is the last node in the doubly linked list specified by\r
3130 List. Otherwise, FALSE is returned. List must have been initialized with\r
17f695ed 3131 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
ac644614 3132\r
3133 If List is NULL, then ASSERT().\r
3134 If Node is NULL, then ASSERT().\r
17f695ed 3135 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
3136 InitializeListHead(), then ASSERT().\r
a71865b1 3137 If PcdMaximumLinkedListLength is not zero, and the number of nodes\r
ac644614 3138 in List, including the List node, is greater than or equal to\r
3139 PcdMaximumLinkedListLength, then ASSERT().\r
1081f624 3140 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().\r
ac644614 3141\r
3142 @param List A pointer to the head node of a doubly linked list.\r
3143 @param Node A pointer to a node in the doubly linked list.\r
3144\r
3145 @retval TRUE Node is the last node in the linked list.\r
3146 @retval FALSE Node is not the last node in the linked list.\r
3147\r
3148**/\r
3149BOOLEAN\r
3150EFIAPI\r
3151IsNodeAtEnd (\r
3152 IN CONST LIST_ENTRY *List,\r
3153 IN CONST LIST_ENTRY *Node\r
3154 );\r
3155\r
3156\r
3157/**\r
3158 Swaps the location of two nodes in a doubly linked list, and returns the\r
3159 first node after the swap.\r
3160\r
3161 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.\r
3162 Otherwise, the location of the FirstEntry node is swapped with the location\r
3163 of the SecondEntry node in a doubly linked list. SecondEntry must be in the\r
3164 same double linked list as FirstEntry and that double linked list must have\r
9095d37b 3165 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
17f695ed 3166 SecondEntry is returned after the nodes are swapped.\r
ac644614 3167\r
3168 If FirstEntry is NULL, then ASSERT().\r
3169 If SecondEntry is NULL, then ASSERT().\r
9095d37b 3170 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the\r
1081f624 3171 same linked list, then ASSERT().\r
ac644614 3172 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the\r
3173 linked list containing the FirstEntry and SecondEntry nodes, including\r
3174 the FirstEntry and SecondEntry nodes, is greater than or equal to\r
3175 PcdMaximumLinkedListLength, then ASSERT().\r
3176\r
3177 @param FirstEntry A pointer to a node in a linked list.\r
3178 @param SecondEntry A pointer to another node in the same linked list.\r
9095d37b 3179\r
9aa049d9 3180 @return SecondEntry.\r
ac644614 3181\r
3182**/\r
3183LIST_ENTRY *\r
3184EFIAPI\r
3185SwapListEntries (\r
aa0583c7 3186 IN OUT LIST_ENTRY *FirstEntry,\r
3187 IN OUT LIST_ENTRY *SecondEntry\r
ac644614 3188 );\r
3189\r
3190\r
3191/**\r
3192 Removes a node from a doubly linked list, and returns the node that follows\r
3193 the removed node.\r
3194\r
3195 Removes the node Entry from a doubly linked list. It is up to the caller of\r
3196 this function to release the memory used by this node if that is required. On\r
3197 exit, the node following Entry in the doubly linked list is returned. If\r
3198 Entry is the only node in the linked list, then the head node of the linked\r
3199 list is returned.\r
3200\r
3201 If Entry is NULL, then ASSERT().\r