4 Copyright (c) 2014 - 2017, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #include "BaseLibInternals.h"
17 #define RSIZE_MAX (PcdGet32 (PcdMaximumUnicodeStringLength))
19 #define ASCII_RSIZE_MAX (PcdGet32 (PcdMaximumAsciiStringLength))
21 #define SAFE_STRING_CONSTRAINT_CHECK(Expression, Status) \
23 ASSERT (Expression); \
24 if (!(Expression)) { \
30 Returns if 2 memory blocks are overlapped.
32 @param Base1 Base address of 1st memory block.
33 @param Size1 Size of 1st memory block.
34 @param Base2 Base address of 2nd memory block.
35 @param Size2 Size of 2nd memory block.
37 @retval TRUE 2 memory blocks are overlapped.
38 @retval FALSE 2 memory blocks are not overlapped.
41 InternalSafeStringIsOverlap (
48 if ((((UINTN
)Base1
>= (UINTN
)Base2
) && ((UINTN
)Base1
< (UINTN
)Base2
+ Size2
)) ||
49 (((UINTN
)Base2
>= (UINTN
)Base1
) && ((UINTN
)Base2
< (UINTN
)Base1
+ Size1
))) {
56 Returns if 2 Unicode strings are not overlapped.
58 @param Str1 Start address of 1st Unicode string.
59 @param Size1 The number of char in 1st Unicode string,
60 including terminating null char.
61 @param Str2 Start address of 2nd Unicode string.
62 @param Size2 The number of char in 2nd Unicode string,
63 including terminating null char.
65 @retval TRUE 2 Unicode strings are NOT overlapped.
66 @retval FALSE 2 Unicode strings are overlapped.
69 InternalSafeStringNoStrOverlap (
76 return !InternalSafeStringIsOverlap (Str1
, Size1
* sizeof(CHAR16
), Str2
, Size2
* sizeof(CHAR16
));
80 Returns if 2 Ascii strings are not overlapped.
82 @param Str1 Start address of 1st Ascii string.
83 @param Size1 The number of char in 1st Ascii string,
84 including terminating null char.
85 @param Str2 Start address of 2nd Ascii string.
86 @param Size2 The number of char in 2nd Ascii string,
87 including terminating null char.
89 @retval TRUE 2 Ascii strings are NOT overlapped.
90 @retval FALSE 2 Ascii strings are overlapped.
93 InternalSafeStringNoAsciiStrOverlap (
100 return !InternalSafeStringIsOverlap (Str1
, Size1
, Str2
, Size2
);
104 Returns the length of a Null-terminated Unicode string.
106 This function is similar as strlen_s defined in C11.
108 If String is not aligned on a 16-bit boundary, then ASSERT().
110 @param String A pointer to a Null-terminated Unicode string.
111 @param MaxSize The maximum number of Destination Unicode
112 char, including terminating null char.
114 @retval 0 If String is NULL.
115 @retval MaxSize If there is no null character in the first MaxSize characters of String.
116 @return The number of characters that percede the terminating null character.
122 IN CONST CHAR16
*String
,
128 ASSERT (((UINTN
) String
& BIT0
) == 0);
131 // If String is a null pointer or MaxSize is 0, then the StrnLenS function returns zero.
133 if ((String
== NULL
) || (MaxSize
== 0)) {
138 // Otherwise, the StrnLenS function returns the number of characters that precede the
139 // terminating null character. If there is no null character in the first MaxSize characters of
140 // String then StrnLenS returns MaxSize. At most the first MaxSize characters of String shall
141 // be accessed by StrnLenS.
144 while (String
[Length
] != 0) {
145 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().
206 If an error would be returned, then the function will also ASSERT().
208 If an error is returned, then the Destination is unmodified.
210 @param Destination A pointer to a Null-terminated Unicode string.
211 @param DestMax The maximum number of Destination Unicode
212 char, including terminating null char.
213 @param Source A pointer to a Null-terminated Unicode string.
215 @retval RETURN_SUCCESS String is copied.
216 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
217 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
219 If PcdMaximumUnicodeStringLength is not zero,
220 and DestMax is greater than
221 PcdMaximumUnicodeStringLength.
223 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
228 OUT CHAR16
*Destination
,
230 IN CONST CHAR16
*Source
235 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
236 ASSERT (((UINTN
) Source
& BIT0
) == 0);
239 // 1. Neither Destination nor Source shall be a null pointer.
241 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
242 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
245 // 2. DestMax shall not be greater than RSIZE_MAX.
247 if (RSIZE_MAX
!= 0) {
248 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
252 // 3. DestMax shall not equal zero.
254 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
257 // 4. DestMax shall be greater than StrnLenS(Source, DestMax).
259 SourceLen
= StrnLenS (Source
, DestMax
);
260 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
263 // 5. Copying shall not take place between objects that overlap.
265 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
268 // The StrCpyS function copies the string pointed to by Source (including the terminating
269 // null character) into the array pointed to by Destination.
271 while (*Source
!= 0) {
272 *(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().
288 If an error would be returned, then the function will also ASSERT().
290 If an error is returned, then the Destination is unmodified.
292 @param Destination A pointer to a Null-terminated Unicode string.
293 @param DestMax The maximum number of Destination Unicode
294 char, including terminating null char.
295 @param Source A pointer to a Null-terminated Unicode string.
296 @param Length The maximum number of Unicode characters to copy.
298 @retval RETURN_SUCCESS String is copied.
299 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
300 MIN(StrLen(Source), Length).
301 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
303 If PcdMaximumUnicodeStringLength is not zero,
304 and DestMax is greater than
305 PcdMaximumUnicodeStringLength.
307 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
312 OUT CHAR16
*Destination
,
314 IN CONST CHAR16
*Source
,
320 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
321 ASSERT (((UINTN
) Source
& BIT0
) == 0);
324 // 1. Neither Destination nor Source shall be a null pointer.
326 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
327 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
330 // 2. Neither DestMax nor Length shall be greater than RSIZE_MAX
332 if (RSIZE_MAX
!= 0) {
333 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
334 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
338 // 3. DestMax shall not equal zero.
340 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
343 // 4. If Length is not less than DestMax, then DestMax shall be greater than StrnLenS(Source, DestMax).
345 SourceLen
= StrnLenS (Source
, DestMax
);
346 if (Length
>= DestMax
) {
347 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
351 // 5. Copying shall not take place between objects that overlap.
353 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 ((*Source
!= 0) && (SourceLen
> 0)) {
365 *(Destination
++) = *(Source
++);
370 return RETURN_SUCCESS
;
374 Appends a copy of the string pointed to by Source (including the terminating
375 null char) to the end of the string pointed to by Destination.
377 This function is similar as strcat_s defined in C11.
379 If Destination is not aligned on a 16-bit boundary, then ASSERT().
380 If Source is not aligned on a 16-bit boundary, then ASSERT().
381 If an error would be returned, then the function will also 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
++);
469 return RETURN_SUCCESS
;
473 Appends not more than Length successive char from the string pointed to by
474 Source to the end of the string pointed to by Destination. If no null char is
475 copied from Source, then Destination[StrLen(Destination) + Length] is always
478 This function is similar as strncat_s defined in C11.
480 If Destination is not aligned on a 16-bit boundary, then ASSERT().
481 If Source is not aligned on a 16-bit boundary, then ASSERT().
482 If an error would be returned, then the function will also 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
, CopyLen
);
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
) {
565 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoStrOverlap (Destination
, DestMax
, (CHAR16
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
568 // The StrnCatS function appends not more than Length successive characters (characters
569 // that follow a null character are not copied) from the array pointed to by Source to the end of
570 // the string pointed to by Destination. The initial character from Source overwrites the null character at
571 // the end of Destination. If no null character was copied from Source, then Destination[DestMax-CopyLen+Length] is set to
574 Destination
= Destination
+ DestLen
;
575 while ((*Source
!= 0) && (SourceLen
> 0)) {
576 *(Destination
++) = *(Source
++);
581 return RETURN_SUCCESS
;
585 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
587 This function outputs a value of type UINTN by interpreting the contents of
588 the Unicode string specified by String as a decimal number. The format of the
589 input Unicode string String is:
591 [spaces] [decimal digits].
593 The valid decimal digit character is in the range [0-9]. The function will
594 ignore the pad space, which includes spaces or tab characters, before
595 [decimal digits]. The running zero in the beginning of [decimal digits] will
596 be ignored. Then, the function stops at the first character that is a not a
597 valid decimal character or a Null-terminator, whichever one comes first.
599 If String is NULL, then ASSERT().
600 If Data is NULL, then ASSERT().
601 If String is not aligned in a 16-bit boundary, then ASSERT().
602 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
603 PcdMaximumUnicodeStringLength Unicode characters, not including the
604 Null-terminator, then ASSERT().
606 If String has no valid decimal digits in the above format, then 0 is stored
607 at the location pointed to by Data.
608 If the number represented by String exceeds the range defined by UINTN, then
609 MAX_UINTN is stored at the location pointed to by Data.
611 If EndPointer is not NULL, a pointer to the character that stopped the scan
612 is stored at the location pointed to by EndPointer. If String has no valid
613 decimal digits right after the optional pad spaces, the value of String is
614 stored at the location pointed to by EndPointer.
616 @param String Pointer to a Null-terminated Unicode string.
617 @param EndPointer Pointer to character that stops scan.
618 @param Data Pointer to the converted value.
620 @retval RETURN_SUCCESS Value is translated from String.
621 @retval RETURN_INVALID_PARAMETER If String is NULL.
623 If PcdMaximumUnicodeStringLength is not
624 zero, and String contains more than
625 PcdMaximumUnicodeStringLength Unicode
626 characters, not including the
628 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
629 the range defined by UINTN.
635 IN CONST CHAR16
*String
,
636 OUT CHAR16
**EndPointer
, OPTIONAL
640 ASSERT (((UINTN
) String
& BIT0
) == 0);
643 // 1. Neither String nor Data shall be a null pointer.
645 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
646 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
649 // 2. The length of String shall not be greater than RSIZE_MAX.
651 if (RSIZE_MAX
!= 0) {
652 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
655 if (EndPointer
!= NULL
) {
656 *EndPointer
= (CHAR16
*) String
;
660 // Ignore the pad spaces (space or tab)
662 while ((*String
== L
' ') || (*String
== L
'\t')) {
667 // Ignore leading Zeros after the spaces
669 while (*String
== L
'0') {
675 while (InternalIsDecimalDigitCharacter (*String
)) {
677 // If the number represented by String overflows according to the range
678 // defined by UINTN, then MAX_UINTN is stored in *Data and
679 // RETURN_UNSUPPORTED is returned.
681 if (*Data
> ((MAX_UINTN
- (*String
- L
'0')) / 10)) {
683 if (EndPointer
!= NULL
) {
684 *EndPointer
= (CHAR16
*) String
;
686 return RETURN_UNSUPPORTED
;
689 *Data
= *Data
* 10 + (*String
- L
'0');
693 if (EndPointer
!= NULL
) {
694 *EndPointer
= (CHAR16
*) String
;
696 return RETURN_SUCCESS
;
700 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
702 This function outputs a value of type UINT64 by interpreting the contents of
703 the Unicode string specified by String as a decimal number. The format of the
704 input Unicode string String is:
706 [spaces] [decimal digits].
708 The valid decimal digit character is in the range [0-9]. The function will
709 ignore the pad space, which includes spaces or tab characters, before
710 [decimal digits]. The running zero in the beginning of [decimal digits] will
711 be ignored. Then, the function stops at the first character that is a not a
712 valid decimal character or a Null-terminator, whichever one comes first.
714 If String is NULL, then ASSERT().
715 If Data is NULL, then ASSERT().
716 If String is not aligned in a 16-bit boundary, then ASSERT().
717 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
718 PcdMaximumUnicodeStringLength Unicode characters, not including the
719 Null-terminator, then ASSERT().
721 If String has no valid decimal digits in the above format, then 0 is stored
722 at the location pointed to by Data.
723 If the number represented by String exceeds the range defined by UINT64, then
724 MAX_UINT64 is stored at the location pointed to by Data.
726 If EndPointer is not NULL, a pointer to the character that stopped the scan
727 is stored at the location pointed to by EndPointer. If String has no valid
728 decimal digits right after the optional pad spaces, the value of String is
729 stored at the location pointed to by EndPointer.
731 @param String Pointer to a Null-terminated Unicode string.
732 @param EndPointer Pointer to character that stops scan.
733 @param Data Pointer to the converted value.
735 @retval RETURN_SUCCESS Value is translated from String.
736 @retval RETURN_INVALID_PARAMETER If String is NULL.
738 If PcdMaximumUnicodeStringLength is not
739 zero, and String contains more than
740 PcdMaximumUnicodeStringLength Unicode
741 characters, not including the
743 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
744 the range defined by UINT64.
749 StrDecimalToUint64S (
750 IN CONST CHAR16
*String
,
751 OUT CHAR16
**EndPointer
, OPTIONAL
755 ASSERT (((UINTN
) String
& BIT0
) == 0);
758 // 1. Neither String nor Data shall be a null pointer.
760 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
761 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
764 // 2. The length of String shall not be greater than RSIZE_MAX.
766 if (RSIZE_MAX
!= 0) {
767 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
770 if (EndPointer
!= NULL
) {
771 *EndPointer
= (CHAR16
*) String
;
775 // Ignore the pad spaces (space or tab)
777 while ((*String
== L
' ') || (*String
== L
'\t')) {
782 // Ignore leading Zeros after the spaces
784 while (*String
== L
'0') {
790 while (InternalIsDecimalDigitCharacter (*String
)) {
792 // If the number represented by String overflows according to the range
793 // defined by UINT64, then MAX_UINT64 is stored in *Data and
794 // RETURN_UNSUPPORTED is returned.
796 if (*Data
> DivU64x32 (MAX_UINT64
- (*String
- L
'0'), 10)) {
798 if (EndPointer
!= NULL
) {
799 *EndPointer
= (CHAR16
*) String
;
801 return RETURN_UNSUPPORTED
;
804 *Data
= MultU64x32 (*Data
, 10) + (*String
- L
'0');
808 if (EndPointer
!= NULL
) {
809 *EndPointer
= (CHAR16
*) String
;
811 return RETURN_SUCCESS
;
815 Convert a Null-terminated Unicode hexadecimal string to a value of type
818 This function outputs a value of type UINTN by interpreting the contents of
819 the Unicode string specified by String as a hexadecimal number. The format of
820 the input Unicode string String is:
822 [spaces][zeros][x][hexadecimal digits].
824 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
825 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
826 If "x" appears in the input string, it must be prefixed with at least one 0.
827 The function will ignore the pad space, which includes spaces or tab
828 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
829 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
830 after [x] or the first valid hexadecimal digit. Then, the function stops at
831 the first character that is a not a valid hexadecimal character or NULL,
832 whichever one comes first.
834 If String is NULL, then ASSERT().
835 If Data is NULL, then ASSERT().
836 If String is not aligned in a 16-bit boundary, then ASSERT().
837 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
838 PcdMaximumUnicodeStringLength Unicode characters, not including the
839 Null-terminator, then ASSERT().
841 If String has no valid hexadecimal digits in the above format, then 0 is
842 stored at the location pointed to by Data.
843 If the number represented by String exceeds the range defined by UINTN, then
844 MAX_UINTN is stored at the location pointed to by Data.
846 If EndPointer is not NULL, a pointer to the character that stopped the scan
847 is stored at the location pointed to by EndPointer. If String has no valid
848 hexadecimal digits right after the optional pad spaces, the value of String
849 is stored at the location pointed to by EndPointer.
851 @param String Pointer to a Null-terminated Unicode string.
852 @param EndPointer Pointer to character that stops scan.
853 @param Data Pointer to the converted value.
855 @retval RETURN_SUCCESS Value is translated from String.
856 @retval RETURN_INVALID_PARAMETER If String is NULL.
858 If PcdMaximumUnicodeStringLength is not
859 zero, and String contains more than
860 PcdMaximumUnicodeStringLength Unicode
861 characters, not including the
863 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
864 the range defined by UINTN.
870 IN CONST CHAR16
*String
,
871 OUT CHAR16
**EndPointer
, OPTIONAL
875 ASSERT (((UINTN
) String
& BIT0
) == 0);
878 // 1. Neither String nor Data shall be a null pointer.
880 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
881 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
884 // 2. The length of String shall not be greater than RSIZE_MAX.
886 if (RSIZE_MAX
!= 0) {
887 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
890 if (EndPointer
!= NULL
) {
891 *EndPointer
= (CHAR16
*) String
;
895 // Ignore the pad spaces (space or tab)
897 while ((*String
== L
' ') || (*String
== L
'\t')) {
902 // Ignore leading Zeros after the spaces
904 while (*String
== L
'0') {
908 if (InternalCharToUpper (*String
) == L
'X') {
909 if (*(String
- 1) != L
'0') {
911 return RETURN_SUCCESS
;
921 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
923 // If the number represented by String overflows according to the range
924 // defined by UINTN, then MAX_UINTN is stored in *Data and
925 // RETURN_UNSUPPORTED is returned.
927 if (*Data
> ((MAX_UINTN
- InternalHexCharToUintn (*String
)) >> 4)) {
929 if (EndPointer
!= NULL
) {
930 *EndPointer
= (CHAR16
*) String
;
932 return RETURN_UNSUPPORTED
;
935 *Data
= (*Data
<< 4) + InternalHexCharToUintn (*String
);
939 if (EndPointer
!= NULL
) {
940 *EndPointer
= (CHAR16
*) String
;
942 return RETURN_SUCCESS
;
946 Convert a Null-terminated Unicode hexadecimal string to a value of type
949 This function outputs a value of type UINT64 by interpreting the contents of
950 the Unicode string specified by String as a hexadecimal number. The format of
951 the input Unicode string String is:
953 [spaces][zeros][x][hexadecimal digits].
955 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
956 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
957 If "x" appears in the input string, it must be prefixed with at least one 0.
958 The function will ignore the pad space, which includes spaces or tab
959 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
960 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
961 after [x] or the first valid hexadecimal digit. Then, the function stops at
962 the first character that is a not a valid hexadecimal character or NULL,
963 whichever one comes first.
965 If String is NULL, then ASSERT().
966 If Data is NULL, then ASSERT().
967 If String is not aligned in a 16-bit boundary, then ASSERT().
968 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
969 PcdMaximumUnicodeStringLength Unicode characters, not including the
970 Null-terminator, then ASSERT().
972 If String has no valid hexadecimal digits in the above format, then 0 is
973 stored at the location pointed to by Data.
974 If the number represented by String exceeds the range defined by UINT64, then
975 MAX_UINT64 is stored at the location pointed to by Data.
977 If EndPointer is not NULL, a pointer to the character that stopped the scan
978 is stored at the location pointed to by EndPointer. If String has no valid
979 hexadecimal digits right after the optional pad spaces, the value of String
980 is stored at the location pointed to by EndPointer.
982 @param String Pointer to a Null-terminated Unicode string.
983 @param EndPointer Pointer to character that stops scan.
984 @param Data Pointer to the converted value.
986 @retval RETURN_SUCCESS Value is translated from String.
987 @retval RETURN_INVALID_PARAMETER If String is NULL.
989 If PcdMaximumUnicodeStringLength is not
990 zero, and String contains more than
991 PcdMaximumUnicodeStringLength Unicode
992 characters, not including the
994 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
995 the range defined by UINT64.
1001 IN CONST CHAR16
*String
,
1002 OUT CHAR16
**EndPointer
, OPTIONAL
1006 ASSERT (((UINTN
) String
& BIT0
) == 0);
1009 // 1. Neither String nor Data shall be a null pointer.
1011 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1012 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
1015 // 2. The length of String shall not be greater than RSIZE_MAX.
1017 if (RSIZE_MAX
!= 0) {
1018 SAFE_STRING_CONSTRAINT_CHECK ((StrnLenS (String
, RSIZE_MAX
+ 1) <= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1021 if (EndPointer
!= NULL
) {
1022 *EndPointer
= (CHAR16
*) String
;
1026 // Ignore the pad spaces (space or tab)
1028 while ((*String
== L
' ') || (*String
== L
'\t')) {
1033 // Ignore leading Zeros after the spaces
1035 while (*String
== L
'0') {
1039 if (InternalCharToUpper (*String
) == L
'X') {
1040 if (*(String
- 1) != L
'0') {
1042 return RETURN_SUCCESS
;
1052 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
1054 // If the number represented by String overflows according to the range
1055 // defined by UINT64, then MAX_UINT64 is stored in *Data and
1056 // RETURN_UNSUPPORTED is returned.
1058 if (*Data
> RShiftU64 (MAX_UINT64
- InternalHexCharToUintn (*String
), 4)) {
1060 if (EndPointer
!= NULL
) {
1061 *EndPointer
= (CHAR16
*) String
;
1063 return RETURN_UNSUPPORTED
;
1066 *Data
= LShiftU64 (*Data
, 4) + InternalHexCharToUintn (*String
);
1070 if (EndPointer
!= NULL
) {
1071 *EndPointer
= (CHAR16
*) String
;
1073 return RETURN_SUCCESS
;
1077 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1079 This function outputs a value of type IPv6_ADDRESS and may output a value
1080 of type UINT8 by interpreting the contents of the Unicode string specified
1081 by String. The format of the input Unicode string String is as follows:
1085 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1086 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1087 memory address and high byte is stored in high memory address. P contains decimal
1088 digit characters in the range [0-9]. The running zero in the beginning of P will
1089 be ignored. /P is optional.
1091 When /P is not in the String, the function stops at the first character that is
1092 not a valid hexadecimal digit character after eight X's are converted.
1094 When /P is in the String, the function stops at the first character that is not
1095 a valid decimal digit character after P is converted.
1097 "::" can be used to compress one or more groups of X when X contains only 0.
1098 The "::" can only appear once in the String.
1100 If String is NULL, then ASSERT().
1102 If Address is NULL, then ASSERT().
1104 If String is not aligned in a 16-bit boundary, then ASSERT().
1106 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1107 PcdMaximumUnicodeStringLength Unicode characters, not including the
1108 Null-terminator, then ASSERT().
1110 If EndPointer is not NULL and Address is translated from String, a pointer
1111 to the character that stopped the scan is stored at the location pointed to
1114 @param String Pointer to a Null-terminated Unicode string.
1115 @param EndPointer Pointer to character that stops scan.
1116 @param Address Pointer to the converted IPv6 address.
1117 @param PrefixLength Pointer to the converted IPv6 address prefix
1118 length. MAX_UINT8 is returned when /P is
1121 @retval RETURN_SUCCESS Address is translated from String.
1122 @retval RETURN_INVALID_PARAMETER If String is NULL.
1124 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1126 If String contains "::" and number of X
1128 If P starts with character that is not a
1129 valid decimal digit character.
1130 If the decimal number converted from P
1137 IN CONST CHAR16
*String
,
1138 OUT CHAR16
**EndPointer
, OPTIONAL
1139 OUT IPv6_ADDRESS
*Address
,
1140 OUT UINT8
*PrefixLength OPTIONAL
1143 RETURN_STATUS Status
;
1146 IPv6_ADDRESS LocalAddress
;
1147 UINT8 LocalPrefixLength
;
1148 CONST CHAR16
*Pointer
;
1150 UINTN CompressStart
;
1151 BOOLEAN ExpectPrefix
;
1153 LocalPrefixLength
= MAX_UINT8
;
1154 CompressStart
= ARRAY_SIZE (Address
->Addr
);
1155 ExpectPrefix
= FALSE
;
1157 ASSERT (((UINTN
) String
& BIT0
) == 0);
1160 // 1. None of String or Guid shall be a null pointer.
1162 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1163 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
1165 for (Pointer
= String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
1166 if (!InternalIsHexaDecimalDigitCharacter (*Pointer
)) {
1167 if (*Pointer
!= L
':') {
1169 // ":" or "/" should be followed by digit characters.
1171 return RETURN_UNSUPPORTED
;
1175 // Meet second ":" after previous ":" or "/"
1176 // or meet first ":" in the beginning of String.
1180 // ":" shall not be after "/"
1182 return RETURN_UNSUPPORTED
;
1185 if (CompressStart
!= ARRAY_SIZE (Address
->Addr
) || AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1187 // "::" can only appear once.
1188 // "::" can only appear when address is not full length.
1190 return RETURN_UNSUPPORTED
;
1193 // Remember the start of zero compressing.
1195 CompressStart
= AddressIndex
;
1198 if (CompressStart
== 0) {
1199 if (*Pointer
!= L
':') {
1201 // Single ":" shall not be in the beginning of String.
1203 return RETURN_UNSUPPORTED
;
1210 if (!InternalIsHexaDecimalDigitCharacter (*Pointer
)) {
1211 if (*Pointer
== L
'/') {
1213 // Might be optional "/P" after "::".
1215 if (CompressStart
!= AddressIndex
) {
1216 return RETURN_UNSUPPORTED
;
1222 if (!ExpectPrefix
) {
1226 Status
= StrHexToUintnS (Pointer
, &End
, &Uintn
);
1227 if (RETURN_ERROR (Status
) || End
- Pointer
> 4) {
1229 // Number of hexadecimal digit characters is no more than 4.
1231 return RETURN_UNSUPPORTED
;
1235 // Uintn won't exceed MAX_UINT16 if number of hexadecimal digit characters is no more than 4.
1237 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) ((UINT16
) Uintn
>> 8);
1238 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
) Uintn
;
1242 // Get P, then exit the loop.
1244 Status
= StrDecimalToUintnS (Pointer
, &End
, &Uintn
);
1245 if (RETURN_ERROR (Status
) || End
== Pointer
|| Uintn
> 128) {
1247 // Prefix length should not exceed 128.
1249 return RETURN_UNSUPPORTED
;
1251 LocalPrefixLength
= (UINT8
) Uintn
;
1260 if (*Pointer
== L
'/') {
1261 ExpectPrefix
= TRUE
;
1262 } else if (*Pointer
== L
':') {
1263 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1265 // Meet additional ":" after all 8 16-bit address
1271 // Meet other character that is not "/" or ":" after all 8 16-bit address
1278 if ((AddressIndex
== ARRAY_SIZE (Address
->Addr
) && CompressStart
!= ARRAY_SIZE (Address
->Addr
)) ||
1279 (AddressIndex
!= ARRAY_SIZE (Address
->Addr
) && CompressStart
== ARRAY_SIZE (Address
->Addr
))
1282 // Full length of address shall not have compressing zeros.
1283 // Non-full length of address shall have compressing zeros.
1285 return RETURN_UNSUPPORTED
;
1287 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
1288 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
1290 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
1291 &LocalAddress
.Addr
[CompressStart
],
1292 AddressIndex
- CompressStart
1295 if (PrefixLength
!= NULL
) {
1296 *PrefixLength
= LocalPrefixLength
;
1298 if (EndPointer
!= NULL
) {
1299 *EndPointer
= (CHAR16
*) Pointer
;
1302 return RETURN_SUCCESS
;
1306 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1308 This function outputs a value of type IPv4_ADDRESS and may output a value
1309 of type UINT8 by interpreting the contents of the Unicode string specified
1310 by String. The format of the input Unicode string String is as follows:
1314 D and P are decimal digit characters in the range [0-9]. The running zero in
1315 the beginning of D and P will be ignored. /P is optional.
1317 When /P is not in the String, the function stops at the first character that is
1318 not a valid decimal digit character after four D's are converted.
1320 When /P is in the String, the function stops at the first character that is not
1321 a valid decimal digit character after P is converted.
1323 If String is NULL, then ASSERT().
1325 If Address is NULL, then ASSERT().
1327 If String is not aligned in a 16-bit boundary, then ASSERT().
1329 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1330 PcdMaximumUnicodeStringLength Unicode characters, not including the
1331 Null-terminator, then ASSERT().
1333 If EndPointer is not NULL and Address is translated from String, a pointer
1334 to the character that stopped the scan is stored at the location pointed to
1337 @param String Pointer to a Null-terminated Unicode string.
1338 @param EndPointer Pointer to character that stops scan.
1339 @param Address Pointer to the converted IPv4 address.
1340 @param PrefixLength Pointer to the converted IPv4 address prefix
1341 length. MAX_UINT8 is returned when /P is
1344 @retval RETURN_SUCCESS Address is translated from String.
1345 @retval RETURN_INVALID_PARAMETER If String is NULL.
1347 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1348 If any decimal number converted from D
1350 If the decimal number converted from P
1357 IN CONST CHAR16
*String
,
1358 OUT CHAR16
**EndPointer
, OPTIONAL
1359 OUT IPv4_ADDRESS
*Address
,
1360 OUT UINT8
*PrefixLength OPTIONAL
1363 RETURN_STATUS Status
;
1366 IPv4_ADDRESS LocalAddress
;
1367 UINT8 LocalPrefixLength
;
1370 LocalPrefixLength
= MAX_UINT8
;
1372 ASSERT (((UINTN
) String
& BIT0
) == 0);
1375 // 1. None of String or Guid shall be a null pointer.
1377 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1378 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
1380 for (Pointer
= (CHAR16
*) String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
1381 if (!InternalIsDecimalDigitCharacter (*Pointer
)) {
1383 // D or P contains invalid characters.
1391 Status
= StrDecimalToUintnS ((CONST CHAR16
*) Pointer
, &Pointer
, &Uintn
);
1392 if (RETURN_ERROR (Status
)) {
1393 return RETURN_UNSUPPORTED
;
1395 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1400 return RETURN_UNSUPPORTED
;
1402 LocalPrefixLength
= (UINT8
) Uintn
;
1407 if (Uintn
> MAX_UINT8
) {
1408 return RETURN_UNSUPPORTED
;
1410 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) Uintn
;
1415 // Check the '.' or '/', depending on the AddressIndex.
1417 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1418 if (*Pointer
== L
'/') {
1420 // '/P' is in the String.
1421 // Skip "/" and get P in next loop.
1426 // '/P' is not in the String.
1430 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1431 if (*Pointer
== L
'.') {
1433 // D should be followed by '.'
1437 return RETURN_UNSUPPORTED
;
1442 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1443 return RETURN_UNSUPPORTED
;
1446 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
1447 if (PrefixLength
!= NULL
) {
1448 *PrefixLength
= LocalPrefixLength
;
1450 if (EndPointer
!= NULL
) {
1451 *EndPointer
= Pointer
;
1454 return RETURN_SUCCESS
;
1458 Convert a Null-terminated Unicode GUID string to a value of type
1461 This function outputs a GUID value by interpreting the contents of
1462 the Unicode string specified by String. The format of the input
1463 Unicode string String consists of 36 characters, as follows:
1465 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1467 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1468 [A-F], with each pair representing a single byte hexadecimal value.
1470 The mapping between String and the EFI_GUID structure is as follows:
1488 If String is NULL, then ASSERT().
1489 If Guid is NULL, then ASSERT().
1490 If String is not aligned in a 16-bit boundary, then ASSERT().
1492 @param String Pointer to a Null-terminated Unicode string.
1493 @param Guid Pointer to the converted GUID.
1495 @retval RETURN_SUCCESS Guid is translated from String.
1496 @retval RETURN_INVALID_PARAMETER If String is NULL.
1498 @retval RETURN_UNSUPPORTED If String is not as the above format.
1504 IN CONST CHAR16
*String
,
1508 RETURN_STATUS Status
;
1511 ASSERT (((UINTN
) String
& BIT0
) == 0);
1514 // 1. None of String or Guid shall be a null pointer.
1516 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1517 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
1520 // Get aabbccdd in big-endian.
1522 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*) &LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
1523 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data1
)] != L
'-') {
1524 return RETURN_UNSUPPORTED
;
1527 // Convert big-endian to little-endian.
1529 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
1530 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
1533 // Get eeff in big-endian.
1535 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*) &LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
1536 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data2
)] != L
'-') {
1537 return RETURN_UNSUPPORTED
;
1540 // Convert big-endian to little-endian.
1542 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
1543 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
1546 // Get gghh in big-endian.
1548 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*) &LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
1549 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data3
)] != L
'-') {
1550 return RETURN_UNSUPPORTED
;
1553 // Convert big-endian to little-endian.
1555 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
1556 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
1561 Status
= StrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
1562 if (RETURN_ERROR (Status
) || String
[2 * 2] != L
'-') {
1563 return RETURN_UNSUPPORTED
;
1565 String
+= 2 * 2 + 1;
1568 // Get kkllmmnnoopp.
1570 Status
= StrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
1571 if (RETURN_ERROR (Status
)) {
1572 return RETURN_UNSUPPORTED
;
1575 CopyGuid (Guid
, &LocalGuid
);
1576 return RETURN_SUCCESS
;
1580 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1582 This function outputs a byte array by interpreting the contents of
1583 the Unicode string specified by String in hexadecimal format. The format of
1584 the input Unicode string String is:
1588 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1589 The function decodes every two hexadecimal digit characters as one byte. The
1590 decoding stops after Length of characters and outputs Buffer containing
1593 If String is not aligned in a 16-bit boundary, then ASSERT().
1595 If String is NULL, then ASSERT().
1597 If Buffer is NULL, then ASSERT().
1599 If Length is not multiple of 2, then ASSERT().
1601 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1602 PcdMaximumUnicodeStringLength, then ASSERT().
1604 If MaxBufferSize is less than (Length / 2), then ASSERT().
1606 @param String Pointer to a Null-terminated Unicode string.
1607 @param Length The number of Unicode characters to decode.
1608 @param Buffer Pointer to the converted bytes array.
1609 @param MaxBufferSize The maximum size of Buffer.
1611 @retval RETURN_SUCCESS Buffer is translated from String.
1612 @retval RETURN_INVALID_PARAMETER If String is NULL.
1614 If Length is not multiple of 2.
1615 If PcdMaximumUnicodeStringLength is not zero,
1616 and Length is greater than
1617 PcdMaximumUnicodeStringLength.
1618 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1619 a character that is not valid hexadecimal
1620 digit characters, or a Null-terminator.
1621 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1626 IN CONST CHAR16
*String
,
1629 IN UINTN MaxBufferSize
1634 ASSERT (((UINTN
) String
& BIT0
) == 0);
1637 // 1. None of String or Buffer shall be a null pointer.
1639 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1640 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
1643 // 2. Length shall not be greater than RSIZE_MAX.
1645 if (RSIZE_MAX
!= 0) {
1646 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1650 // 3. Length shall not be odd.
1652 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
1655 // 4. MaxBufferSize shall equal to or greater than Length / 2.
1657 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
1660 // 5. String shall not contains invalid hexadecimal digits.
1662 for (Index
= 0; Index
< Length
; Index
++) {
1663 if (!InternalIsHexaDecimalDigitCharacter (String
[Index
])) {
1667 if (Index
!= Length
) {
1668 return RETURN_UNSUPPORTED
;
1672 // Convert the hex string to bytes.
1674 for(Index
= 0; Index
< Length
; Index
++) {
1677 // For even characters, write the upper nibble for each buffer byte,
1678 // and for even characters, the lower nibble.
1680 if ((Index
& BIT0
) == 0) {
1681 Buffer
[Index
/ 2] = (UINT8
) InternalHexCharToUintn (String
[Index
]) << 4;
1683 Buffer
[Index
/ 2] |= (UINT8
) InternalHexCharToUintn (String
[Index
]);
1686 return RETURN_SUCCESS
;
1690 Returns the length of a Null-terminated Ascii string.
1692 This function is similar as strlen_s defined in C11.
1694 @param String A pointer to a Null-terminated Ascii string.
1695 @param MaxSize The maximum number of Destination Ascii
1696 char, including terminating null char.
1698 @retval 0 If String is NULL.
1699 @retval MaxSize If there is no null character in the first MaxSize characters of String.
1700 @return The number of characters that percede the terminating null character.
1706 IN CONST CHAR8
*String
,
1713 // If String is a null pointer or MaxSize is 0, then the AsciiStrnLenS function returns zero.
1715 if ((String
== NULL
) || (MaxSize
== 0)) {
1720 // Otherwise, the AsciiStrnLenS function returns the number of characters that precede the
1721 // terminating null character. If there is no null character in the first MaxSize characters of
1722 // String then AsciiStrnLenS returns MaxSize. At most the first MaxSize characters of String shall
1723 // be accessed by AsciiStrnLenS.
1726 while (String
[Length
] != 0) {
1727 if (Length
>= MaxSize
- 1) {
1736 Returns the size of a Null-terminated Ascii string in bytes, including the
1739 This function returns the size of the Null-terminated Ascii string specified
1740 by String in bytes, including the Null terminator.
1742 @param String A pointer to a Null-terminated Ascii string.
1743 @param MaxSize The maximum number of Destination Ascii
1744 char, including the Null terminator.
1746 @retval 0 If String is NULL.
1747 @retval (sizeof (CHAR8) * (MaxSize + 1))
1748 If there is no Null terminator in the first MaxSize characters of
1750 @return The size of the Null-terminated Ascii string in bytes, including the
1757 IN CONST CHAR8
*String
,
1762 // If String is a null pointer, then the AsciiStrnSizeS function returns
1765 if (String
== NULL
) {
1770 // Otherwise, the AsciiStrnSizeS function returns the size of the
1771 // Null-terminated Ascii string in bytes, including the Null terminator. If
1772 // there is no Null terminator in the first MaxSize characters of String,
1773 // then AsciiStrnSizeS returns (sizeof (CHAR8) * (MaxSize + 1)) to keep a
1774 // consistent map with the AsciiStrnLenS function.
1776 return (AsciiStrnLenS (String
, MaxSize
) + 1) * sizeof (*String
);
1780 Copies the string pointed to by Source (including the terminating null char)
1781 to the array pointed to by Destination.
1783 This function is similar as strcpy_s defined in C11.
1785 If an error would be returned, then the function will also ASSERT().
1787 If an error is returned, then the Destination is unmodified.
1789 @param Destination A pointer to a Null-terminated Ascii string.
1790 @param DestMax The maximum number of Destination Ascii
1791 char, including terminating null char.
1792 @param Source A pointer to a Null-terminated Ascii string.
1794 @retval RETURN_SUCCESS String is copied.
1795 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1796 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1798 If PcdMaximumAsciiStringLength is not zero,
1799 and DestMax is greater than
1800 PcdMaximumAsciiStringLength.
1802 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1807 OUT CHAR8
*Destination
,
1809 IN CONST CHAR8
*Source
1815 // 1. Neither Destination nor Source shall be a null pointer.
1817 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1818 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1821 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
1823 if (ASCII_RSIZE_MAX
!= 0) {
1824 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1828 // 3. DestMax shall not equal zero.
1830 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1833 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1835 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
1836 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1839 // 5. Copying shall not take place between objects that overlap.
1841 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1844 // The AsciiStrCpyS function copies the string pointed to by Source (including the terminating
1845 // null character) into the array pointed to by Destination.
1847 while (*Source
!= 0) {
1848 *(Destination
++) = *(Source
++);
1852 return RETURN_SUCCESS
;
1856 Copies not more than Length successive char from the string pointed to by
1857 Source to the array pointed to by Destination. If no null char is copied from
1858 Source, then Destination[Length] is always set to null.
1860 This function is similar as strncpy_s defined in C11.
1862 If an error would be returned, then the function will also ASSERT().
1864 If an error is returned, then the Destination is unmodified.
1866 @param Destination A pointer to a Null-terminated Ascii string.
1867 @param DestMax The maximum number of Destination Ascii
1868 char, including terminating null char.
1869 @param Source A pointer to a Null-terminated Ascii string.
1870 @param Length The maximum number of Ascii characters to copy.
1872 @retval RETURN_SUCCESS String is copied.
1873 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1874 MIN(StrLen(Source), Length).
1875 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1877 If PcdMaximumAsciiStringLength is not zero,
1878 and DestMax is greater than
1879 PcdMaximumAsciiStringLength.
1881 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1886 OUT CHAR8
*Destination
,
1888 IN CONST CHAR8
*Source
,
1895 // 1. Neither Destination nor Source shall be a null pointer.
1897 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1898 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1901 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX
1903 if (ASCII_RSIZE_MAX
!= 0) {
1904 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1905 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1909 // 3. DestMax shall not equal zero.
1911 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1914 // 4. If Length is not less than DestMax, then DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1916 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
1917 if (Length
>= DestMax
) {
1918 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1922 // 5. Copying shall not take place between objects that overlap.
1924 if (SourceLen
> Length
) {
1927 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1930 // The AsciiStrnCpyS function copies not more than Length successive characters (characters that
1931 // follow a null character are not copied) from the array pointed to by Source to the array
1932 // pointed to by Destination. If no null character was copied from Source, then Destination[Length] is set to a null
1935 while ((*Source
!= 0) && (SourceLen
> 0)) {
1936 *(Destination
++) = *(Source
++);
1941 return RETURN_SUCCESS
;
1945 Appends a copy of the string pointed to by Source (including the terminating
1946 null char) to the end of the string pointed to by Destination.
1948 This function is similar as strcat_s defined in C11.
1950 If an error would be returned, then the function will also ASSERT().
1952 If an error is returned, then the Destination is unmodified.
1954 @param Destination A pointer to a Null-terminated Ascii string.
1955 @param DestMax The maximum number of Destination Ascii
1956 char, including terminating null char.
1957 @param Source A pointer to a Null-terminated Ascii string.
1959 @retval RETURN_SUCCESS String is appended.
1960 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
1961 StrLen(Destination).
1962 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
1963 greater than StrLen(Source).
1964 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1966 If PcdMaximumAsciiStringLength is not zero,
1967 and DestMax is greater than
1968 PcdMaximumAsciiStringLength.
1970 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1975 IN OUT CHAR8
*Destination
,
1977 IN CONST CHAR8
*Source
1985 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrCatS.
1987 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
1988 CopyLen
= DestMax
- DestLen
;
1991 // 1. Neither Destination nor Source shall be a null pointer.
1993 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1994 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1997 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
1999 if (ASCII_RSIZE_MAX
!= 0) {
2000 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2004 // 3. DestMax shall not equal zero.
2006 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2009 // 4. CopyLen shall not equal zero.
2011 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
2014 // 5. CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
2016 SourceLen
= AsciiStrnLenS (Source
, CopyLen
);
2017 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2020 // 6. Copying shall not take place between objects that overlap.
2022 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2025 // The AsciiStrCatS function appends a copy of the string pointed to by Source (including the
2026 // terminating null character) to the end of the string pointed to by Destination. The initial character
2027 // from Source overwrites the null character at the end of Destination.
2029 Destination
= Destination
+ DestLen
;
2030 while (*Source
!= 0) {
2031 *(Destination
++) = *(Source
++);
2035 return RETURN_SUCCESS
;
2039 Appends not more than Length successive char from the string pointed to by
2040 Source to the end of the string pointed to by Destination. If no null char is
2041 copied from Source, then Destination[StrLen(Destination) + Length] is always
2044 This function is similar as strncat_s defined in C11.
2046 If an error would be returned, then the function will also ASSERT().
2048 If an error is returned, then the Destination is unmodified.
2050 @param Destination A pointer to a Null-terminated Ascii string.
2051 @param DestMax The maximum number of Destination Ascii
2052 char, including terminating null char.
2053 @param Source A pointer to a Null-terminated Ascii string.
2054 @param Length The maximum number of Ascii characters to copy.
2056 @retval RETURN_SUCCESS String is appended.
2057 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
2058 StrLen(Destination).
2059 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
2060 greater than MIN(StrLen(Source), Length).
2061 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2063 If PcdMaximumAsciiStringLength is not zero,
2064 and DestMax is greater than
2065 PcdMaximumAsciiStringLength.
2067 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2072 IN OUT CHAR8
*Destination
,
2074 IN CONST CHAR8
*Source
,
2083 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrnCatS.
2085 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
2086 CopyLen
= DestMax
- DestLen
;
2089 // 1. Neither Destination nor Source shall be a null pointer.
2091 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2092 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2095 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX.
2097 if (ASCII_RSIZE_MAX
!= 0) {
2098 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2099 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2103 // 3. DestMax shall not equal zero.
2105 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2108 // 4. CopyLen shall not equal zero.
2110 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
2113 // 5. If Length is not less than CopyLen, then CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
2115 SourceLen
= AsciiStrnLenS (Source
, CopyLen
);
2116 if (Length
>= CopyLen
) {
2117 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2121 // 6. Copying shall not take place between objects that overlap.
2123 if (SourceLen
> Length
) {
2126 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2129 // The AsciiStrnCatS function appends not more than Length successive characters (characters
2130 // that follow a null character are not copied) from the array pointed to by Source to the end of
2131 // the string pointed to by Destination. The initial character from Source overwrites the null character at
2132 // the end of Destination. If no null character was copied from Source, then Destination[DestMax-CopyLen+Length] is set to
2133 // a null character.
2135 Destination
= Destination
+ DestLen
;
2136 while ((*Source
!= 0) && (SourceLen
> 0)) {
2137 *(Destination
++) = *(Source
++);
2142 return RETURN_SUCCESS
;
2146 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
2148 This function outputs a value of type UINTN by interpreting the contents of
2149 the Ascii string specified by String as a decimal number. The format of the
2150 input Ascii string String is:
2152 [spaces] [decimal digits].
2154 The valid decimal digit character is in the range [0-9]. The function will
2155 ignore the pad space, which includes spaces or tab characters, before
2156 [decimal digits]. The running zero in the beginning of [decimal digits] will
2157 be ignored. Then, the function stops at the first character that is a not a
2158 valid decimal character or a Null-terminator, whichever one comes first.
2160 If String is NULL, then ASSERT().
2161 If Data is NULL, then ASSERT().
2162 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2163 PcdMaximumAsciiStringLength Ascii characters, not including the
2164 Null-terminator, then ASSERT().
2166 If String has no valid decimal digits in the above format, then 0 is stored
2167 at the location pointed to by Data.
2168 If the number represented by String exceeds the range defined by UINTN, then
2169 MAX_UINTN is stored at the location pointed to by Data.
2171 If EndPointer is not NULL, a pointer to the character that stopped the scan
2172 is stored at the location pointed to by EndPointer. If String has no valid
2173 decimal digits right after the optional pad spaces, the value of String is
2174 stored at the location pointed to by EndPointer.
2176 @param String Pointer to a Null-terminated Ascii string.
2177 @param EndPointer Pointer to character that stops scan.
2178 @param Data Pointer to the converted value.
2180 @retval RETURN_SUCCESS Value is translated from String.
2181 @retval RETURN_INVALID_PARAMETER If String is NULL.
2183 If PcdMaximumAsciiStringLength is not zero,
2184 and String contains more than
2185 PcdMaximumAsciiStringLength Ascii
2186 characters, not including the
2188 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2189 the range defined by UINTN.
2194 AsciiStrDecimalToUintnS (
2195 IN CONST CHAR8
*String
,
2196 OUT CHAR8
**EndPointer
, OPTIONAL
2201 // 1. Neither String nor Data shall be a null pointer.
2203 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2204 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2207 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2209 if (ASCII_RSIZE_MAX
!= 0) {
2210 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2213 if (EndPointer
!= NULL
) {
2214 *EndPointer
= (CHAR8
*) String
;
2218 // Ignore the pad spaces (space or tab)
2220 while ((*String
== ' ') || (*String
== '\t')) {
2225 // Ignore leading Zeros after the spaces
2227 while (*String
== '0') {
2233 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2235 // If the number represented by String overflows according to the range
2236 // defined by UINTN, then MAX_UINTN is stored in *Data and
2237 // RETURN_UNSUPPORTED is returned.
2239 if (*Data
> ((MAX_UINTN
- (*String
- '0')) / 10)) {
2241 if (EndPointer
!= NULL
) {
2242 *EndPointer
= (CHAR8
*) String
;
2244 return RETURN_UNSUPPORTED
;
2247 *Data
= *Data
* 10 + (*String
- '0');
2251 if (EndPointer
!= NULL
) {
2252 *EndPointer
= (CHAR8
*) String
;
2254 return RETURN_SUCCESS
;
2258 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
2260 This function outputs a value of type UINT64 by interpreting the contents of
2261 the Ascii string specified by String as a decimal number. The format of the
2262 input Ascii string String is:
2264 [spaces] [decimal digits].
2266 The valid decimal digit character is in the range [0-9]. The function will
2267 ignore the pad space, which includes spaces or tab characters, before
2268 [decimal digits]. The running zero in the beginning of [decimal digits] will
2269 be ignored. Then, the function stops at the first character that is a not a
2270 valid decimal character or a Null-terminator, whichever one comes first.
2272 If String is NULL, then ASSERT().
2273 If Data is NULL, then ASSERT().
2274 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2275 PcdMaximumAsciiStringLength Ascii characters, not including the
2276 Null-terminator, then ASSERT().
2278 If String has no valid decimal digits in the above format, then 0 is stored
2279 at the location pointed to by Data.
2280 If the number represented by String exceeds the range defined by UINT64, then
2281 MAX_UINT64 is stored at the location pointed to by Data.
2283 If EndPointer is not NULL, a pointer to the character that stopped the scan
2284 is stored at the location pointed to by EndPointer. If String has no valid
2285 decimal digits right after the optional pad spaces, the value of String is
2286 stored at the location pointed to by EndPointer.
2288 @param String Pointer to a Null-terminated Ascii string.
2289 @param EndPointer Pointer to character that stops scan.
2290 @param Data Pointer to the converted value.
2292 @retval RETURN_SUCCESS Value is translated from String.
2293 @retval RETURN_INVALID_PARAMETER If String is NULL.
2295 If PcdMaximumAsciiStringLength is not zero,
2296 and String contains more than
2297 PcdMaximumAsciiStringLength Ascii
2298 characters, not including the
2300 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2301 the range defined by UINT64.
2306 AsciiStrDecimalToUint64S (
2307 IN CONST CHAR8
*String
,
2308 OUT CHAR8
**EndPointer
, OPTIONAL
2313 // 1. Neither String nor Data shall be a null pointer.
2315 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2316 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2319 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2321 if (ASCII_RSIZE_MAX
!= 0) {
2322 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2325 if (EndPointer
!= NULL
) {
2326 *EndPointer
= (CHAR8
*) String
;
2330 // Ignore the pad spaces (space or tab)
2332 while ((*String
== ' ') || (*String
== '\t')) {
2337 // Ignore leading Zeros after the spaces
2339 while (*String
== '0') {
2345 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2347 // If the number represented by String overflows according to the range
2348 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2349 // RETURN_UNSUPPORTED is returned.
2351 if (*Data
> DivU64x32 (MAX_UINT64
- (*String
- '0'), 10)) {
2353 if (EndPointer
!= NULL
) {
2354 *EndPointer
= (CHAR8
*) String
;
2356 return RETURN_UNSUPPORTED
;
2359 *Data
= MultU64x32 (*Data
, 10) + (*String
- '0');
2363 if (EndPointer
!= NULL
) {
2364 *EndPointer
= (CHAR8
*) String
;
2366 return RETURN_SUCCESS
;
2370 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
2372 This function outputs a value of type UINTN by interpreting the contents of
2373 the Ascii string specified by String as a hexadecimal number. The format of
2374 the input Ascii string String is:
2376 [spaces][zeros][x][hexadecimal digits].
2378 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2379 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2380 "x" appears in the input string, it must be prefixed with at least one 0. The
2381 function will ignore the pad space, which includes spaces or tab characters,
2382 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2383 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2384 the first valid hexadecimal digit. Then, the function stops at the first
2385 character that is a not a valid hexadecimal character or Null-terminator,
2386 whichever on comes first.
2388 If String is NULL, then ASSERT().
2389 If Data is NULL, then ASSERT().
2390 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2391 PcdMaximumAsciiStringLength Ascii characters, not including the
2392 Null-terminator, then ASSERT().
2394 If String has no valid hexadecimal digits in the above format, then 0 is
2395 stored at the location pointed to by Data.
2396 If the number represented by String exceeds the range defined by UINTN, then
2397 MAX_UINTN is stored at the location pointed to by Data.
2399 If EndPointer is not NULL, a pointer to the character that stopped the scan
2400 is stored at the location pointed to by EndPointer. If String has no valid
2401 hexadecimal digits right after the optional pad spaces, the value of String
2402 is stored at the location pointed to by EndPointer.
2404 @param String Pointer to a Null-terminated Ascii string.
2405 @param EndPointer Pointer to character that stops scan.
2406 @param Data Pointer to the converted value.
2408 @retval RETURN_SUCCESS Value is translated from String.
2409 @retval RETURN_INVALID_PARAMETER If String is NULL.
2411 If PcdMaximumAsciiStringLength is not zero,
2412 and String contains more than
2413 PcdMaximumAsciiStringLength Ascii
2414 characters, not including the
2416 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2417 the range defined by UINTN.
2422 AsciiStrHexToUintnS (
2423 IN CONST CHAR8
*String
,
2424 OUT CHAR8
**EndPointer
, OPTIONAL
2429 // 1. Neither String nor Data shall be a null pointer.
2431 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2432 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2435 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2437 if (ASCII_RSIZE_MAX
!= 0) {
2438 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2441 if (EndPointer
!= NULL
) {
2442 *EndPointer
= (CHAR8
*) String
;
2446 // Ignore the pad spaces (space or tab)
2448 while ((*String
== ' ') || (*String
== '\t')) {
2453 // Ignore leading Zeros after the spaces
2455 while (*String
== '0') {
2459 if (InternalBaseLibAsciiToUpper (*String
) == 'X') {
2460 if (*(String
- 1) != '0') {
2462 return RETURN_SUCCESS
;
2472 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2474 // If the number represented by String overflows according to the range
2475 // defined by UINTN, then MAX_UINTN is stored in *Data and
2476 // RETURN_UNSUPPORTED is returned.
2478 if (*Data
> ((MAX_UINTN
- InternalAsciiHexCharToUintn (*String
)) >> 4)) {
2480 if (EndPointer
!= NULL
) {
2481 *EndPointer
= (CHAR8
*) String
;
2483 return RETURN_UNSUPPORTED
;
2486 *Data
= (*Data
<< 4) + InternalAsciiHexCharToUintn (*String
);
2490 if (EndPointer
!= NULL
) {
2491 *EndPointer
= (CHAR8
*) String
;
2493 return RETURN_SUCCESS
;
2497 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
2499 This function outputs a value of type UINT64 by interpreting the contents of
2500 the Ascii string specified by String as a hexadecimal number. The format of
2501 the input Ascii string String is:
2503 [spaces][zeros][x][hexadecimal digits].
2505 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2506 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2507 "x" appears in the input string, it must be prefixed with at least one 0. The
2508 function will ignore the pad space, which includes spaces or tab characters,
2509 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2510 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2511 the first valid hexadecimal digit. Then, the function stops at the first
2512 character that is a not a valid hexadecimal character or Null-terminator,
2513 whichever on comes first.
2515 If String is NULL, then ASSERT().
2516 If Data is NULL, then ASSERT().
2517 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2518 PcdMaximumAsciiStringLength Ascii characters, not including the
2519 Null-terminator, then ASSERT().
2521 If String has no valid hexadecimal digits in the above format, then 0 is
2522 stored at the location pointed to by Data.
2523 If the number represented by String exceeds the range defined by UINT64, then
2524 MAX_UINT64 is stored at the location pointed to by Data.
2526 If EndPointer is not NULL, a pointer to the character that stopped the scan
2527 is stored at the location pointed to by EndPointer. If String has no valid
2528 hexadecimal digits right after the optional pad spaces, the value of String
2529 is stored at the location pointed to by EndPointer.
2531 @param String Pointer to a Null-terminated Ascii string.
2532 @param EndPointer Pointer to character that stops scan.
2533 @param Data Pointer to the converted value.
2535 @retval RETURN_SUCCESS Value is translated from String.
2536 @retval RETURN_INVALID_PARAMETER If String is NULL.
2538 If PcdMaximumAsciiStringLength is not zero,
2539 and String contains more than
2540 PcdMaximumAsciiStringLength Ascii
2541 characters, not including the
2543 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2544 the range defined by UINT64.
2549 AsciiStrHexToUint64S (
2550 IN CONST CHAR8
*String
,
2551 OUT CHAR8
**EndPointer
, OPTIONAL
2556 // 1. Neither String nor Data shall be a null pointer.
2558 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2559 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2562 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2564 if (ASCII_RSIZE_MAX
!= 0) {
2565 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2568 if (EndPointer
!= NULL
) {
2569 *EndPointer
= (CHAR8
*) String
;
2573 // Ignore the pad spaces (space or tab)
2575 while ((*String
== ' ') || (*String
== '\t')) {
2580 // Ignore leading Zeros after the spaces
2582 while (*String
== '0') {
2586 if (InternalBaseLibAsciiToUpper (*String
) == 'X') {
2587 if (*(String
- 1) != '0') {
2589 return RETURN_SUCCESS
;
2599 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2601 // If the number represented by String overflows according to the range
2602 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2603 // RETURN_UNSUPPORTED is returned.
2605 if (*Data
> RShiftU64 (MAX_UINT64
- InternalAsciiHexCharToUintn (*String
), 4)) {
2607 if (EndPointer
!= NULL
) {
2608 *EndPointer
= (CHAR8
*) String
;
2610 return RETURN_UNSUPPORTED
;
2613 *Data
= LShiftU64 (*Data
, 4) + InternalAsciiHexCharToUintn (*String
);
2617 if (EndPointer
!= NULL
) {
2618 *EndPointer
= (CHAR8
*) String
;
2620 return RETURN_SUCCESS
;
2624 Convert a Null-terminated Unicode string to a Null-terminated
2627 This function is similar to AsciiStrCpyS.
2629 This function converts the content of the Unicode string Source
2630 to the ASCII string Destination by copying the lower 8 bits of
2631 each Unicode character. The function terminates the ASCII string
2632 Destination by appending a Null-terminator character at the end.
2634 The caller is responsible to make sure Destination points to a buffer with size
2635 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
2637 If any Unicode characters in Source contain non-zero value in
2638 the upper 8 bits, then ASSERT().
2640 If Source is not aligned on a 16-bit boundary, then ASSERT().
2641 If an error would be returned, then the function will also ASSERT().
2643 If an error is returned, then the Destination is unmodified.
2645 @param Source The pointer to a Null-terminated Unicode string.
2646 @param Destination The pointer to a Null-terminated ASCII string.
2647 @param DestMax The maximum number of Destination Ascii
2648 char, including terminating null char.
2650 @retval RETURN_SUCCESS String is converted.
2651 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2652 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2654 If PcdMaximumAsciiStringLength is not zero,
2655 and DestMax is greater than
2656 PcdMaximumAsciiStringLength.
2657 If PcdMaximumUnicodeStringLength is not zero,
2658 and DestMax is greater than
2659 PcdMaximumUnicodeStringLength.
2661 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2666 UnicodeStrToAsciiStrS (
2667 IN CONST CHAR16
*Source
,
2668 OUT CHAR8
*Destination
,
2674 ASSERT (((UINTN
) Source
& BIT0
) == 0);
2677 // 1. Neither Destination nor Source shall be a null pointer.
2679 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2680 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2683 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX or RSIZE_MAX.
2685 if (ASCII_RSIZE_MAX
!= 0) {
2686 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2688 if (RSIZE_MAX
!= 0) {
2689 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2693 // 3. DestMax shall not equal zero.
2695 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2698 // 4. DestMax shall be greater than StrnLenS (Source, DestMax).
2700 SourceLen
= StrnLenS (Source
, DestMax
);
2701 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2704 // 5. Copying shall not take place between objects that overlap.
2706 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof(CHAR16
)), RETURN_ACCESS_DENIED
);
2711 while (*Source
!= '\0') {
2713 // If any Unicode characters in Source contain
2714 // non-zero value in the upper 8 bits, then ASSERT().
2716 ASSERT (*Source
< 0x100);
2717 *(Destination
++) = (CHAR8
) *(Source
++);
2719 *Destination
= '\0';
2721 return RETURN_SUCCESS
;
2725 Convert not more than Length successive characters from a Null-terminated
2726 Unicode string to a Null-terminated Ascii string. If no null char is copied
2727 from Source, then Destination[Length] is always set to null.
2729 This function converts not more than Length successive characters from the
2730 Unicode string Source to the Ascii string Destination by copying the lower 8
2731 bits of each Unicode character. The function terminates the Ascii string
2732 Destination by appending a Null-terminator character at the end.
2734 The caller is responsible to make sure Destination points to a buffer with
2735 size not smaller than ((MIN(StrLen(Source), Length) + 1) * sizeof (CHAR8))
2738 If any Unicode characters in Source contain non-zero value in the upper 8
2739 bits, then ASSERT().
2740 If Source is not aligned on a 16-bit boundary, then ASSERT().
2741 If an error would be returned, then the function will also ASSERT().
2743 If an error is returned, then Destination and DestinationLength are
2746 @param Source The pointer to a Null-terminated Unicode string.
2747 @param Length The maximum number of Unicode characters to
2749 @param Destination The pointer to a Null-terminated Ascii string.
2750 @param DestMax The maximum number of Destination Ascii char,
2751 including terminating null char.
2752 @param DestinationLength The number of Unicode characters converted.
2754 @retval RETURN_SUCCESS String is converted.
2755 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2757 If DestinationLength is NULL.
2758 If PcdMaximumAsciiStringLength is not zero,
2759 and Length or DestMax is greater than
2760 PcdMaximumAsciiStringLength.
2761 If PcdMaximumUnicodeStringLength is not
2762 zero, and Length or DestMax is greater than
2763 PcdMaximumUnicodeStringLength.
2765 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2766 MIN(StrLen(Source), Length).
2767 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2772 UnicodeStrnToAsciiStrS (
2773 IN CONST CHAR16
*Source
,
2775 OUT CHAR8
*Destination
,
2777 OUT UINTN
*DestinationLength
2782 ASSERT (((UINTN
) Source
& BIT0
) == 0);
2785 // 1. None of Destination, Source or DestinationLength shall be a null
2788 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2789 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2790 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
2793 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
2796 if (ASCII_RSIZE_MAX
!= 0) {
2797 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2798 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2800 if (RSIZE_MAX
!= 0) {
2801 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2802 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2806 // 3. DestMax shall not equal zero.
2808 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2811 // 4. If Length is not less than DestMax, then DestMax shall be greater than
2812 // StrnLenS(Source, DestMax).
2814 SourceLen
= StrnLenS (Source
, DestMax
);
2815 if (Length
>= DestMax
) {
2816 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2820 // 5. Copying shall not take place between objects that overlap.
2822 if (SourceLen
> Length
) {
2825 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof(CHAR16
)), RETURN_ACCESS_DENIED
);
2827 *DestinationLength
= 0;
2832 while ((*Source
!= 0) && (SourceLen
> 0)) {
2834 // If any Unicode characters in Source contain non-zero value in the upper
2835 // 8 bits, then ASSERT().
2837 ASSERT (*Source
< 0x100);
2838 *(Destination
++) = (CHAR8
) *(Source
++);
2840 (*DestinationLength
)++;
2844 return RETURN_SUCCESS
;
2848 Convert one Null-terminated ASCII string to a Null-terminated
2851 This function is similar to StrCpyS.
2853 This function converts the contents of the ASCII string Source to the Unicode
2854 string Destination. The function terminates the Unicode string Destination by
2855 appending a Null-terminator character at the end.
2857 The caller is responsible to make sure Destination points to a buffer with size
2858 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2860 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2861 If an error would be returned, then the function will also ASSERT().
2863 If an error is returned, then the Destination is unmodified.
2865 @param Source The pointer to a Null-terminated ASCII string.
2866 @param Destination The pointer to a Null-terminated Unicode string.
2867 @param DestMax The maximum number of Destination Unicode
2868 char, including terminating null char.
2870 @retval RETURN_SUCCESS String is converted.
2871 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2872 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2874 If PcdMaximumUnicodeStringLength is not zero,
2875 and DestMax is greater than
2876 PcdMaximumUnicodeStringLength.
2877 If PcdMaximumAsciiStringLength is not zero,
2878 and DestMax is greater than
2879 PcdMaximumAsciiStringLength.
2881 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2886 AsciiStrToUnicodeStrS (
2887 IN CONST CHAR8
*Source
,
2888 OUT CHAR16
*Destination
,
2894 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
2897 // 1. Neither Destination nor Source shall be a null pointer.
2899 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2900 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2903 // 2. DestMax shall not be greater than RSIZE_MAX or ASCII_RSIZE_MAX.
2905 if (RSIZE_MAX
!= 0) {
2906 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2908 if (ASCII_RSIZE_MAX
!= 0) {
2909 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2913 // 3. DestMax shall not equal zero.
2915 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2918 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
2920 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
2921 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2924 // 5. Copying shall not take place between objects that overlap.
2926 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof(CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2931 while (*Source
!= '\0') {
2932 *(Destination
++) = (CHAR16
)*(Source
++);
2934 *Destination
= '\0';
2936 return RETURN_SUCCESS
;
2940 Convert not more than Length successive characters from a Null-terminated
2941 Ascii string to a Null-terminated Unicode string. If no null char is copied
2942 from Source, then Destination[Length] is always set to null.
2944 This function converts not more than Length successive characters from the
2945 Ascii string Source to the Unicode string Destination. The function
2946 terminates the Unicode string Destination by appending a Null-terminator
2947 character at the end.
2949 The caller is responsible to make sure Destination points to a buffer with
2950 size not smaller than
2951 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2953 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2954 If an error would be returned, then the function will also ASSERT().
2956 If an error is returned, then Destination and DestinationLength are
2959 @param Source The pointer to a Null-terminated Ascii string.
2960 @param Length The maximum number of Ascii characters to convert.
2961 @param Destination The pointer to a Null-terminated Unicode string.
2962 @param DestMax The maximum number of Destination Unicode char,
2963 including terminating null char.
2964 @param DestinationLength The number of Ascii characters converted.
2966 @retval RETURN_SUCCESS String is converted.
2967 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2969 If DestinationLength is NULL.
2970 If PcdMaximumUnicodeStringLength is not
2971 zero, and Length or DestMax is greater than
2972 PcdMaximumUnicodeStringLength.
2973 If PcdMaximumAsciiStringLength is not zero,
2974 and Length or DestMax is greater than
2975 PcdMaximumAsciiStringLength.
2977 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2978 MIN(AsciiStrLen(Source), Length).
2979 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2984 AsciiStrnToUnicodeStrS (
2985 IN CONST CHAR8
*Source
,
2987 OUT CHAR16
*Destination
,
2989 OUT UINTN
*DestinationLength
2994 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
2997 // 1. None of Destination, Source or DestinationLength shall be a null
3000 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
3001 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
3002 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
3005 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
3008 if (RSIZE_MAX
!= 0) {
3009 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3010 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3012 if (ASCII_RSIZE_MAX
!= 0) {
3013 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3014 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3018 // 3. DestMax shall not equal zero.
3020 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
3023 // 4. If Length is not less than DestMax, then DestMax shall be greater than
3024 // AsciiStrnLenS(Source, DestMax).
3026 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
3027 if (Length
>= DestMax
) {
3028 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
3032 // 5. Copying shall not take place between objects that overlap.
3034 if (SourceLen
> Length
) {
3037 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof(CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
3039 *DestinationLength
= 0;
3044 while ((*Source
!= 0) && (SourceLen
> 0)) {
3045 *(Destination
++) = (CHAR16
)*(Source
++);
3047 (*DestinationLength
)++;
3051 return RETURN_SUCCESS
;
3055 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
3057 This function outputs a value of type IPv6_ADDRESS and may output a value
3058 of type UINT8 by interpreting the contents of the ASCII string specified
3059 by String. The format of the input ASCII string String is as follows:
3063 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
3064 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
3065 memory address and high byte is stored in high memory address. P contains decimal
3066 digit characters in the range [0-9]. The running zero in the beginning of P will
3067 be ignored. /P is optional.
3069 When /P is not in the String, the function stops at the first character that is
3070 not a valid hexadecimal digit character after eight X's are converted.
3072 When /P is in the String, the function stops at the first character that is not
3073 a valid decimal digit character after P is converted.
3075 "::" can be used to compress one or more groups of X when X contains only 0.
3076 The "::" can only appear once in the String.
3078 If String is NULL, then ASSERT().
3080 If Address is NULL, then ASSERT().
3082 If EndPointer is not NULL and Address is translated from String, a pointer
3083 to the character that stopped the scan is stored at the location pointed to
3086 @param String Pointer to a Null-terminated ASCII string.
3087 @param EndPointer Pointer to character that stops scan.
3088 @param Address Pointer to the converted IPv6 address.
3089 @param PrefixLength Pointer to the converted IPv6 address prefix
3090 length. MAX_UINT8 is returned when /P is
3093 @retval RETURN_SUCCESS Address is translated from String.
3094 @retval RETURN_INVALID_PARAMETER If String is NULL.
3096 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
3098 If String contains "::" and number of X
3100 If P starts with character that is not a
3101 valid decimal digit character.
3102 If the decimal number converted from P
3108 AsciiStrToIpv6Address (
3109 IN CONST CHAR8
*String
,
3110 OUT CHAR8
**EndPointer
, OPTIONAL
3111 OUT IPv6_ADDRESS
*Address
,
3112 OUT UINT8
*PrefixLength OPTIONAL
3115 RETURN_STATUS Status
;
3118 IPv6_ADDRESS LocalAddress
;
3119 UINT8 LocalPrefixLength
;
3120 CONST CHAR8
*Pointer
;
3122 UINTN CompressStart
;
3123 BOOLEAN ExpectPrefix
;
3125 LocalPrefixLength
= MAX_UINT8
;
3126 CompressStart
= ARRAY_SIZE (Address
->Addr
);
3127 ExpectPrefix
= FALSE
;
3130 // None of String or Address shall be a null pointer.
3132 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3133 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3135 for (Pointer
= String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3136 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3137 if (*Pointer
!= ':') {
3139 // ":" or "/" should be followed by digit characters.
3141 return RETURN_UNSUPPORTED
;
3145 // Meet second ":" after previous ":" or "/"
3146 // or meet first ":" in the beginning of String.
3150 // ":" shall not be after "/"
3152 return RETURN_UNSUPPORTED
;
3155 if (CompressStart
!= ARRAY_SIZE (Address
->Addr
) || AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3157 // "::" can only appear once.
3158 // "::" can only appear when address is not full length.
3160 return RETURN_UNSUPPORTED
;
3163 // Remember the start of zero compressing.
3165 CompressStart
= AddressIndex
;
3168 if (CompressStart
== 0) {
3169 if (*Pointer
!= ':') {
3171 // Single ":" shall not be in the beginning of String.
3173 return RETURN_UNSUPPORTED
;
3180 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3181 if (*Pointer
== '/') {
3183 // Might be optional "/P" after "::".
3185 if (CompressStart
!= AddressIndex
) {
3186 return RETURN_UNSUPPORTED
;
3192 if (!ExpectPrefix
) {
3196 Status
= AsciiStrHexToUintnS (Pointer
, &End
, &Uintn
);
3197 if (RETURN_ERROR (Status
) || End
- Pointer
> 4) {
3199 // Number of hexadecimal digit characters is no more than 4.
3201 return RETURN_UNSUPPORTED
;
3205 // Uintn won't exceed MAX_UINT16 if number of hexadecimal digit characters is no more than 4.
3207 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) ((UINT16
) Uintn
>> 8);
3208 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
) Uintn
;
3212 // Get P, then exit the loop.
3214 Status
= AsciiStrDecimalToUintnS (Pointer
, &End
, &Uintn
);
3215 if (RETURN_ERROR (Status
) || End
== Pointer
|| Uintn
> 128) {
3217 // Prefix length should not exceed 128.
3219 return RETURN_UNSUPPORTED
;
3221 LocalPrefixLength
= (UINT8
) Uintn
;
3230 if (*Pointer
== '/') {
3231 ExpectPrefix
= TRUE
;
3232 } else if (*Pointer
== ':') {
3233 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3235 // Meet additional ":" after all 8 16-bit address
3241 // Meet other character that is not "/" or ":" after all 8 16-bit address
3248 if ((AddressIndex
== ARRAY_SIZE (Address
->Addr
) && CompressStart
!= ARRAY_SIZE (Address
->Addr
)) ||
3249 (AddressIndex
!= ARRAY_SIZE (Address
->Addr
) && CompressStart
== ARRAY_SIZE (Address
->Addr
))
3252 // Full length of address shall not have compressing zeros.
3253 // Non-full length of address shall have compressing zeros.
3255 return RETURN_UNSUPPORTED
;
3257 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
3258 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
3260 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
3261 &LocalAddress
.Addr
[CompressStart
],
3262 AddressIndex
- CompressStart
3265 if (PrefixLength
!= NULL
) {
3266 *PrefixLength
= LocalPrefixLength
;
3268 if (EndPointer
!= NULL
) {
3269 *EndPointer
= (CHAR8
*) Pointer
;
3272 return RETURN_SUCCESS
;
3276 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
3278 This function outputs a value of type IPv4_ADDRESS and may output a value
3279 of type UINT8 by interpreting the contents of the ASCII string specified
3280 by String. The format of the input ASCII string String is as follows:
3284 D and P are decimal digit characters in the range [0-9]. The running zero in
3285 the beginning of D and P will be ignored. /P is optional.
3287 When /P is not in the String, the function stops at the first character that is
3288 not a valid decimal digit character after four D's are converted.
3290 When /P is in the String, the function stops at the first character that is not
3291 a valid decimal digit character after P is converted.
3293 If String is NULL, then ASSERT().
3295 If Address is NULL, then ASSERT().
3297 If EndPointer is not NULL and Address is translated from String, a pointer
3298 to the character that stopped the scan is stored at the location pointed to
3301 @param String Pointer to a Null-terminated ASCII string.
3302 @param EndPointer Pointer to character that stops scan.
3303 @param Address Pointer to the converted IPv4 address.
3304 @param PrefixLength Pointer to the converted IPv4 address prefix
3305 length. MAX_UINT8 is returned when /P is
3308 @retval RETURN_SUCCESS Address is translated from String.
3309 @retval RETURN_INVALID_PARAMETER If String is NULL.
3311 @retval RETURN_UNSUPPORTED If String is not in the correct format.
3312 If any decimal number converted from D
3314 If the decimal number converted from P
3320 AsciiStrToIpv4Address (
3321 IN CONST CHAR8
*String
,
3322 OUT CHAR8
**EndPointer
, OPTIONAL
3323 OUT IPv4_ADDRESS
*Address
,
3324 OUT UINT8
*PrefixLength OPTIONAL
3327 RETURN_STATUS Status
;
3330 IPv4_ADDRESS LocalAddress
;
3331 UINT8 LocalPrefixLength
;
3334 LocalPrefixLength
= MAX_UINT8
;
3337 // None of String or Address shall be a null pointer.
3339 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3340 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3342 for (Pointer
= (CHAR8
*) String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3343 if (!InternalAsciiIsDecimalDigitCharacter (*Pointer
)) {
3345 // D or P contains invalid characters.
3353 Status
= AsciiStrDecimalToUintnS ((CONST CHAR8
*) Pointer
, &Pointer
, &Uintn
);
3354 if (RETURN_ERROR (Status
)) {
3355 return RETURN_UNSUPPORTED
;
3357 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3362 return RETURN_UNSUPPORTED
;
3364 LocalPrefixLength
= (UINT8
) Uintn
;
3369 if (Uintn
> MAX_UINT8
) {
3370 return RETURN_UNSUPPORTED
;
3372 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) Uintn
;
3377 // Check the '.' or '/', depending on the AddressIndex.
3379 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3380 if (*Pointer
== '/') {
3382 // '/P' is in the String.
3383 // Skip "/" and get P in next loop.
3388 // '/P' is not in the String.
3392 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3393 if (*Pointer
== '.') {
3395 // D should be followed by '.'
3399 return RETURN_UNSUPPORTED
;
3404 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3405 return RETURN_UNSUPPORTED
;
3408 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
3409 if (PrefixLength
!= NULL
) {
3410 *PrefixLength
= LocalPrefixLength
;
3412 if (EndPointer
!= NULL
) {
3413 *EndPointer
= Pointer
;
3416 return RETURN_SUCCESS
;
3420 Convert a Null-terminated ASCII GUID string to a value of type
3423 This function outputs a GUID value by interpreting the contents of
3424 the ASCII string specified by String. The format of the input
3425 ASCII string String consists of 36 characters, as follows:
3427 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
3429 The pairs aa - pp are two characters in the range [0-9], [a-f] and
3430 [A-F], with each pair representing a single byte hexadecimal value.
3432 The mapping between String and the EFI_GUID structure is as follows:
3450 If String is NULL, then ASSERT().
3451 If Guid is NULL, then ASSERT().
3453 @param String Pointer to a Null-terminated ASCII string.
3454 @param Guid Pointer to the converted GUID.
3456 @retval RETURN_SUCCESS Guid is translated from String.
3457 @retval RETURN_INVALID_PARAMETER If String is NULL.
3459 @retval RETURN_UNSUPPORTED If String is not as the above format.
3465 IN CONST CHAR8
*String
,
3469 RETURN_STATUS Status
;
3473 // None of String or Guid shall be a null pointer.
3475 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3476 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
3479 // Get aabbccdd in big-endian.
3481 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*) &LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
3482 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data1
)] != '-') {
3483 return RETURN_UNSUPPORTED
;
3486 // Convert big-endian to little-endian.
3488 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
3489 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
3492 // Get eeff in big-endian.
3494 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*) &LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
3495 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data2
)] != '-') {
3496 return RETURN_UNSUPPORTED
;
3499 // Convert big-endian to little-endian.
3501 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
3502 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
3505 // Get gghh in big-endian.
3507 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*) &LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
3508 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data3
)] != '-') {
3509 return RETURN_UNSUPPORTED
;
3512 // Convert big-endian to little-endian.
3514 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
3515 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
3520 Status
= AsciiStrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
3521 if (RETURN_ERROR (Status
) || String
[2 * 2] != '-') {
3522 return RETURN_UNSUPPORTED
;
3524 String
+= 2 * 2 + 1;
3527 // Get kkllmmnnoopp.
3529 Status
= AsciiStrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
3530 if (RETURN_ERROR (Status
)) {
3531 return RETURN_UNSUPPORTED
;
3534 CopyGuid (Guid
, &LocalGuid
);
3535 return RETURN_SUCCESS
;
3539 Convert a Null-terminated ASCII hexadecimal string to a byte array.
3541 This function outputs a byte array by interpreting the contents of
3542 the ASCII string specified by String in hexadecimal format. The format of
3543 the input ASCII string String is:
3547 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
3548 The function decodes every two hexadecimal digit characters as one byte. The
3549 decoding stops after Length of characters and outputs Buffer containing
3552 If String is NULL, then ASSERT().
3554 If Buffer is NULL, then ASSERT().
3556 If Length is not multiple of 2, then ASSERT().
3558 If PcdMaximumAsciiStringLength is not zero and Length is greater than
3559 PcdMaximumAsciiStringLength, then ASSERT().
3561 If MaxBufferSize is less than (Length / 2), then ASSERT().
3563 @param String Pointer to a Null-terminated ASCII string.
3564 @param Length The number of ASCII characters to decode.
3565 @param Buffer Pointer to the converted bytes array.
3566 @param MaxBufferSize The maximum size of Buffer.
3568 @retval RETURN_SUCCESS Buffer is translated from String.
3569 @retval RETURN_INVALID_PARAMETER If String is NULL.
3571 If Length is not multiple of 2.
3572 If PcdMaximumAsciiStringLength is not zero,
3573 and Length is greater than
3574 PcdMaximumAsciiStringLength.
3575 @retval RETURN_UNSUPPORTED If Length of characters from String contain
3576 a character that is not valid hexadecimal
3577 digit characters, or a Null-terminator.
3578 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
3582 AsciiStrHexToBytes (
3583 IN CONST CHAR8
*String
,
3586 IN UINTN MaxBufferSize
3592 // 1. None of String or Buffer shall be a null pointer.
3594 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3595 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
3598 // 2. Length shall not be greater than ASCII_RSIZE_MAX.
3600 if (ASCII_RSIZE_MAX
!= 0) {
3601 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3605 // 3. Length shall not be odd.
3607 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
3610 // 4. MaxBufferSize shall equal to or greater than Length / 2.
3612 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
3615 // 5. String shall not contains invalid hexadecimal digits.
3617 for (Index
= 0; Index
< Length
; Index
++) {
3618 if (!InternalAsciiIsHexaDecimalDigitCharacter (String
[Index
])) {
3622 if (Index
!= Length
) {
3623 return RETURN_UNSUPPORTED
;
3627 // Convert the hex string to bytes.
3629 for(Index
= 0; Index
< Length
; Index
++) {
3632 // For even characters, write the upper nibble for each buffer byte,
3633 // and for even characters, the lower nibble.
3635 if ((Index
& BIT0
) == 0) {
3636 Buffer
[Index
/ 2] = (UINT8
) InternalAsciiHexCharToUintn (String
[Index
]) << 4;
3638 Buffer
[Index
/ 2] |= (UINT8
) InternalAsciiHexCharToUintn (String
[Index
]);
3641 return RETURN_SUCCESS
;