4 Copyright (c) 2014 - 2019, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #include "BaseLibInternals.h"
11 #define RSIZE_MAX (PcdGet32 (PcdMaximumUnicodeStringLength))
13 #define ASCII_RSIZE_MAX (PcdGet32 (PcdMaximumAsciiStringLength))
15 #define SAFE_STRING_CONSTRAINT_CHECK(Expression, Status) \
17 if (!(Expression)) { \
18 DEBUG ((DEBUG_VERBOSE, \
19 "%a(%d) %a: SAFE_STRING_CONSTRAINT_CHECK(%a) failed. Return %r\n", \
20 __FILE__, DEBUG_LINE_NUMBER, __FUNCTION__, DEBUG_EXPRESSION_STRING (Expression), Status)); \
26 Returns if 2 memory blocks are overlapped.
28 @param Base1 Base address of 1st memory block.
29 @param Size1 Size of 1st memory block.
30 @param Base2 Base address of 2nd memory block.
31 @param Size2 Size of 2nd memory block.
33 @retval TRUE 2 memory blocks are overlapped.
34 @retval FALSE 2 memory blocks are not overlapped.
37 InternalSafeStringIsOverlap (
44 if ((((UINTN
)Base1
>= (UINTN
)Base2
) && ((UINTN
)Base1
< (UINTN
)Base2
+ Size2
)) ||
45 (((UINTN
)Base2
>= (UINTN
)Base1
) && ((UINTN
)Base2
< (UINTN
)Base1
+ Size1
)))
54 Returns if 2 Unicode strings are not overlapped.
56 @param Str1 Start address of 1st Unicode string.
57 @param Size1 The number of char in 1st Unicode string,
58 including terminating null char.
59 @param Str2 Start address of 2nd Unicode string.
60 @param Size2 The number of char in 2nd Unicode string,
61 including terminating null char.
63 @retval TRUE 2 Unicode strings are NOT overlapped.
64 @retval FALSE 2 Unicode strings are overlapped.
67 InternalSafeStringNoStrOverlap (
74 return !InternalSafeStringIsOverlap (Str1
, Size1
* sizeof (CHAR16
), Str2
, Size2
* sizeof (CHAR16
));
78 Returns if 2 Ascii strings are not overlapped.
80 @param Str1 Start address of 1st Ascii string.
81 @param Size1 The number of char in 1st Ascii string,
82 including terminating null char.
83 @param Str2 Start address of 2nd Ascii string.
84 @param Size2 The number of char in 2nd Ascii string,
85 including terminating null char.
87 @retval TRUE 2 Ascii strings are NOT overlapped.
88 @retval FALSE 2 Ascii strings are overlapped.
91 InternalSafeStringNoAsciiStrOverlap (
98 return !InternalSafeStringIsOverlap (Str1
, Size1
, Str2
, Size2
);
102 Returns the length of a Null-terminated Unicode string.
104 This function is similar as strlen_s defined in C11.
106 If String is not aligned on a 16-bit boundary, then ASSERT().
108 @param String A pointer to a Null-terminated Unicode string.
109 @param MaxSize The maximum number of Destination Unicode
110 char, including terminating null char.
112 @retval 0 If String is NULL.
113 @retval MaxSize If there is no null character in the first MaxSize characters of String.
114 @return The number of characters that percede the terminating null character.
120 IN CONST CHAR16
*String
,
126 ASSERT (((UINTN
)String
& BIT0
) == 0);
129 // If String is a null pointer or MaxSize is 0, then the StrnLenS function returns zero.
131 if ((String
== NULL
) || (MaxSize
== 0)) {
136 // Otherwise, the StrnLenS function returns the number of characters that precede the
137 // terminating null character. If there is no null character in the first MaxSize characters of
138 // String then StrnLenS returns MaxSize. At most the first MaxSize characters of String shall
139 // be accessed by StrnLenS.
142 while (String
[Length
] != 0) {
143 if (Length
>= MaxSize
- 1) {
154 Returns the size of a Null-terminated Unicode string in bytes, including the
157 This function returns the size of the Null-terminated Unicode string
158 specified by String in bytes, including the Null terminator.
160 If String is not aligned on a 16-bit boundary, then ASSERT().
162 @param String A pointer to a Null-terminated Unicode string.
163 @param MaxSize The maximum number of Destination Unicode
164 char, including the Null terminator.
166 @retval 0 If String is NULL.
167 @retval (sizeof (CHAR16) * (MaxSize + 1))
168 If there is no Null terminator in the first MaxSize characters of
170 @return The size of the Null-terminated Unicode string in bytes, including
177 IN CONST CHAR16
*String
,
182 // If String is a null pointer, then the StrnSizeS function returns zero.
184 if (String
== NULL
) {
189 // Otherwise, the StrnSizeS function returns the size of the Null-terminated
190 // Unicode string in bytes, including the Null terminator. If there is no
191 // Null terminator in the first MaxSize characters of String, then StrnSizeS
192 // returns (sizeof (CHAR16) * (MaxSize + 1)) to keep a consistent map with
193 // the StrnLenS function.
195 return (StrnLenS (String
, MaxSize
) + 1) * sizeof (*String
);
199 Copies the string pointed to by Source (including the terminating null char)
200 to the array pointed to by Destination.
202 This function is similar as strcpy_s defined in C11.
204 If Destination is not aligned on a 16-bit boundary, then ASSERT().
205 If Source is not aligned on a 16-bit boundary, then ASSERT().
207 If an error is returned, then the Destination is unmodified.
209 @param Destination A pointer to a Null-terminated Unicode string.
210 @param DestMax The maximum number of Destination Unicode
211 char, including terminating null char.
212 @param Source A pointer to a Null-terminated Unicode string.
214 @retval RETURN_SUCCESS String is copied.
215 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
216 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
218 If PcdMaximumUnicodeStringLength is not zero,
219 and DestMax is greater than
220 PcdMaximumUnicodeStringLength.
222 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
227 OUT CHAR16
*Destination
,
229 IN CONST CHAR16
*Source
234 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
235 ASSERT (((UINTN
)Source
& BIT0
) == 0);
238 // 1. Neither Destination nor Source shall be a null pointer.
240 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
241 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
244 // 2. DestMax shall not be greater than RSIZE_MAX.
246 if (RSIZE_MAX
!= 0) {
247 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
251 // 3. DestMax shall not equal zero.
253 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
256 // 4. DestMax shall be greater than StrnLenS(Source, DestMax).
258 SourceLen
= StrnLenS (Source
, DestMax
);
259 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
262 // 5. Copying shall not take place between objects that overlap.
264 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
267 // The StrCpyS function copies the string pointed to by Source (including the terminating
268 // null character) into the array pointed to by Destination.
270 while (*Source
!= 0) {
271 *(Destination
++) = *(Source
++);
276 return RETURN_SUCCESS
;
280 Copies not more than Length successive char from the string pointed to by
281 Source to the array pointed to by Destination. If no null char is copied from
282 Source, then Destination[Length] is always set to null.
284 This function is similar as strncpy_s defined in C11.
286 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
287 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
289 If an error is returned, then the Destination is unmodified.
291 @param Destination A pointer to a Null-terminated Unicode string.
292 @param DestMax The maximum number of Destination Unicode
293 char, including terminating null char.
294 @param Source A pointer to a Null-terminated Unicode string.
295 @param Length The maximum number of Unicode characters to copy.
297 @retval RETURN_SUCCESS String is copied.
298 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
299 MIN(StrLen(Source), Length).
300 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
302 If PcdMaximumUnicodeStringLength is not zero,
303 and DestMax is greater than
304 PcdMaximumUnicodeStringLength.
306 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
311 OUT CHAR16
*Destination
,
313 IN CONST CHAR16
*Source
,
319 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
320 ASSERT (((UINTN
)Source
& BIT0
) == 0);
323 // 1. Neither Destination nor Source shall be a null pointer.
325 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
326 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
329 // 2. Neither DestMax nor Length shall be greater than RSIZE_MAX
331 if (RSIZE_MAX
!= 0) {
332 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
333 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
337 // 3. DestMax shall not equal zero.
339 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
342 // 4. If Length is not less than DestMax, then DestMax shall be greater than StrnLenS(Source, DestMax).
344 SourceLen
= StrnLenS (Source
, MIN (DestMax
, Length
));
345 if (Length
>= DestMax
) {
346 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
350 // 5. Copying shall not take place between objects that overlap.
352 if (SourceLen
> Length
) {
356 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
359 // The StrnCpyS function copies not more than Length successive characters (characters that
360 // follow a null character are not copied) from the array pointed to by Source to the array
361 // pointed to by Destination. If no null character was copied from Source, then Destination[Length] is set to a null
364 while ((SourceLen
> 0) && (*Source
!= 0)) {
365 *(Destination
++) = *(Source
++);
371 return RETURN_SUCCESS
;
375 Appends a copy of the string pointed to by Source (including the terminating
376 null char) to the end of the string pointed to by Destination.
378 This function is similar as strcat_s defined in C11.
380 If Destination is not aligned on a 16-bit boundary, then ASSERT().
381 If Source is not aligned on a 16-bit boundary, then ASSERT().
383 If an error is returned, then the Destination is unmodified.
385 @param Destination A pointer to a Null-terminated Unicode string.
386 @param DestMax The maximum number of Destination Unicode
387 char, including terminating null char.
388 @param Source A pointer to a Null-terminated Unicode string.
390 @retval RETURN_SUCCESS String is appended.
391 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
393 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
394 greater than StrLen(Source).
395 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
397 If PcdMaximumUnicodeStringLength is not zero,
398 and DestMax is greater than
399 PcdMaximumUnicodeStringLength.
401 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
406 IN OUT CHAR16
*Destination
,
408 IN CONST CHAR16
*Source
415 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
416 ASSERT (((UINTN
)Source
& BIT0
) == 0);
419 // Let CopyLen denote the value DestMax - StrnLenS(Destination, DestMax) upon entry to StrCatS.
421 DestLen
= StrnLenS (Destination
, DestMax
);
422 CopyLen
= DestMax
- DestLen
;
425 // 1. Neither Destination nor Source shall be a null pointer.
427 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
428 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
431 // 2. DestMax shall not be greater than RSIZE_MAX.
433 if (RSIZE_MAX
!= 0) {
434 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
438 // 3. DestMax shall not equal zero.
440 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
443 // 4. CopyLen shall not equal zero.
445 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
448 // 5. CopyLen shall be greater than StrnLenS(Source, CopyLen).
450 SourceLen
= StrnLenS (Source
, CopyLen
);
451 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
454 // 6. Copying shall not take place between objects that overlap.
456 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
459 // The StrCatS function appends a copy of the string pointed to by Source (including the
460 // terminating null character) to the end of the string pointed to by Destination. The initial character
461 // from Source overwrites the null character at the end of Destination.
463 Destination
= Destination
+ DestLen
;
464 while (*Source
!= 0) {
465 *(Destination
++) = *(Source
++);
470 return RETURN_SUCCESS
;
474 Appends not more than Length successive char from the string pointed to by
475 Source to the end of the string pointed to by Destination. If no null char is
476 copied from Source, then Destination[StrLen(Destination) + Length] is always
479 This function is similar as strncat_s defined in C11.
481 If Destination is not aligned on a 16-bit boundary, then ASSERT().
482 If Source is not aligned on a 16-bit boundary, then ASSERT().
484 If an error is returned, then the Destination is unmodified.
486 @param Destination A pointer to a Null-terminated Unicode string.
487 @param DestMax The maximum number of Destination Unicode
488 char, including terminating null char.
489 @param Source A pointer to a Null-terminated Unicode string.
490 @param Length The maximum number of Unicode characters to copy.
492 @retval RETURN_SUCCESS String is appended.
493 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
495 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
496 greater than MIN(StrLen(Source), Length).
497 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
499 If PcdMaximumUnicodeStringLength is not zero,
500 and DestMax is greater than
501 PcdMaximumUnicodeStringLength.
503 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
508 IN OUT CHAR16
*Destination
,
510 IN CONST CHAR16
*Source
,
518 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
519 ASSERT (((UINTN
)Source
& BIT0
) == 0);
522 // Let CopyLen denote the value DestMax - StrnLenS(Destination, DestMax) upon entry to StrnCatS.
524 DestLen
= StrnLenS (Destination
, DestMax
);
525 CopyLen
= DestMax
- DestLen
;
528 // 1. Neither Destination nor Source shall be a null pointer.
530 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
531 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
534 // 2. Neither DestMax nor Length shall be greater than RSIZE_MAX.
536 if (RSIZE_MAX
!= 0) {
537 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
538 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
542 // 3. DestMax shall not equal zero.
544 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
547 // 4. CopyLen shall not equal zero.
549 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
552 // 5. If Length is not less than CopyLen, then CopyLen shall be greater than StrnLenS(Source, CopyLen).
554 SourceLen
= StrnLenS (Source
, MIN (CopyLen
, Length
));
555 if (Length
>= CopyLen
) {
556 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
560 // 6. Copying shall not take place between objects that overlap.
562 if (SourceLen
> Length
) {
566 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
569 // The StrnCatS function appends not more than Length successive characters (characters
570 // that follow a null character are not copied) from the array pointed to by Source to the end of
571 // the string pointed to by Destination. The initial character from Source overwrites the null character at
572 // the end of Destination. If no null character was copied from Source, then Destination[DestMax-CopyLen+Length] is set to
575 Destination
= Destination
+ DestLen
;
576 while ((SourceLen
> 0) && (*Source
!= 0)) {
577 *(Destination
++) = *(Source
++);
583 return RETURN_SUCCESS
;
587 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
589 This function outputs a value of type UINTN by interpreting the contents of
590 the Unicode string specified by String as a decimal number. The format of the
591 input Unicode string String is:
593 [spaces] [decimal digits].
595 The valid decimal digit character is in the range [0-9]. The function will
596 ignore the pad space, which includes spaces or tab characters, before
597 [decimal digits]. The running zero in the beginning of [decimal digits] will
598 be ignored. Then, the function stops at the first character that is a not a
599 valid decimal character or a Null-terminator, whichever one comes first.
601 If String is not aligned in a 16-bit boundary, then ASSERT().
603 If String has no valid decimal digits in the above format, then 0 is stored
604 at the location pointed to by Data.
605 If the number represented by String exceeds the range defined by UINTN, then
606 MAX_UINTN is stored at the location pointed to by Data.
608 If EndPointer is not NULL, a pointer to the character that stopped the scan
609 is stored at the location pointed to by EndPointer. If String has no valid
610 decimal digits right after the optional pad spaces, the value of String is
611 stored at the location pointed to by EndPointer.
613 @param String Pointer to a Null-terminated Unicode string.
614 @param EndPointer Pointer to character that stops scan.
615 @param Data Pointer to the converted value.
617 @retval RETURN_SUCCESS Value is translated from String.
618 @retval RETURN_INVALID_PARAMETER If String is NULL.
620 If PcdMaximumUnicodeStringLength is not
621 zero, and String contains more than
622 PcdMaximumUnicodeStringLength Unicode
623 characters, not including the
625 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
626 the range defined by UINTN.
632 IN CONST CHAR16
*String
,
633 OUT CHAR16
**EndPointer OPTIONAL
,
637 ASSERT (((UINTN
)String
& BIT0
) == 0);
640 // 1. Neither String nor Data shall be a null pointer.
642 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
643 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
646 // 2. The length of String shall not be greater than RSIZE_MAX.
648 if (RSIZE_MAX
!= 0) {
649 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
652 if (EndPointer
!= NULL
) {
653 *EndPointer
= (CHAR16
*)String
;
657 // Ignore the pad spaces (space or tab)
659 while ((*String
== L
' ') || (*String
== L
'\t')) {
664 // Ignore leading Zeros after the spaces
666 while (*String
== L
'0') {
672 while (InternalIsDecimalDigitCharacter (*String
)) {
674 // If the number represented by String overflows according to the range
675 // defined by UINTN, then MAX_UINTN is stored in *Data and
676 // RETURN_UNSUPPORTED is returned.
678 if (*Data
> ((MAX_UINTN
- (*String
- L
'0')) / 10)) {
680 if (EndPointer
!= NULL
) {
681 *EndPointer
= (CHAR16
*)String
;
684 return RETURN_UNSUPPORTED
;
687 *Data
= *Data
* 10 + (*String
- L
'0');
691 if (EndPointer
!= NULL
) {
692 *EndPointer
= (CHAR16
*)String
;
695 return RETURN_SUCCESS
;
699 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
701 This function outputs a value of type UINT64 by interpreting the contents of
702 the Unicode string specified by String as a decimal number. The format of the
703 input Unicode string String is:
705 [spaces] [decimal digits].
707 The valid decimal digit character is in the range [0-9]. The function will
708 ignore the pad space, which includes spaces or tab characters, before
709 [decimal digits]. The running zero in the beginning of [decimal digits] will
710 be ignored. Then, the function stops at the first character that is a not a
711 valid decimal character or a Null-terminator, whichever one comes first.
713 If String is not aligned in a 16-bit boundary, then ASSERT().
715 If String has no valid decimal digits in the above format, then 0 is stored
716 at the location pointed to by Data.
717 If the number represented by String exceeds the range defined by UINT64, then
718 MAX_UINT64 is stored at the location pointed to by Data.
720 If EndPointer is not NULL, a pointer to the character that stopped the scan
721 is stored at the location pointed to by EndPointer. If String has no valid
722 decimal digits right after the optional pad spaces, the value of String is
723 stored at the location pointed to by EndPointer.
725 @param String Pointer to a Null-terminated Unicode string.
726 @param EndPointer Pointer to character that stops scan.
727 @param Data Pointer to the converted value.
729 @retval RETURN_SUCCESS Value is translated from String.
730 @retval RETURN_INVALID_PARAMETER If String is NULL.
732 If PcdMaximumUnicodeStringLength is not
733 zero, and String contains more than
734 PcdMaximumUnicodeStringLength Unicode
735 characters, not including the
737 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
738 the range defined by UINT64.
743 StrDecimalToUint64S (
744 IN CONST CHAR16
*String
,
745 OUT CHAR16
**EndPointer OPTIONAL
,
749 ASSERT (((UINTN
)String
& BIT0
) == 0);
752 // 1. Neither String nor Data shall be a null pointer.
754 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
755 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
758 // 2. The length of String shall not be greater than RSIZE_MAX.
760 if (RSIZE_MAX
!= 0) {
761 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
764 if (EndPointer
!= NULL
) {
765 *EndPointer
= (CHAR16
*)String
;
769 // Ignore the pad spaces (space or tab)
771 while ((*String
== L
' ') || (*String
== L
'\t')) {
776 // Ignore leading Zeros after the spaces
778 while (*String
== L
'0') {
784 while (InternalIsDecimalDigitCharacter (*String
)) {
786 // If the number represented by String overflows according to the range
787 // defined by UINT64, then MAX_UINT64 is stored in *Data and
788 // RETURN_UNSUPPORTED is returned.
790 if (*Data
> DivU64x32 (MAX_UINT64
- (*String
- L
'0'), 10)) {
792 if (EndPointer
!= NULL
) {
793 *EndPointer
= (CHAR16
*)String
;
796 return RETURN_UNSUPPORTED
;
799 *Data
= MultU64x32 (*Data
, 10) + (*String
- L
'0');
803 if (EndPointer
!= NULL
) {
804 *EndPointer
= (CHAR16
*)String
;
807 return RETURN_SUCCESS
;
811 Convert a Null-terminated Unicode hexadecimal string to a value of type
814 This function outputs a value of type UINTN by interpreting the contents of
815 the Unicode string specified by String as a hexadecimal number. The format of
816 the input Unicode string String is:
818 [spaces][zeros][x][hexadecimal digits].
820 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
821 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
822 If "x" appears in the input string, it must be prefixed with at least one 0.
823 The function will ignore the pad space, which includes spaces or tab
824 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
825 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
826 after [x] or the first valid hexadecimal digit. Then, the function stops at
827 the first character that is a not a valid hexadecimal character or NULL,
828 whichever one comes first.
830 If String is not aligned in a 16-bit boundary, then ASSERT().
832 If String has no valid hexadecimal digits in the above format, then 0 is
833 stored at the location pointed to by Data.
834 If the number represented by String exceeds the range defined by UINTN, then
835 MAX_UINTN is stored at the location pointed to by Data.
837 If EndPointer is not NULL, a pointer to the character that stopped the scan
838 is stored at the location pointed to by EndPointer. If String has no valid
839 hexadecimal digits right after the optional pad spaces, the value of String
840 is stored at the location pointed to by EndPointer.
842 @param String Pointer to a Null-terminated Unicode string.
843 @param EndPointer Pointer to character that stops scan.
844 @param Data Pointer to the converted value.
846 @retval RETURN_SUCCESS Value is translated from String.
847 @retval RETURN_INVALID_PARAMETER If String is NULL.
849 If PcdMaximumUnicodeStringLength is not
850 zero, and String contains more than
851 PcdMaximumUnicodeStringLength Unicode
852 characters, not including the
854 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
855 the range defined by UINTN.
861 IN CONST CHAR16
*String
,
862 OUT CHAR16
**EndPointer OPTIONAL
,
866 ASSERT (((UINTN
)String
& BIT0
) == 0);
869 // 1. Neither String nor Data shall be a null pointer.
871 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
872 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
875 // 2. The length of String shall not be greater than RSIZE_MAX.
877 if (RSIZE_MAX
!= 0) {
878 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
881 if (EndPointer
!= NULL
) {
882 *EndPointer
= (CHAR16
*)String
;
886 // Ignore the pad spaces (space or tab)
888 while ((*String
== L
' ') || (*String
== L
'\t')) {
893 // Ignore leading Zeros after the spaces
895 while (*String
== L
'0') {
899 if (CharToUpper (*String
) == L
'X') {
900 if (*(String
- 1) != L
'0') {
902 return RETURN_SUCCESS
;
913 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
915 // If the number represented by String overflows according to the range
916 // defined by UINTN, then MAX_UINTN is stored in *Data and
917 // RETURN_UNSUPPORTED is returned.
919 if (*Data
> ((MAX_UINTN
- InternalHexCharToUintn (*String
)) >> 4)) {
921 if (EndPointer
!= NULL
) {
922 *EndPointer
= (CHAR16
*)String
;
925 return RETURN_UNSUPPORTED
;
928 *Data
= (*Data
<< 4) + InternalHexCharToUintn (*String
);
932 if (EndPointer
!= NULL
) {
933 *EndPointer
= (CHAR16
*)String
;
936 return RETURN_SUCCESS
;
940 Convert a Null-terminated Unicode hexadecimal string to a value of type
943 This function outputs a value of type UINT64 by interpreting the contents of
944 the Unicode string specified by String as a hexadecimal number. The format of
945 the input Unicode string String is:
947 [spaces][zeros][x][hexadecimal digits].
949 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
950 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
951 If "x" appears in the input string, it must be prefixed with at least one 0.
952 The function will ignore the pad space, which includes spaces or tab
953 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
954 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
955 after [x] or the first valid hexadecimal digit. Then, the function stops at
956 the first character that is a not a valid hexadecimal character or NULL,
957 whichever one comes first.
959 If String is not aligned in a 16-bit boundary, then ASSERT().
961 If String has no valid hexadecimal digits in the above format, then 0 is
962 stored at the location pointed to by Data.
963 If the number represented by String exceeds the range defined by UINT64, then
964 MAX_UINT64 is stored at the location pointed to by Data.
966 If EndPointer is not NULL, a pointer to the character that stopped the scan
967 is stored at the location pointed to by EndPointer. If String has no valid
968 hexadecimal digits right after the optional pad spaces, the value of String
969 is stored at the location pointed to by EndPointer.
971 @param String Pointer to a Null-terminated Unicode string.
972 @param EndPointer Pointer to character that stops scan.
973 @param Data Pointer to the converted value.
975 @retval RETURN_SUCCESS Value is translated from String.
976 @retval RETURN_INVALID_PARAMETER If String is NULL.
978 If PcdMaximumUnicodeStringLength is not
979 zero, and String contains more than
980 PcdMaximumUnicodeStringLength Unicode
981 characters, not including the
983 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
984 the range defined by UINT64.
990 IN CONST CHAR16
*String
,
991 OUT CHAR16
**EndPointer OPTIONAL
,
995 ASSERT (((UINTN
)String
& BIT0
) == 0);
998 // 1. Neither String nor Data shall be a null pointer.
1000 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1001 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
1004 // 2. The length of String shall not be greater than RSIZE_MAX.
1006 if (RSIZE_MAX
!= 0) {
1007 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1010 if (EndPointer
!= NULL
) {
1011 *EndPointer
= (CHAR16
*)String
;
1015 // Ignore the pad spaces (space or tab)
1017 while ((*String
== L
' ') || (*String
== L
'\t')) {
1022 // Ignore leading Zeros after the spaces
1024 while (*String
== L
'0') {
1028 if (CharToUpper (*String
) == L
'X') {
1029 if (*(String
- 1) != L
'0') {
1031 return RETURN_SUCCESS
;
1042 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
1044 // If the number represented by String overflows according to the range
1045 // defined by UINT64, then MAX_UINT64 is stored in *Data and
1046 // RETURN_UNSUPPORTED is returned.
1048 if (*Data
> RShiftU64 (MAX_UINT64
- InternalHexCharToUintn (*String
), 4)) {
1050 if (EndPointer
!= NULL
) {
1051 *EndPointer
= (CHAR16
*)String
;
1054 return RETURN_UNSUPPORTED
;
1057 *Data
= LShiftU64 (*Data
, 4) + InternalHexCharToUintn (*String
);
1061 if (EndPointer
!= NULL
) {
1062 *EndPointer
= (CHAR16
*)String
;
1065 return RETURN_SUCCESS
;
1069 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1071 This function outputs a value of type IPv6_ADDRESS and may output a value
1072 of type UINT8 by interpreting the contents of the Unicode string specified
1073 by String. The format of the input Unicode string String is as follows:
1077 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1078 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1079 memory address and high byte is stored in high memory address. P contains decimal
1080 digit characters in the range [0-9]. The running zero in the beginning of P will
1081 be ignored. /P is optional.
1083 When /P is not in the String, the function stops at the first character that is
1084 not a valid hexadecimal digit character after eight X's are converted.
1086 When /P is in the String, the function stops at the first character that is not
1087 a valid decimal digit character after P is converted.
1089 "::" can be used to compress one or more groups of X when X contains only 0.
1090 The "::" can only appear once in the String.
1092 If String is not aligned in a 16-bit boundary, then ASSERT().
1094 If EndPointer is not NULL and Address is translated from String, a pointer
1095 to the character that stopped the scan is stored at the location pointed to
1098 @param String Pointer to a Null-terminated Unicode string.
1099 @param EndPointer Pointer to character that stops scan.
1100 @param Address Pointer to the converted IPv6 address.
1101 @param PrefixLength Pointer to the converted IPv6 address prefix
1102 length. MAX_UINT8 is returned when /P is
1105 @retval RETURN_SUCCESS Address is translated from String.
1106 @retval RETURN_INVALID_PARAMETER If String is NULL.
1108 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1110 If String contains "::" and number of X
1112 If P starts with character that is not a
1113 valid decimal digit character.
1114 If the decimal number converted from P
1121 IN CONST CHAR16
*String
,
1122 OUT CHAR16
**EndPointer OPTIONAL
,
1123 OUT IPv6_ADDRESS
*Address
,
1124 OUT UINT8
*PrefixLength OPTIONAL
1127 RETURN_STATUS Status
;
1130 IPv6_ADDRESS LocalAddress
;
1131 UINT8 LocalPrefixLength
;
1132 CONST CHAR16
*Pointer
;
1134 UINTN CompressStart
;
1135 BOOLEAN ExpectPrefix
;
1137 LocalPrefixLength
= MAX_UINT8
;
1138 CompressStart
= ARRAY_SIZE (Address
->Addr
);
1139 ExpectPrefix
= FALSE
;
1141 ASSERT (((UINTN
)String
& BIT0
) == 0);
1144 // 1. None of String or Guid shall be a null pointer.
1146 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1147 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
1149 for (Pointer
= String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
1150 if (!InternalIsHexaDecimalDigitCharacter (*Pointer
)) {
1151 if (*Pointer
!= L
':') {
1153 // ":" or "/" should be followed by digit characters.
1155 return RETURN_UNSUPPORTED
;
1159 // Meet second ":" after previous ":" or "/"
1160 // or meet first ":" in the beginning of String.
1164 // ":" shall not be after "/"
1166 return RETURN_UNSUPPORTED
;
1169 if ((CompressStart
!= ARRAY_SIZE (Address
->Addr
)) || (AddressIndex
== ARRAY_SIZE (Address
->Addr
))) {
1171 // "::" can only appear once.
1172 // "::" can only appear when address is not full length.
1174 return RETURN_UNSUPPORTED
;
1177 // Remember the start of zero compressing.
1179 CompressStart
= AddressIndex
;
1182 if (CompressStart
== 0) {
1183 if (*Pointer
!= L
':') {
1185 // Single ":" shall not be in the beginning of String.
1187 return RETURN_UNSUPPORTED
;
1195 if (!InternalIsHexaDecimalDigitCharacter (*Pointer
)) {
1196 if (*Pointer
== L
'/') {
1198 // Might be optional "/P" after "::".
1200 if (CompressStart
!= AddressIndex
) {
1201 return RETURN_UNSUPPORTED
;
1207 if (!ExpectPrefix
) {
1211 Status
= StrHexToUintnS (Pointer
, &End
, &Uintn
);
1212 if (RETURN_ERROR (Status
) || (End
- Pointer
> 4)) {
1214 // Number of hexadecimal digit characters is no more than 4.
1216 return RETURN_UNSUPPORTED
;
1221 // Uintn won't exceed MAX_UINT16 if number of hexadecimal digit characters is no more than 4.
1223 ASSERT (AddressIndex
+ 1 < ARRAY_SIZE (Address
->Addr
));
1224 LocalAddress
.Addr
[AddressIndex
] = (UINT8
)((UINT16
)Uintn
>> 8);
1225 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
)Uintn
;
1229 // Get P, then exit the loop.
1231 Status
= StrDecimalToUintnS (Pointer
, &End
, &Uintn
);
1232 if (RETURN_ERROR (Status
) || (End
== Pointer
) || (Uintn
> 128)) {
1234 // Prefix length should not exceed 128.
1236 return RETURN_UNSUPPORTED
;
1239 LocalPrefixLength
= (UINT8
)Uintn
;
1248 if (*Pointer
== L
'/') {
1249 ExpectPrefix
= TRUE
;
1250 } else if (*Pointer
== L
':') {
1251 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1253 // Meet additional ":" after all 8 16-bit address
1259 // Meet other character that is not "/" or ":" after all 8 16-bit address
1267 if (((AddressIndex
== ARRAY_SIZE (Address
->Addr
)) && (CompressStart
!= ARRAY_SIZE (Address
->Addr
))) ||
1268 ((AddressIndex
!= ARRAY_SIZE (Address
->Addr
)) && (CompressStart
== ARRAY_SIZE (Address
->Addr
)))
1272 // Full length of address shall not have compressing zeros.
1273 // Non-full length of address shall have compressing zeros.
1275 return RETURN_UNSUPPORTED
;
1278 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
1279 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
1280 if (AddressIndex
> CompressStart
) {
1282 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
1283 &LocalAddress
.Addr
[CompressStart
],
1284 AddressIndex
- CompressStart
1288 if (PrefixLength
!= NULL
) {
1289 *PrefixLength
= LocalPrefixLength
;
1292 if (EndPointer
!= NULL
) {
1293 *EndPointer
= (CHAR16
*)Pointer
;
1296 return RETURN_SUCCESS
;
1300 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1302 This function outputs a value of type IPv4_ADDRESS and may output a value
1303 of type UINT8 by interpreting the contents of the Unicode string specified
1304 by String. The format of the input Unicode string String is as follows:
1308 D and P are decimal digit characters in the range [0-9]. The running zero in
1309 the beginning of D and P will be ignored. /P is optional.
1311 When /P is not in the String, the function stops at the first character that is
1312 not a valid decimal digit character after four D's are converted.
1314 When /P is in the String, the function stops at the first character that is not
1315 a valid decimal digit character after P is converted.
1317 If String is not aligned in a 16-bit boundary, then ASSERT().
1319 If EndPointer is not NULL and Address is translated from String, a pointer
1320 to the character that stopped the scan is stored at the location pointed to
1323 @param String Pointer to a Null-terminated Unicode string.
1324 @param EndPointer Pointer to character that stops scan.
1325 @param Address Pointer to the converted IPv4 address.
1326 @param PrefixLength Pointer to the converted IPv4 address prefix
1327 length. MAX_UINT8 is returned when /P is
1330 @retval RETURN_SUCCESS Address is translated from String.
1331 @retval RETURN_INVALID_PARAMETER If String is NULL.
1333 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1334 If any decimal number converted from D
1336 If the decimal number converted from P
1343 IN CONST CHAR16
*String
,
1344 OUT CHAR16
**EndPointer OPTIONAL
,
1345 OUT IPv4_ADDRESS
*Address
,
1346 OUT UINT8
*PrefixLength OPTIONAL
1349 RETURN_STATUS Status
;
1352 IPv4_ADDRESS LocalAddress
;
1353 UINT8 LocalPrefixLength
;
1356 LocalPrefixLength
= MAX_UINT8
;
1358 ASSERT (((UINTN
)String
& BIT0
) == 0);
1361 // 1. None of String or Guid shall be a null pointer.
1363 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1364 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
1366 for (Pointer
= (CHAR16
*)String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
1367 if (!InternalIsDecimalDigitCharacter (*Pointer
)) {
1369 // D or P contains invalid characters.
1377 Status
= StrDecimalToUintnS ((CONST CHAR16
*)Pointer
, &Pointer
, &Uintn
);
1378 if (RETURN_ERROR (Status
)) {
1379 return RETURN_UNSUPPORTED
;
1382 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1387 return RETURN_UNSUPPORTED
;
1390 LocalPrefixLength
= (UINT8
)Uintn
;
1395 if (Uintn
> MAX_UINT8
) {
1396 return RETURN_UNSUPPORTED
;
1399 LocalAddress
.Addr
[AddressIndex
] = (UINT8
)Uintn
;
1404 // Check the '.' or '/', depending on the AddressIndex.
1406 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1407 if (*Pointer
== L
'/') {
1409 // '/P' is in the String.
1410 // Skip "/" and get P in next loop.
1415 // '/P' is not in the String.
1419 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1420 if (*Pointer
== L
'.') {
1422 // D should be followed by '.'
1426 return RETURN_UNSUPPORTED
;
1431 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1432 return RETURN_UNSUPPORTED
;
1435 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
1436 if (PrefixLength
!= NULL
) {
1437 *PrefixLength
= LocalPrefixLength
;
1440 if (EndPointer
!= NULL
) {
1441 *EndPointer
= Pointer
;
1444 return RETURN_SUCCESS
;
1448 Convert a Null-terminated Unicode GUID string to a value of type
1451 This function outputs a GUID value by interpreting the contents of
1452 the Unicode string specified by String. The format of the input
1453 Unicode string String consists of 36 characters, as follows:
1455 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1457 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1458 [A-F], with each pair representing a single byte hexadecimal value.
1460 The mapping between String and the EFI_GUID structure is as follows:
1478 If String is not aligned in a 16-bit boundary, then ASSERT().
1480 @param String Pointer to a Null-terminated Unicode string.
1481 @param Guid Pointer to the converted GUID.
1483 @retval RETURN_SUCCESS Guid is translated from String.
1484 @retval RETURN_INVALID_PARAMETER If String is NULL.
1486 @retval RETURN_UNSUPPORTED If String is not as the above format.
1492 IN CONST CHAR16
*String
,
1496 RETURN_STATUS Status
;
1499 ASSERT (((UINTN
)String
& BIT0
) == 0);
1502 // 1. None of String or Guid shall be a null pointer.
1504 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1505 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
1508 // Get aabbccdd in big-endian.
1510 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*)&LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
1511 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data1
)] != L
'-')) {
1512 return RETURN_UNSUPPORTED
;
1516 // Convert big-endian to little-endian.
1518 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
1519 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
1522 // Get eeff in big-endian.
1524 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*)&LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
1525 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data2
)] != L
'-')) {
1526 return RETURN_UNSUPPORTED
;
1530 // Convert big-endian to little-endian.
1532 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
1533 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
1536 // Get gghh in big-endian.
1538 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*)&LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
1539 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data3
)] != L
'-')) {
1540 return RETURN_UNSUPPORTED
;
1544 // Convert big-endian to little-endian.
1546 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
1547 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
1552 Status
= StrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
1553 if (RETURN_ERROR (Status
) || (String
[2 * 2] != L
'-')) {
1554 return RETURN_UNSUPPORTED
;
1557 String
+= 2 * 2 + 1;
1560 // Get kkllmmnnoopp.
1562 Status
= StrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
1563 if (RETURN_ERROR (Status
)) {
1564 return RETURN_UNSUPPORTED
;
1567 CopyGuid (Guid
, &LocalGuid
);
1568 return RETURN_SUCCESS
;
1572 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1574 This function outputs a byte array by interpreting the contents of
1575 the Unicode string specified by String in hexadecimal format. The format of
1576 the input Unicode string String is:
1580 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1581 The function decodes every two hexadecimal digit characters as one byte. The
1582 decoding stops after Length of characters and outputs Buffer containing
1585 If String is not aligned in a 16-bit boundary, then ASSERT().
1587 @param String Pointer to a Null-terminated Unicode string.
1588 @param Length The number of Unicode characters to decode.
1589 @param Buffer Pointer to the converted bytes array.
1590 @param MaxBufferSize The maximum size of Buffer.
1592 @retval RETURN_SUCCESS Buffer is translated from String.
1593 @retval RETURN_INVALID_PARAMETER If String is NULL.
1595 If Length is not multiple of 2.
1596 If PcdMaximumUnicodeStringLength is not zero,
1597 and Length is greater than
1598 PcdMaximumUnicodeStringLength.
1599 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1600 a character that is not valid hexadecimal
1601 digit characters, or a Null-terminator.
1602 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1607 IN CONST CHAR16
*String
,
1610 IN UINTN MaxBufferSize
1615 ASSERT (((UINTN
)String
& BIT0
) == 0);
1618 // 1. None of String or Buffer shall be a null pointer.
1620 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1621 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
1624 // 2. Length shall not be greater than RSIZE_MAX.
1626 if (RSIZE_MAX
!= 0) {
1627 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1631 // 3. Length shall not be odd.
1633 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
1636 // 4. MaxBufferSize shall equal to or greater than Length / 2.
1638 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
1641 // 5. String shall not contains invalid hexadecimal digits.
1643 for (Index
= 0; Index
< Length
; Index
++) {
1644 if (!InternalIsHexaDecimalDigitCharacter (String
[Index
])) {
1649 if (Index
!= Length
) {
1650 return RETURN_UNSUPPORTED
;
1654 // Convert the hex string to bytes.
1656 for (Index
= 0; Index
< Length
; Index
++) {
1658 // For even characters, write the upper nibble for each buffer byte,
1659 // and for even characters, the lower nibble.
1661 if ((Index
& BIT0
) == 0) {
1662 Buffer
[Index
/ 2] = (UINT8
)InternalHexCharToUintn (String
[Index
]) << 4;
1664 Buffer
[Index
/ 2] |= (UINT8
)InternalHexCharToUintn (String
[Index
]);
1668 return RETURN_SUCCESS
;
1672 Returns the length of a Null-terminated Ascii string.
1674 This function is similar as strlen_s defined in C11.
1676 @param String A pointer to a Null-terminated Ascii string.
1677 @param MaxSize The maximum number of Destination Ascii
1678 char, including terminating null char.
1680 @retval 0 If String is NULL.
1681 @retval MaxSize If there is no null character in the first MaxSize characters of String.
1682 @return The number of characters that percede the terminating null character.
1688 IN CONST CHAR8
*String
,
1695 // If String is a null pointer or MaxSize is 0, then the AsciiStrnLenS function returns zero.
1697 if ((String
== NULL
) || (MaxSize
== 0)) {
1702 // Otherwise, the AsciiStrnLenS function returns the number of characters that precede the
1703 // terminating null character. If there is no null character in the first MaxSize characters of
1704 // String then AsciiStrnLenS returns MaxSize. At most the first MaxSize characters of String shall
1705 // be accessed by AsciiStrnLenS.
1708 while (String
[Length
] != 0) {
1709 if (Length
>= MaxSize
- 1) {
1720 Returns the size of a Null-terminated Ascii string in bytes, including the
1723 This function returns the size of the Null-terminated Ascii string specified
1724 by String in bytes, including the Null terminator.
1726 @param String A pointer to a Null-terminated Ascii string.
1727 @param MaxSize The maximum number of Destination Ascii
1728 char, including the Null terminator.
1730 @retval 0 If String is NULL.
1731 @retval (sizeof (CHAR8) * (MaxSize + 1))
1732 If there is no Null terminator in the first MaxSize characters of
1734 @return The size of the Null-terminated Ascii string in bytes, including the
1741 IN CONST CHAR8
*String
,
1746 // If String is a null pointer, then the AsciiStrnSizeS function returns
1749 if (String
== NULL
) {
1754 // Otherwise, the AsciiStrnSizeS function returns the size of the
1755 // Null-terminated Ascii string in bytes, including the Null terminator. If
1756 // there is no Null terminator in the first MaxSize characters of String,
1757 // then AsciiStrnSizeS returns (sizeof (CHAR8) * (MaxSize + 1)) to keep a
1758 // consistent map with the AsciiStrnLenS function.
1760 return (AsciiStrnLenS (String
, MaxSize
) + 1) * sizeof (*String
);
1764 Copies the string pointed to by Source (including the terminating null char)
1765 to the array pointed to by Destination.
1767 This function is similar as strcpy_s defined in C11.
1769 If an error is returned, then the Destination is unmodified.
1771 @param Destination A pointer to a Null-terminated Ascii string.
1772 @param DestMax The maximum number of Destination Ascii
1773 char, including terminating null char.
1774 @param Source A pointer to a Null-terminated Ascii string.
1776 @retval RETURN_SUCCESS String is copied.
1777 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1778 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1780 If PcdMaximumAsciiStringLength is not zero,
1781 and DestMax is greater than
1782 PcdMaximumAsciiStringLength.
1784 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1789 OUT CHAR8
*Destination
,
1791 IN CONST CHAR8
*Source
1797 // 1. Neither Destination nor Source shall be a null pointer.
1799 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1800 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1803 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
1805 if (ASCII_RSIZE_MAX
!= 0) {
1806 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1810 // 3. DestMax shall not equal zero.
1812 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1815 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1817 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
1818 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1821 // 5. Copying shall not take place between objects that overlap.
1823 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1826 // The AsciiStrCpyS function copies the string pointed to by Source (including the terminating
1827 // null character) into the array pointed to by Destination.
1829 while (*Source
!= 0) {
1830 *(Destination
++) = *(Source
++);
1835 return RETURN_SUCCESS
;
1839 Copies not more than Length successive char from the string pointed to by
1840 Source to the array pointed to by Destination. If no null char is copied from
1841 Source, then Destination[Length] is always set to null.
1843 This function is similar as strncpy_s defined in C11.
1845 If an error is returned, then the Destination is unmodified.
1847 @param Destination A pointer to a Null-terminated Ascii string.
1848 @param DestMax The maximum number of Destination Ascii
1849 char, including terminating null char.
1850 @param Source A pointer to a Null-terminated Ascii string.
1851 @param Length The maximum number of Ascii characters to copy.
1853 @retval RETURN_SUCCESS String is copied.
1854 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1855 MIN(StrLen(Source), Length).
1856 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1858 If PcdMaximumAsciiStringLength is not zero,
1859 and DestMax is greater than
1860 PcdMaximumAsciiStringLength.
1862 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1867 OUT CHAR8
*Destination
,
1869 IN CONST CHAR8
*Source
,
1876 // 1. Neither Destination nor Source shall be a null pointer.
1878 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1879 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1882 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX
1884 if (ASCII_RSIZE_MAX
!= 0) {
1885 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1886 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1890 // 3. DestMax shall not equal zero.
1892 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1895 // 4. If Length is not less than DestMax, then DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1897 SourceLen
= AsciiStrnLenS (Source
, MIN (DestMax
, Length
));
1898 if (Length
>= DestMax
) {
1899 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1903 // 5. Copying shall not take place between objects that overlap.
1905 if (SourceLen
> Length
) {
1909 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1912 // The AsciiStrnCpyS function copies not more than Length successive characters (characters that
1913 // follow a null character are not copied) from the array pointed to by Source to the array
1914 // pointed to by Destination. If no null character was copied from Source, then Destination[Length] is set to a null
1917 while ((SourceLen
> 0) && (*Source
!= 0)) {
1918 *(Destination
++) = *(Source
++);
1924 return RETURN_SUCCESS
;
1928 Appends a copy of the string pointed to by Source (including the terminating
1929 null char) to the end of the string pointed to by Destination.
1931 This function is similar as strcat_s defined in C11.
1933 If an error is returned, then the Destination is unmodified.
1935 @param Destination A pointer to a Null-terminated Ascii string.
1936 @param DestMax The maximum number of Destination Ascii
1937 char, including terminating null char.
1938 @param Source A pointer to a Null-terminated Ascii string.
1940 @retval RETURN_SUCCESS String is appended.
1941 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
1942 StrLen(Destination).
1943 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
1944 greater than StrLen(Source).
1945 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1947 If PcdMaximumAsciiStringLength is not zero,
1948 and DestMax is greater than
1949 PcdMaximumAsciiStringLength.
1951 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1956 IN OUT CHAR8
*Destination
,
1958 IN CONST CHAR8
*Source
1966 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrCatS.
1968 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
1969 CopyLen
= DestMax
- DestLen
;
1972 // 1. Neither Destination nor Source shall be a null pointer.
1974 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1975 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1978 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
1980 if (ASCII_RSIZE_MAX
!= 0) {
1981 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1985 // 3. DestMax shall not equal zero.
1987 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1990 // 4. CopyLen shall not equal zero.
1992 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
1995 // 5. CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
1997 SourceLen
= AsciiStrnLenS (Source
, CopyLen
);
1998 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2001 // 6. Copying shall not take place between objects that overlap.
2003 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2006 // The AsciiStrCatS function appends a copy of the string pointed to by Source (including the
2007 // terminating null character) to the end of the string pointed to by Destination. The initial character
2008 // from Source overwrites the null character at the end of Destination.
2010 Destination
= Destination
+ DestLen
;
2011 while (*Source
!= 0) {
2012 *(Destination
++) = *(Source
++);
2017 return RETURN_SUCCESS
;
2021 Appends not more than Length successive char from the string pointed to by
2022 Source to the end of the string pointed to by Destination. If no null char is
2023 copied from Source, then Destination[StrLen(Destination) + Length] is always
2026 This function is similar as strncat_s defined in C11.
2028 If an error is returned, then the Destination is unmodified.
2030 @param Destination A pointer to a Null-terminated Ascii string.
2031 @param DestMax The maximum number of Destination Ascii
2032 char, including terminating null char.
2033 @param Source A pointer to a Null-terminated Ascii string.
2034 @param Length The maximum number of Ascii characters to copy.
2036 @retval RETURN_SUCCESS String is appended.
2037 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
2038 StrLen(Destination).
2039 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
2040 greater than MIN(StrLen(Source), Length).
2041 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2043 If PcdMaximumAsciiStringLength is not zero,
2044 and DestMax is greater than
2045 PcdMaximumAsciiStringLength.
2047 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2052 IN OUT CHAR8
*Destination
,
2054 IN CONST CHAR8
*Source
,
2063 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrnCatS.
2065 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
2066 CopyLen
= DestMax
- DestLen
;
2069 // 1. Neither Destination nor Source shall be a null pointer.
2071 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2072 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2075 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX.
2077 if (ASCII_RSIZE_MAX
!= 0) {
2078 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2079 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2083 // 3. DestMax shall not equal zero.
2085 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2088 // 4. CopyLen shall not equal zero.
2090 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
2093 // 5. If Length is not less than CopyLen, then CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
2095 SourceLen
= AsciiStrnLenS (Source
, MIN (CopyLen
, Length
));
2096 if (Length
>= CopyLen
) {
2097 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2101 // 6. Copying shall not take place between objects that overlap.
2103 if (SourceLen
> Length
) {
2107 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2110 // The AsciiStrnCatS function appends not more than Length successive characters (characters
2111 // that follow a null character are not copied) from the array pointed to by Source to the end of
2112 // the string pointed to by Destination. The initial character from Source overwrites the null character at
2113 // the end of Destination. If no null character was copied from Source, then Destination[DestMax-CopyLen+Length] is set to
2114 // a null character.
2116 Destination
= Destination
+ DestLen
;
2117 while ((SourceLen
> 0) && (*Source
!= 0)) {
2118 *(Destination
++) = *(Source
++);
2124 return RETURN_SUCCESS
;
2128 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
2130 This function outputs a value of type UINTN by interpreting the contents of
2131 the Ascii string specified by String as a decimal number. The format of the
2132 input Ascii string String is:
2134 [spaces] [decimal digits].
2136 The valid decimal digit character is in the range [0-9]. The function will
2137 ignore the pad space, which includes spaces or tab characters, before
2138 [decimal digits]. The running zero in the beginning of [decimal digits] will
2139 be ignored. Then, the function stops at the first character that is a not a
2140 valid decimal character or a Null-terminator, whichever one comes first.
2142 If String has no valid decimal digits in the above format, then 0 is stored
2143 at the location pointed to by Data.
2144 If the number represented by String exceeds the range defined by UINTN, then
2145 MAX_UINTN is stored at the location pointed to by Data.
2147 If EndPointer is not NULL, a pointer to the character that stopped the scan
2148 is stored at the location pointed to by EndPointer. If String has no valid
2149 decimal digits right after the optional pad spaces, the value of String is
2150 stored at the location pointed to by EndPointer.
2152 @param String Pointer to a Null-terminated Ascii string.
2153 @param EndPointer Pointer to character that stops scan.
2154 @param Data Pointer to the converted value.
2156 @retval RETURN_SUCCESS Value is translated from String.
2157 @retval RETURN_INVALID_PARAMETER If String is NULL.
2159 If PcdMaximumAsciiStringLength is not zero,
2160 and String contains more than
2161 PcdMaximumAsciiStringLength Ascii
2162 characters, not including the
2164 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2165 the range defined by UINTN.
2170 AsciiStrDecimalToUintnS (
2171 IN CONST CHAR8
*String
,
2172 OUT CHAR8
**EndPointer OPTIONAL
,
2177 // 1. Neither String nor Data shall be a null pointer.
2179 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2180 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2183 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2185 if (ASCII_RSIZE_MAX
!= 0) {
2186 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2189 if (EndPointer
!= NULL
) {
2190 *EndPointer
= (CHAR8
*)String
;
2194 // Ignore the pad spaces (space or tab)
2196 while ((*String
== ' ') || (*String
== '\t')) {
2201 // Ignore leading Zeros after the spaces
2203 while (*String
== '0') {
2209 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2211 // If the number represented by String overflows according to the range
2212 // defined by UINTN, then MAX_UINTN is stored in *Data and
2213 // RETURN_UNSUPPORTED is returned.
2215 if (*Data
> ((MAX_UINTN
- (*String
- '0')) / 10)) {
2217 if (EndPointer
!= NULL
) {
2218 *EndPointer
= (CHAR8
*)String
;
2221 return RETURN_UNSUPPORTED
;
2224 *Data
= *Data
* 10 + (*String
- '0');
2228 if (EndPointer
!= NULL
) {
2229 *EndPointer
= (CHAR8
*)String
;
2232 return RETURN_SUCCESS
;
2236 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
2238 This function outputs a value of type UINT64 by interpreting the contents of
2239 the Ascii string specified by String as a decimal number. The format of the
2240 input Ascii string String is:
2242 [spaces] [decimal digits].
2244 The valid decimal digit character is in the range [0-9]. The function will
2245 ignore the pad space, which includes spaces or tab characters, before
2246 [decimal digits]. The running zero in the beginning of [decimal digits] will
2247 be ignored. Then, the function stops at the first character that is a not a
2248 valid decimal character or a Null-terminator, whichever one comes first.
2250 If String has no valid decimal digits in the above format, then 0 is stored
2251 at the location pointed to by Data.
2252 If the number represented by String exceeds the range defined by UINT64, then
2253 MAX_UINT64 is stored at the location pointed to by Data.
2255 If EndPointer is not NULL, a pointer to the character that stopped the scan
2256 is stored at the location pointed to by EndPointer. If String has no valid
2257 decimal digits right after the optional pad spaces, the value of String is
2258 stored at the location pointed to by EndPointer.
2260 @param String Pointer to a Null-terminated Ascii string.
2261 @param EndPointer Pointer to character that stops scan.
2262 @param Data Pointer to the converted value.
2264 @retval RETURN_SUCCESS Value is translated from String.
2265 @retval RETURN_INVALID_PARAMETER If String is NULL.
2267 If PcdMaximumAsciiStringLength is not zero,
2268 and String contains more than
2269 PcdMaximumAsciiStringLength Ascii
2270 characters, not including the
2272 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2273 the range defined by UINT64.
2278 AsciiStrDecimalToUint64S (
2279 IN CONST CHAR8
*String
,
2280 OUT CHAR8
**EndPointer OPTIONAL
,
2285 // 1. Neither String nor Data shall be a null pointer.
2287 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2288 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2291 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2293 if (ASCII_RSIZE_MAX
!= 0) {
2294 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2297 if (EndPointer
!= NULL
) {
2298 *EndPointer
= (CHAR8
*)String
;
2302 // Ignore the pad spaces (space or tab)
2304 while ((*String
== ' ') || (*String
== '\t')) {
2309 // Ignore leading Zeros after the spaces
2311 while (*String
== '0') {
2317 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2319 // If the number represented by String overflows according to the range
2320 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2321 // RETURN_UNSUPPORTED is returned.
2323 if (*Data
> DivU64x32 (MAX_UINT64
- (*String
- '0'), 10)) {
2325 if (EndPointer
!= NULL
) {
2326 *EndPointer
= (CHAR8
*)String
;
2329 return RETURN_UNSUPPORTED
;
2332 *Data
= MultU64x32 (*Data
, 10) + (*String
- '0');
2336 if (EndPointer
!= NULL
) {
2337 *EndPointer
= (CHAR8
*)String
;
2340 return RETURN_SUCCESS
;
2344 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
2346 This function outputs a value of type UINTN by interpreting the contents of
2347 the Ascii string specified by String as a hexadecimal number. The format of
2348 the input Ascii string String is:
2350 [spaces][zeros][x][hexadecimal digits].
2352 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2353 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2354 "x" appears in the input string, it must be prefixed with at least one 0. The
2355 function will ignore the pad space, which includes spaces or tab characters,
2356 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2357 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2358 the first valid hexadecimal digit. Then, the function stops at the first
2359 character that is a not a valid hexadecimal character or Null-terminator,
2360 whichever on comes first.
2362 If String has no valid hexadecimal digits in the above format, then 0 is
2363 stored at the location pointed to by Data.
2364 If the number represented by String exceeds the range defined by UINTN, then
2365 MAX_UINTN is stored at the location pointed to by Data.
2367 If EndPointer is not NULL, a pointer to the character that stopped the scan
2368 is stored at the location pointed to by EndPointer. If String has no valid
2369 hexadecimal digits right after the optional pad spaces, the value of String
2370 is stored at the location pointed to by EndPointer.
2372 @param String Pointer to a Null-terminated Ascii string.
2373 @param EndPointer Pointer to character that stops scan.
2374 @param Data Pointer to the converted value.
2376 @retval RETURN_SUCCESS Value is translated from String.
2377 @retval RETURN_INVALID_PARAMETER If String is NULL.
2379 If PcdMaximumAsciiStringLength is not zero,
2380 and String contains more than
2381 PcdMaximumAsciiStringLength Ascii
2382 characters, not including the
2384 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2385 the range defined by UINTN.
2390 AsciiStrHexToUintnS (
2391 IN CONST CHAR8
*String
,
2392 OUT CHAR8
**EndPointer OPTIONAL
,
2397 // 1. Neither String nor Data shall be a null pointer.
2399 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2400 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2403 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2405 if (ASCII_RSIZE_MAX
!= 0) {
2406 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2409 if (EndPointer
!= NULL
) {
2410 *EndPointer
= (CHAR8
*)String
;
2414 // Ignore the pad spaces (space or tab)
2416 while ((*String
== ' ') || (*String
== '\t')) {
2421 // Ignore leading Zeros after the spaces
2423 while (*String
== '0') {
2427 if (AsciiCharToUpper (*String
) == 'X') {
2428 if (*(String
- 1) != '0') {
2430 return RETURN_SUCCESS
;
2441 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2443 // If the number represented by String overflows according to the range
2444 // defined by UINTN, then MAX_UINTN is stored in *Data and
2445 // RETURN_UNSUPPORTED is returned.
2447 if (*Data
> ((MAX_UINTN
- InternalAsciiHexCharToUintn (*String
)) >> 4)) {
2449 if (EndPointer
!= NULL
) {
2450 *EndPointer
= (CHAR8
*)String
;
2453 return RETURN_UNSUPPORTED
;
2456 *Data
= (*Data
<< 4) + InternalAsciiHexCharToUintn (*String
);
2460 if (EndPointer
!= NULL
) {
2461 *EndPointer
= (CHAR8
*)String
;
2464 return RETURN_SUCCESS
;
2468 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
2470 This function outputs a value of type UINT64 by interpreting the contents of
2471 the Ascii string specified by String as a hexadecimal number. The format of
2472 the input Ascii string String is:
2474 [spaces][zeros][x][hexadecimal digits].
2476 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2477 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2478 "x" appears in the input string, it must be prefixed with at least one 0. The
2479 function will ignore the pad space, which includes spaces or tab characters,
2480 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2481 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2482 the first valid hexadecimal digit. Then, the function stops at the first
2483 character that is a not a valid hexadecimal character or Null-terminator,
2484 whichever on comes first.
2486 If String has no valid hexadecimal digits in the above format, then 0 is
2487 stored at the location pointed to by Data.
2488 If the number represented by String exceeds the range defined by UINT64, then
2489 MAX_UINT64 is stored at the location pointed to by Data.
2491 If EndPointer is not NULL, a pointer to the character that stopped the scan
2492 is stored at the location pointed to by EndPointer. If String has no valid
2493 hexadecimal digits right after the optional pad spaces, the value of String
2494 is stored at the location pointed to by EndPointer.
2496 @param String Pointer to a Null-terminated Ascii string.
2497 @param EndPointer Pointer to character that stops scan.
2498 @param Data Pointer to the converted value.
2500 @retval RETURN_SUCCESS Value is translated from String.
2501 @retval RETURN_INVALID_PARAMETER If String is NULL.
2503 If PcdMaximumAsciiStringLength is not zero,
2504 and String contains more than
2505 PcdMaximumAsciiStringLength Ascii
2506 characters, not including the
2508 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2509 the range defined by UINT64.
2514 AsciiStrHexToUint64S (
2515 IN CONST CHAR8
*String
,
2516 OUT CHAR8
**EndPointer OPTIONAL
,
2521 // 1. Neither String nor Data shall be a null pointer.
2523 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2524 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2527 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2529 if (ASCII_RSIZE_MAX
!= 0) {
2530 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2533 if (EndPointer
!= NULL
) {
2534 *EndPointer
= (CHAR8
*)String
;
2538 // Ignore the pad spaces (space or tab)
2540 while ((*String
== ' ') || (*String
== '\t')) {
2545 // Ignore leading Zeros after the spaces
2547 while (*String
== '0') {
2551 if (AsciiCharToUpper (*String
) == 'X') {
2552 if (*(String
- 1) != '0') {
2554 return RETURN_SUCCESS
;
2565 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2567 // If the number represented by String overflows according to the range
2568 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2569 // RETURN_UNSUPPORTED is returned.
2571 if (*Data
> RShiftU64 (MAX_UINT64
- InternalAsciiHexCharToUintn (*String
), 4)) {
2573 if (EndPointer
!= NULL
) {
2574 *EndPointer
= (CHAR8
*)String
;
2577 return RETURN_UNSUPPORTED
;
2580 *Data
= LShiftU64 (*Data
, 4) + InternalAsciiHexCharToUintn (*String
);
2584 if (EndPointer
!= NULL
) {
2585 *EndPointer
= (CHAR8
*)String
;
2588 return RETURN_SUCCESS
;
2592 Convert a Null-terminated Unicode string to a Null-terminated
2595 This function is similar to AsciiStrCpyS.
2597 This function converts the content of the Unicode string Source
2598 to the ASCII string Destination by copying the lower 8 bits of
2599 each Unicode character. The function terminates the ASCII string
2600 Destination by appending a Null-terminator character at the end.
2602 The caller is responsible to make sure Destination points to a buffer with size
2603 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
2605 If any Unicode characters in Source contain non-zero value in
2606 the upper 8 bits, then ASSERT().
2608 If Source is not aligned on a 16-bit boundary, then ASSERT().
2610 If an error is returned, then the Destination is unmodified.
2612 @param Source The pointer to a Null-terminated Unicode string.
2613 @param Destination The pointer to a Null-terminated ASCII string.
2614 @param DestMax The maximum number of Destination Ascii
2615 char, including terminating null char.
2617 @retval RETURN_SUCCESS String is converted.
2618 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2619 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2621 If PcdMaximumAsciiStringLength is not zero,
2622 and DestMax is greater than
2623 PcdMaximumAsciiStringLength.
2624 If PcdMaximumUnicodeStringLength is not zero,
2625 and DestMax is greater than
2626 PcdMaximumUnicodeStringLength.
2628 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2633 UnicodeStrToAsciiStrS (
2634 IN CONST CHAR16
*Source
,
2635 OUT CHAR8
*Destination
,
2641 ASSERT (((UINTN
)Source
& BIT0
) == 0);
2644 // 1. Neither Destination nor Source shall be a null pointer.
2646 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2647 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2650 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX or RSIZE_MAX.
2652 if (ASCII_RSIZE_MAX
!= 0) {
2653 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2656 if (RSIZE_MAX
!= 0) {
2657 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2661 // 3. DestMax shall not equal zero.
2663 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2666 // 4. DestMax shall be greater than StrnLenS (Source, DestMax).
2668 SourceLen
= StrnLenS (Source
, DestMax
);
2669 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2672 // 5. Copying shall not take place between objects that overlap.
2674 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof (CHAR16
)), RETURN_ACCESS_DENIED
);
2679 while (*Source
!= '\0') {
2681 // If any Unicode characters in Source contain
2682 // non-zero value in the upper 8 bits, then ASSERT().
2684 ASSERT (*Source
< 0x100);
2685 *(Destination
++) = (CHAR8
)*(Source
++);
2688 *Destination
= '\0';
2690 return RETURN_SUCCESS
;
2694 Convert not more than Length successive characters from a Null-terminated
2695 Unicode string to a Null-terminated Ascii string. If no null char is copied
2696 from Source, then Destination[Length] is always set to null.
2698 This function converts not more than Length successive characters from the
2699 Unicode string Source to the Ascii string Destination by copying the lower 8
2700 bits of each Unicode character. The function terminates the Ascii string
2701 Destination by appending a Null-terminator character at the end.
2703 The caller is responsible to make sure Destination points to a buffer with
2704 size not smaller than ((MIN(StrLen(Source), Length) + 1) * sizeof (CHAR8))
2707 If any Unicode characters in Source contain non-zero value in the upper 8
2708 bits, then ASSERT().
2709 If Source is not aligned on a 16-bit boundary, then ASSERT().
2711 If an error is returned, then Destination and DestinationLength are
2714 @param Source The pointer to a Null-terminated Unicode string.
2715 @param Length The maximum number of Unicode characters to
2717 @param Destination The pointer to a Null-terminated Ascii string.
2718 @param DestMax The maximum number of Destination Ascii char,
2719 including terminating null char.
2720 @param DestinationLength The number of Unicode characters converted.
2722 @retval RETURN_SUCCESS String is converted.
2723 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2725 If DestinationLength is NULL.
2726 If PcdMaximumAsciiStringLength is not zero,
2727 and Length or DestMax is greater than
2728 PcdMaximumAsciiStringLength.
2729 If PcdMaximumUnicodeStringLength is not
2730 zero, and Length or DestMax is greater than
2731 PcdMaximumUnicodeStringLength.
2733 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2734 MIN(StrLen(Source), Length).
2735 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2740 UnicodeStrnToAsciiStrS (
2741 IN CONST CHAR16
*Source
,
2743 OUT CHAR8
*Destination
,
2745 OUT UINTN
*DestinationLength
2750 ASSERT (((UINTN
)Source
& BIT0
) == 0);
2753 // 1. None of Destination, Source or DestinationLength shall be a null
2756 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2757 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2758 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
2761 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
2764 if (ASCII_RSIZE_MAX
!= 0) {
2765 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2766 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2769 if (RSIZE_MAX
!= 0) {
2770 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2771 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2775 // 3. DestMax shall not equal zero.
2777 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2780 // 4. If Length is not less than DestMax, then DestMax shall be greater than
2781 // StrnLenS(Source, DestMax).
2783 SourceLen
= StrnLenS (Source
, DestMax
);
2784 if (Length
>= DestMax
) {
2785 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2789 // 5. Copying shall not take place between objects that overlap.
2791 if (SourceLen
> Length
) {
2795 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof (CHAR16
)), RETURN_ACCESS_DENIED
);
2797 *DestinationLength
= 0;
2802 while ((*Source
!= 0) && (SourceLen
> 0)) {
2804 // If any Unicode characters in Source contain non-zero value in the upper
2805 // 8 bits, then ASSERT().
2807 ASSERT (*Source
< 0x100);
2808 *(Destination
++) = (CHAR8
)*(Source
++);
2810 (*DestinationLength
)++;
2815 return RETURN_SUCCESS
;
2819 Convert one Null-terminated ASCII string to a Null-terminated
2822 This function is similar to StrCpyS.
2824 This function converts the contents of the ASCII string Source to the Unicode
2825 string Destination. The function terminates the Unicode string Destination by
2826 appending a Null-terminator character at the end.
2828 The caller is responsible to make sure Destination points to a buffer with size
2829 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2831 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2833 If an error is returned, then the Destination is unmodified.
2835 @param Source The pointer to a Null-terminated ASCII string.
2836 @param Destination The pointer to a Null-terminated Unicode string.
2837 @param DestMax The maximum number of Destination Unicode
2838 char, including terminating null char.
2840 @retval RETURN_SUCCESS String is converted.
2841 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2842 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2844 If PcdMaximumUnicodeStringLength is not zero,
2845 and DestMax is greater than
2846 PcdMaximumUnicodeStringLength.
2847 If PcdMaximumAsciiStringLength is not zero,
2848 and DestMax is greater than
2849 PcdMaximumAsciiStringLength.
2851 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2856 AsciiStrToUnicodeStrS (
2857 IN CONST CHAR8
*Source
,
2858 OUT CHAR16
*Destination
,
2864 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
2867 // 1. Neither Destination nor Source shall be a null pointer.
2869 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2870 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2873 // 2. DestMax shall not be greater than RSIZE_MAX or ASCII_RSIZE_MAX.
2875 if (RSIZE_MAX
!= 0) {
2876 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2879 if (ASCII_RSIZE_MAX
!= 0) {
2880 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2884 // 3. DestMax shall not equal zero.
2886 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2889 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
2891 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
2892 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2895 // 5. Copying shall not take place between objects that overlap.
2897 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof (CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2902 while (*Source
!= '\0') {
2903 *(Destination
++) = (CHAR16
)(UINT8
)*(Source
++);
2906 *Destination
= '\0';
2908 return RETURN_SUCCESS
;
2912 Convert not more than Length successive characters from a Null-terminated
2913 Ascii string to a Null-terminated Unicode string. If no null char is copied
2914 from Source, then Destination[Length] is always set to null.
2916 This function converts not more than Length successive characters from the
2917 Ascii string Source to the Unicode string Destination. The function
2918 terminates the Unicode string Destination by appending a Null-terminator
2919 character at the end.
2921 The caller is responsible to make sure Destination points to a buffer with
2922 size not smaller than
2923 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2925 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2927 If an error is returned, then Destination and DestinationLength are
2930 @param Source The pointer to a Null-terminated Ascii string.
2931 @param Length The maximum number of Ascii characters to convert.
2932 @param Destination The pointer to a Null-terminated Unicode string.
2933 @param DestMax The maximum number of Destination Unicode char,
2934 including terminating null char.
2935 @param DestinationLength The number of Ascii characters converted.
2937 @retval RETURN_SUCCESS String is converted.
2938 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2940 If DestinationLength is NULL.
2941 If PcdMaximumUnicodeStringLength is not
2942 zero, and Length or DestMax is greater than
2943 PcdMaximumUnicodeStringLength.
2944 If PcdMaximumAsciiStringLength is not zero,
2945 and Length or DestMax is greater than
2946 PcdMaximumAsciiStringLength.
2948 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2949 MIN(AsciiStrLen(Source), Length).
2950 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2955 AsciiStrnToUnicodeStrS (
2956 IN CONST CHAR8
*Source
,
2958 OUT CHAR16
*Destination
,
2960 OUT UINTN
*DestinationLength
2965 ASSERT (((UINTN
)Destination
& BIT0
) == 0);
2968 // 1. None of Destination, Source or DestinationLength shall be a null
2971 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2972 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2973 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
2976 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
2979 if (RSIZE_MAX
!= 0) {
2980 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2981 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2984 if (ASCII_RSIZE_MAX
!= 0) {
2985 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2986 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2990 // 3. DestMax shall not equal zero.
2992 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2995 // 4. If Length is not less than DestMax, then DestMax shall be greater than
2996 // AsciiStrnLenS(Source, DestMax).
2998 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
2999 if (Length
>= DestMax
) {
3000 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
3004 // 5. Copying shall not take place between objects that overlap.
3006 if (SourceLen
> Length
) {
3010 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof (CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
3012 *DestinationLength
= 0;
3017 while ((*Source
!= 0) && (SourceLen
> 0)) {
3018 *(Destination
++) = (CHAR16
)(UINT8
)*(Source
++);
3020 (*DestinationLength
)++;
3025 return RETURN_SUCCESS
;
3029 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
3031 This function outputs a value of type IPv6_ADDRESS and may output a value
3032 of type UINT8 by interpreting the contents of the ASCII string specified
3033 by String. The format of the input ASCII string String is as follows:
3037 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
3038 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
3039 memory address and high byte is stored in high memory address. P contains decimal
3040 digit characters in the range [0-9]. The running zero in the beginning of P will
3041 be ignored. /P is optional.
3043 When /P is not in the String, the function stops at the first character that is
3044 not a valid hexadecimal digit character after eight X's are converted.
3046 When /P is in the String, the function stops at the first character that is not
3047 a valid decimal digit character after P is converted.
3049 "::" can be used to compress one or more groups of X when X contains only 0.
3050 The "::" can only appear once in the String.
3052 If EndPointer is not NULL and Address is translated from String, a pointer
3053 to the character that stopped the scan is stored at the location pointed to
3056 @param String Pointer to a Null-terminated ASCII string.
3057 @param EndPointer Pointer to character that stops scan.
3058 @param Address Pointer to the converted IPv6 address.
3059 @param PrefixLength Pointer to the converted IPv6 address prefix
3060 length. MAX_UINT8 is returned when /P is
3063 @retval RETURN_SUCCESS Address is translated from String.
3064 @retval RETURN_INVALID_PARAMETER If String is NULL.
3066 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
3068 If String contains "::" and number of X
3070 If P starts with character that is not a
3071 valid decimal digit character.
3072 If the decimal number converted from P
3078 AsciiStrToIpv6Address (
3079 IN CONST CHAR8
*String
,
3080 OUT CHAR8
**EndPointer OPTIONAL
,
3081 OUT IPv6_ADDRESS
*Address
,
3082 OUT UINT8
*PrefixLength OPTIONAL
3085 RETURN_STATUS Status
;
3088 IPv6_ADDRESS LocalAddress
;
3089 UINT8 LocalPrefixLength
;
3090 CONST CHAR8
*Pointer
;
3092 UINTN CompressStart
;
3093 BOOLEAN ExpectPrefix
;
3095 LocalPrefixLength
= MAX_UINT8
;
3096 CompressStart
= ARRAY_SIZE (Address
->Addr
);
3097 ExpectPrefix
= FALSE
;
3100 // None of String or Address shall be a null pointer.
3102 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3103 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3105 for (Pointer
= String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3106 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3107 if (*Pointer
!= ':') {
3109 // ":" or "/" should be followed by digit characters.
3111 return RETURN_UNSUPPORTED
;
3115 // Meet second ":" after previous ":" or "/"
3116 // or meet first ":" in the beginning of String.
3120 // ":" shall not be after "/"
3122 return RETURN_UNSUPPORTED
;
3125 if ((CompressStart
!= ARRAY_SIZE (Address
->Addr
)) || (AddressIndex
== ARRAY_SIZE (Address
->Addr
))) {
3127 // "::" can only appear once.
3128 // "::" can only appear when address is not full length.
3130 return RETURN_UNSUPPORTED
;
3133 // Remember the start of zero compressing.
3135 CompressStart
= AddressIndex
;
3138 if (CompressStart
== 0) {
3139 if (*Pointer
!= ':') {
3141 // Single ":" shall not be in the beginning of String.
3143 return RETURN_UNSUPPORTED
;
3151 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3152 if (*Pointer
== '/') {
3154 // Might be optional "/P" after "::".
3156 if (CompressStart
!= AddressIndex
) {
3157 return RETURN_UNSUPPORTED
;
3163 if (!ExpectPrefix
) {
3167 Status
= AsciiStrHexToUintnS (Pointer
, &End
, &Uintn
);
3168 if (RETURN_ERROR (Status
) || (End
- Pointer
> 4)) {
3170 // Number of hexadecimal digit characters is no more than 4.
3172 return RETURN_UNSUPPORTED
;
3177 // Uintn won't exceed MAX_UINT16 if number of hexadecimal digit characters is no more than 4.
3179 ASSERT (AddressIndex
+ 1 < ARRAY_SIZE (Address
->Addr
));
3180 LocalAddress
.Addr
[AddressIndex
] = (UINT8
)((UINT16
)Uintn
>> 8);
3181 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
)Uintn
;
3185 // Get P, then exit the loop.
3187 Status
= AsciiStrDecimalToUintnS (Pointer
, &End
, &Uintn
);
3188 if (RETURN_ERROR (Status
) || (End
== Pointer
) || (Uintn
> 128)) {
3190 // Prefix length should not exceed 128.
3192 return RETURN_UNSUPPORTED
;
3195 LocalPrefixLength
= (UINT8
)Uintn
;
3204 if (*Pointer
== '/') {
3205 ExpectPrefix
= TRUE
;
3206 } else if (*Pointer
== ':') {
3207 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3209 // Meet additional ":" after all 8 16-bit address
3215 // Meet other character that is not "/" or ":" after all 8 16-bit address
3223 if (((AddressIndex
== ARRAY_SIZE (Address
->Addr
)) && (CompressStart
!= ARRAY_SIZE (Address
->Addr
))) ||
3224 ((AddressIndex
!= ARRAY_SIZE (Address
->Addr
)) && (CompressStart
== ARRAY_SIZE (Address
->Addr
)))
3228 // Full length of address shall not have compressing zeros.
3229 // Non-full length of address shall have compressing zeros.
3231 return RETURN_UNSUPPORTED
;
3234 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
3235 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
3236 if (AddressIndex
> CompressStart
) {
3238 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
3239 &LocalAddress
.Addr
[CompressStart
],
3240 AddressIndex
- CompressStart
3244 if (PrefixLength
!= NULL
) {
3245 *PrefixLength
= LocalPrefixLength
;
3248 if (EndPointer
!= NULL
) {
3249 *EndPointer
= (CHAR8
*)Pointer
;
3252 return RETURN_SUCCESS
;
3256 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
3258 This function outputs a value of type IPv4_ADDRESS and may output a value
3259 of type UINT8 by interpreting the contents of the ASCII string specified
3260 by String. The format of the input ASCII string String is as follows:
3264 D and P are decimal digit characters in the range [0-9]. The running zero in
3265 the beginning of D and P will be ignored. /P is optional.
3267 When /P is not in the String, the function stops at the first character that is
3268 not a valid decimal digit character after four D's are converted.
3270 When /P is in the String, the function stops at the first character that is not
3271 a valid decimal digit character after P is converted.
3273 If EndPointer is not NULL and Address is translated from String, a pointer
3274 to the character that stopped the scan is stored at the location pointed to
3277 @param String Pointer to a Null-terminated ASCII string.
3278 @param EndPointer Pointer to character that stops scan.
3279 @param Address Pointer to the converted IPv4 address.
3280 @param PrefixLength Pointer to the converted IPv4 address prefix
3281 length. MAX_UINT8 is returned when /P is
3284 @retval RETURN_SUCCESS Address is translated from String.
3285 @retval RETURN_INVALID_PARAMETER If String is NULL.
3287 @retval RETURN_UNSUPPORTED If String is not in the correct format.
3288 If any decimal number converted from D
3290 If the decimal number converted from P
3296 AsciiStrToIpv4Address (
3297 IN CONST CHAR8
*String
,
3298 OUT CHAR8
**EndPointer OPTIONAL
,
3299 OUT IPv4_ADDRESS
*Address
,
3300 OUT UINT8
*PrefixLength OPTIONAL
3303 RETURN_STATUS Status
;
3306 IPv4_ADDRESS LocalAddress
;
3307 UINT8 LocalPrefixLength
;
3310 LocalPrefixLength
= MAX_UINT8
;
3313 // None of String or Address shall be a null pointer.
3315 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3316 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3318 for (Pointer
= (CHAR8
*)String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3319 if (!InternalAsciiIsDecimalDigitCharacter (*Pointer
)) {
3321 // D or P contains invalid characters.
3329 Status
= AsciiStrDecimalToUintnS ((CONST CHAR8
*)Pointer
, &Pointer
, &Uintn
);
3330 if (RETURN_ERROR (Status
)) {
3331 return RETURN_UNSUPPORTED
;
3334 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3339 return RETURN_UNSUPPORTED
;
3342 LocalPrefixLength
= (UINT8
)Uintn
;
3347 if (Uintn
> MAX_UINT8
) {
3348 return RETURN_UNSUPPORTED
;
3351 LocalAddress
.Addr
[AddressIndex
] = (UINT8
)Uintn
;
3356 // Check the '.' or '/', depending on the AddressIndex.
3358 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3359 if (*Pointer
== '/') {
3361 // '/P' is in the String.
3362 // Skip "/" and get P in next loop.
3367 // '/P' is not in the String.
3371 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3372 if (*Pointer
== '.') {
3374 // D should be followed by '.'
3378 return RETURN_UNSUPPORTED
;
3383 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3384 return RETURN_UNSUPPORTED
;
3387 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
3388 if (PrefixLength
!= NULL
) {
3389 *PrefixLength
= LocalPrefixLength
;
3392 if (EndPointer
!= NULL
) {
3393 *EndPointer
= Pointer
;
3396 return RETURN_SUCCESS
;
3400 Convert a Null-terminated ASCII GUID string to a value of type
3403 This function outputs a GUID value by interpreting the contents of
3404 the ASCII string specified by String. The format of the input
3405 ASCII string String consists of 36 characters, as follows:
3407 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
3409 The pairs aa - pp are two characters in the range [0-9], [a-f] and
3410 [A-F], with each pair representing a single byte hexadecimal value.
3412 The mapping between String and the EFI_GUID structure is as follows:
3430 @param String Pointer to a Null-terminated ASCII string.
3431 @param Guid Pointer to the converted GUID.
3433 @retval RETURN_SUCCESS Guid is translated from String.
3434 @retval RETURN_INVALID_PARAMETER If String is NULL.
3436 @retval RETURN_UNSUPPORTED If String is not as the above format.
3442 IN CONST CHAR8
*String
,
3446 RETURN_STATUS Status
;
3450 // None of String or Guid shall be a null pointer.
3452 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3453 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
3456 // Get aabbccdd in big-endian.
3458 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*)&LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
3459 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data1
)] != '-')) {
3460 return RETURN_UNSUPPORTED
;
3464 // Convert big-endian to little-endian.
3466 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
3467 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
3470 // Get eeff in big-endian.
3472 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*)&LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
3473 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data2
)] != '-')) {
3474 return RETURN_UNSUPPORTED
;
3478 // Convert big-endian to little-endian.
3480 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
3481 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
3484 // Get gghh in big-endian.
3486 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*)&LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
3487 if (RETURN_ERROR (Status
) || (String
[2 * sizeof (LocalGuid
.Data3
)] != '-')) {
3488 return RETURN_UNSUPPORTED
;
3492 // Convert big-endian to little-endian.
3494 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
3495 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
3500 Status
= AsciiStrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
3501 if (RETURN_ERROR (Status
) || (String
[2 * 2] != '-')) {
3502 return RETURN_UNSUPPORTED
;
3505 String
+= 2 * 2 + 1;
3508 // Get kkllmmnnoopp.
3510 Status
= AsciiStrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
3511 if (RETURN_ERROR (Status
)) {
3512 return RETURN_UNSUPPORTED
;
3515 CopyGuid (Guid
, &LocalGuid
);
3516 return RETURN_SUCCESS
;
3520 Convert a Null-terminated ASCII hexadecimal string to a byte array.
3522 This function outputs a byte array by interpreting the contents of
3523 the ASCII string specified by String in hexadecimal format. The format of
3524 the input ASCII string String is:
3528 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
3529 The function decodes every two hexadecimal digit characters as one byte. The
3530 decoding stops after Length of characters and outputs Buffer containing
3533 @param String Pointer to a Null-terminated ASCII string.
3534 @param Length The number of ASCII characters to decode.
3535 @param Buffer Pointer to the converted bytes array.
3536 @param MaxBufferSize The maximum size of Buffer.
3538 @retval RETURN_SUCCESS Buffer is translated from String.
3539 @retval RETURN_INVALID_PARAMETER If String is NULL.
3541 If Length is not multiple of 2.
3542 If PcdMaximumAsciiStringLength is not zero,
3543 and Length is greater than
3544 PcdMaximumAsciiStringLength.
3545 @retval RETURN_UNSUPPORTED If Length of characters from String contain
3546 a character that is not valid hexadecimal
3547 digit characters, or a Null-terminator.
3548 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
3552 AsciiStrHexToBytes (
3553 IN CONST CHAR8
*String
,
3556 IN UINTN MaxBufferSize
3562 // 1. None of String or Buffer shall be a null pointer.
3564 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3565 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
3568 // 2. Length shall not be greater than ASCII_RSIZE_MAX.
3570 if (ASCII_RSIZE_MAX
!= 0) {
3571 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3575 // 3. Length shall not be odd.
3577 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
3580 // 4. MaxBufferSize shall equal to or greater than Length / 2.
3582 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
3585 // 5. String shall not contains invalid hexadecimal digits.
3587 for (Index
= 0; Index
< Length
; Index
++) {
3588 if (!InternalAsciiIsHexaDecimalDigitCharacter (String
[Index
])) {
3593 if (Index
!= Length
) {
3594 return RETURN_UNSUPPORTED
;
3598 // Convert the hex string to bytes.
3600 for (Index
= 0; Index
< Length
; Index
++) {
3602 // For even characters, write the upper nibble for each buffer byte,
3603 // and for even characters, the lower nibble.
3605 if ((Index
& BIT0
) == 0) {
3606 Buffer
[Index
/ 2] = (UINT8
)InternalAsciiHexCharToUintn (String
[Index
]) << 4;
3608 Buffer
[Index
/ 2] |= (UINT8
)InternalAsciiHexCharToUintn (String
[Index
]);
3612 return RETURN_SUCCESS
;