4 Copyright (c) 2014 - 2018, 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
, MIN (DestMax
, Length
));
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 ((SourceLen
> 0) && (*Source
!= 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
, MIN (CopyLen
, Length
));
555 if (Length
>= CopyLen
) {
556 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
560 // 6. Copying shall not take place between objects that overlap.
562 if (SourceLen
> Length
) {
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 ((SourceLen
> 0) && (*Source
!= 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 ASSERT (AddressIndex
+ 1 < ARRAY_SIZE (Address
->Addr
));
1238 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) ((UINT16
) Uintn
>> 8);
1239 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
) Uintn
;
1243 // Get P, then exit the loop.
1245 Status
= StrDecimalToUintnS (Pointer
, &End
, &Uintn
);
1246 if (RETURN_ERROR (Status
) || End
== Pointer
|| Uintn
> 128) {
1248 // Prefix length should not exceed 128.
1250 return RETURN_UNSUPPORTED
;
1252 LocalPrefixLength
= (UINT8
) Uintn
;
1261 if (*Pointer
== L
'/') {
1262 ExpectPrefix
= TRUE
;
1263 } else if (*Pointer
== L
':') {
1264 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1266 // Meet additional ":" after all 8 16-bit address
1272 // Meet other character that is not "/" or ":" after all 8 16-bit address
1279 if ((AddressIndex
== ARRAY_SIZE (Address
->Addr
) && CompressStart
!= ARRAY_SIZE (Address
->Addr
)) ||
1280 (AddressIndex
!= ARRAY_SIZE (Address
->Addr
) && CompressStart
== ARRAY_SIZE (Address
->Addr
))
1283 // Full length of address shall not have compressing zeros.
1284 // Non-full length of address shall have compressing zeros.
1286 return RETURN_UNSUPPORTED
;
1288 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
1289 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
1290 if (AddressIndex
> CompressStart
) {
1292 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
1293 &LocalAddress
.Addr
[CompressStart
],
1294 AddressIndex
- CompressStart
1298 if (PrefixLength
!= NULL
) {
1299 *PrefixLength
= LocalPrefixLength
;
1301 if (EndPointer
!= NULL
) {
1302 *EndPointer
= (CHAR16
*) Pointer
;
1305 return RETURN_SUCCESS
;
1309 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1311 This function outputs a value of type IPv4_ADDRESS and may output a value
1312 of type UINT8 by interpreting the contents of the Unicode string specified
1313 by String. The format of the input Unicode string String is as follows:
1317 D and P are decimal digit characters in the range [0-9]. The running zero in
1318 the beginning of D and P will be ignored. /P is optional.
1320 When /P is not in the String, the function stops at the first character that is
1321 not a valid decimal digit character after four D's are converted.
1323 When /P is in the String, the function stops at the first character that is not
1324 a valid decimal digit character after P is converted.
1326 If String is NULL, then ASSERT().
1328 If Address is NULL, then ASSERT().
1330 If String is not aligned in a 16-bit boundary, then ASSERT().
1332 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1333 PcdMaximumUnicodeStringLength Unicode characters, not including the
1334 Null-terminator, then ASSERT().
1336 If EndPointer is not NULL and Address is translated from String, a pointer
1337 to the character that stopped the scan is stored at the location pointed to
1340 @param String Pointer to a Null-terminated Unicode string.
1341 @param EndPointer Pointer to character that stops scan.
1342 @param Address Pointer to the converted IPv4 address.
1343 @param PrefixLength Pointer to the converted IPv4 address prefix
1344 length. MAX_UINT8 is returned when /P is
1347 @retval RETURN_SUCCESS Address is translated from String.
1348 @retval RETURN_INVALID_PARAMETER If String is NULL.
1350 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1351 If any decimal number converted from D
1353 If the decimal number converted from P
1360 IN CONST CHAR16
*String
,
1361 OUT CHAR16
**EndPointer
, OPTIONAL
1362 OUT IPv4_ADDRESS
*Address
,
1363 OUT UINT8
*PrefixLength OPTIONAL
1366 RETURN_STATUS Status
;
1369 IPv4_ADDRESS LocalAddress
;
1370 UINT8 LocalPrefixLength
;
1373 LocalPrefixLength
= MAX_UINT8
;
1375 ASSERT (((UINTN
) String
& BIT0
) == 0);
1378 // 1. None of String or Guid shall be a null pointer.
1380 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1381 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
1383 for (Pointer
= (CHAR16
*) String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
1384 if (!InternalIsDecimalDigitCharacter (*Pointer
)) {
1386 // D or P contains invalid characters.
1394 Status
= StrDecimalToUintnS ((CONST CHAR16
*) Pointer
, &Pointer
, &Uintn
);
1395 if (RETURN_ERROR (Status
)) {
1396 return RETURN_UNSUPPORTED
;
1398 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1403 return RETURN_UNSUPPORTED
;
1405 LocalPrefixLength
= (UINT8
) Uintn
;
1410 if (Uintn
> MAX_UINT8
) {
1411 return RETURN_UNSUPPORTED
;
1413 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) Uintn
;
1418 // Check the '.' or '/', depending on the AddressIndex.
1420 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
1421 if (*Pointer
== L
'/') {
1423 // '/P' is in the String.
1424 // Skip "/" and get P in next loop.
1429 // '/P' is not in the String.
1433 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1434 if (*Pointer
== L
'.') {
1436 // D should be followed by '.'
1440 return RETURN_UNSUPPORTED
;
1445 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
1446 return RETURN_UNSUPPORTED
;
1449 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
1450 if (PrefixLength
!= NULL
) {
1451 *PrefixLength
= LocalPrefixLength
;
1453 if (EndPointer
!= NULL
) {
1454 *EndPointer
= Pointer
;
1457 return RETURN_SUCCESS
;
1461 Convert a Null-terminated Unicode GUID string to a value of type
1464 This function outputs a GUID value by interpreting the contents of
1465 the Unicode string specified by String. The format of the input
1466 Unicode string String consists of 36 characters, as follows:
1468 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1470 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1471 [A-F], with each pair representing a single byte hexadecimal value.
1473 The mapping between String and the EFI_GUID structure is as follows:
1491 If String is NULL, then ASSERT().
1492 If Guid is NULL, then ASSERT().
1493 If String is not aligned in a 16-bit boundary, then ASSERT().
1495 @param String Pointer to a Null-terminated Unicode string.
1496 @param Guid Pointer to the converted GUID.
1498 @retval RETURN_SUCCESS Guid is translated from String.
1499 @retval RETURN_INVALID_PARAMETER If String is NULL.
1501 @retval RETURN_UNSUPPORTED If String is not as the above format.
1507 IN CONST CHAR16
*String
,
1511 RETURN_STATUS Status
;
1514 ASSERT (((UINTN
) String
& BIT0
) == 0);
1517 // 1. None of String or Guid shall be a null pointer.
1519 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1520 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
1523 // Get aabbccdd in big-endian.
1525 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*) &LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
1526 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data1
)] != L
'-') {
1527 return RETURN_UNSUPPORTED
;
1530 // Convert big-endian to little-endian.
1532 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
1533 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
1536 // Get eeff in big-endian.
1538 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*) &LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
1539 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data2
)] != L
'-') {
1540 return RETURN_UNSUPPORTED
;
1543 // Convert big-endian to little-endian.
1545 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
1546 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
1549 // Get gghh in big-endian.
1551 Status
= StrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*) &LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
1552 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data3
)] != L
'-') {
1553 return RETURN_UNSUPPORTED
;
1556 // Convert big-endian to little-endian.
1558 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
1559 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
1564 Status
= StrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
1565 if (RETURN_ERROR (Status
) || String
[2 * 2] != L
'-') {
1566 return RETURN_UNSUPPORTED
;
1568 String
+= 2 * 2 + 1;
1571 // Get kkllmmnnoopp.
1573 Status
= StrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
1574 if (RETURN_ERROR (Status
)) {
1575 return RETURN_UNSUPPORTED
;
1578 CopyGuid (Guid
, &LocalGuid
);
1579 return RETURN_SUCCESS
;
1583 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1585 This function outputs a byte array by interpreting the contents of
1586 the Unicode string specified by String in hexadecimal format. The format of
1587 the input Unicode string String is:
1591 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1592 The function decodes every two hexadecimal digit characters as one byte. The
1593 decoding stops after Length of characters and outputs Buffer containing
1596 If String is not aligned in a 16-bit boundary, then ASSERT().
1598 If String is NULL, then ASSERT().
1600 If Buffer is NULL, then ASSERT().
1602 If Length is not multiple of 2, then ASSERT().
1604 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1605 PcdMaximumUnicodeStringLength, then ASSERT().
1607 If MaxBufferSize is less than (Length / 2), then ASSERT().
1609 @param String Pointer to a Null-terminated Unicode string.
1610 @param Length The number of Unicode characters to decode.
1611 @param Buffer Pointer to the converted bytes array.
1612 @param MaxBufferSize The maximum size of Buffer.
1614 @retval RETURN_SUCCESS Buffer is translated from String.
1615 @retval RETURN_INVALID_PARAMETER If String is NULL.
1617 If Length is not multiple of 2.
1618 If PcdMaximumUnicodeStringLength is not zero,
1619 and Length is greater than
1620 PcdMaximumUnicodeStringLength.
1621 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1622 a character that is not valid hexadecimal
1623 digit characters, or a Null-terminator.
1624 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1629 IN CONST CHAR16
*String
,
1632 IN UINTN MaxBufferSize
1637 ASSERT (((UINTN
) String
& BIT0
) == 0);
1640 // 1. None of String or Buffer shall be a null pointer.
1642 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
1643 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
1646 // 2. Length shall not be greater than RSIZE_MAX.
1648 if (RSIZE_MAX
!= 0) {
1649 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1653 // 3. Length shall not be odd.
1655 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
1658 // 4. MaxBufferSize shall equal to or greater than Length / 2.
1660 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
1663 // 5. String shall not contains invalid hexadecimal digits.
1665 for (Index
= 0; Index
< Length
; Index
++) {
1666 if (!InternalIsHexaDecimalDigitCharacter (String
[Index
])) {
1670 if (Index
!= Length
) {
1671 return RETURN_UNSUPPORTED
;
1675 // Convert the hex string to bytes.
1677 for(Index
= 0; Index
< Length
; Index
++) {
1680 // For even characters, write the upper nibble for each buffer byte,
1681 // and for even characters, the lower nibble.
1683 if ((Index
& BIT0
) == 0) {
1684 Buffer
[Index
/ 2] = (UINT8
) InternalHexCharToUintn (String
[Index
]) << 4;
1686 Buffer
[Index
/ 2] |= (UINT8
) InternalHexCharToUintn (String
[Index
]);
1689 return RETURN_SUCCESS
;
1693 Returns the length of a Null-terminated Ascii string.
1695 This function is similar as strlen_s defined in C11.
1697 @param String A pointer to a Null-terminated Ascii string.
1698 @param MaxSize The maximum number of Destination Ascii
1699 char, including terminating null char.
1701 @retval 0 If String is NULL.
1702 @retval MaxSize If there is no null character in the first MaxSize characters of String.
1703 @return The number of characters that percede the terminating null character.
1709 IN CONST CHAR8
*String
,
1716 // If String is a null pointer or MaxSize is 0, then the AsciiStrnLenS function returns zero.
1718 if ((String
== NULL
) || (MaxSize
== 0)) {
1723 // Otherwise, the AsciiStrnLenS function returns the number of characters that precede the
1724 // terminating null character. If there is no null character in the first MaxSize characters of
1725 // String then AsciiStrnLenS returns MaxSize. At most the first MaxSize characters of String shall
1726 // be accessed by AsciiStrnLenS.
1729 while (String
[Length
] != 0) {
1730 if (Length
>= MaxSize
- 1) {
1739 Returns the size of a Null-terminated Ascii string in bytes, including the
1742 This function returns the size of the Null-terminated Ascii string specified
1743 by String in bytes, including the Null terminator.
1745 @param String A pointer to a Null-terminated Ascii string.
1746 @param MaxSize The maximum number of Destination Ascii
1747 char, including the Null terminator.
1749 @retval 0 If String is NULL.
1750 @retval (sizeof (CHAR8) * (MaxSize + 1))
1751 If there is no Null terminator in the first MaxSize characters of
1753 @return The size of the Null-terminated Ascii string in bytes, including the
1760 IN CONST CHAR8
*String
,
1765 // If String is a null pointer, then the AsciiStrnSizeS function returns
1768 if (String
== NULL
) {
1773 // Otherwise, the AsciiStrnSizeS function returns the size of the
1774 // Null-terminated Ascii string in bytes, including the Null terminator. If
1775 // there is no Null terminator in the first MaxSize characters of String,
1776 // then AsciiStrnSizeS returns (sizeof (CHAR8) * (MaxSize + 1)) to keep a
1777 // consistent map with the AsciiStrnLenS function.
1779 return (AsciiStrnLenS (String
, MaxSize
) + 1) * sizeof (*String
);
1783 Copies the string pointed to by Source (including the terminating null char)
1784 to the array pointed to by Destination.
1786 This function is similar as strcpy_s defined in C11.
1788 If an error would be returned, then the function will also ASSERT().
1790 If an error is returned, then the Destination is unmodified.
1792 @param Destination A pointer to a Null-terminated Ascii string.
1793 @param DestMax The maximum number of Destination Ascii
1794 char, including terminating null char.
1795 @param Source A pointer to a Null-terminated Ascii string.
1797 @retval RETURN_SUCCESS String is copied.
1798 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1799 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1801 If PcdMaximumAsciiStringLength is not zero,
1802 and DestMax is greater than
1803 PcdMaximumAsciiStringLength.
1805 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1810 OUT CHAR8
*Destination
,
1812 IN CONST CHAR8
*Source
1818 // 1. Neither Destination nor Source shall be a null pointer.
1820 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1821 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1824 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
1826 if (ASCII_RSIZE_MAX
!= 0) {
1827 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1831 // 3. DestMax shall not equal zero.
1833 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1836 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1838 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
1839 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1842 // 5. Copying shall not take place between objects that overlap.
1844 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1847 // The AsciiStrCpyS function copies the string pointed to by Source (including the terminating
1848 // null character) into the array pointed to by Destination.
1850 while (*Source
!= 0) {
1851 *(Destination
++) = *(Source
++);
1855 return RETURN_SUCCESS
;
1859 Copies not more than Length successive char from the string pointed to by
1860 Source to the array pointed to by Destination. If no null char is copied from
1861 Source, then Destination[Length] is always set to null.
1863 This function is similar as strncpy_s defined in C11.
1865 If an error would be returned, then the function will also ASSERT().
1867 If an error is returned, then the Destination is unmodified.
1869 @param Destination A pointer to a Null-terminated Ascii string.
1870 @param DestMax The maximum number of Destination Ascii
1871 char, including terminating null char.
1872 @param Source A pointer to a Null-terminated Ascii string.
1873 @param Length The maximum number of Ascii characters to copy.
1875 @retval RETURN_SUCCESS String is copied.
1876 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1877 MIN(StrLen(Source), Length).
1878 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1880 If PcdMaximumAsciiStringLength is not zero,
1881 and DestMax is greater than
1882 PcdMaximumAsciiStringLength.
1884 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1889 OUT CHAR8
*Destination
,
1891 IN CONST CHAR8
*Source
,
1898 // 1. Neither Destination nor Source shall be a null pointer.
1900 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1901 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
1904 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX
1906 if (ASCII_RSIZE_MAX
!= 0) {
1907 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1908 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
1912 // 3. DestMax shall not equal zero.
1914 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
1917 // 4. If Length is not less than DestMax, then DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
1919 SourceLen
= AsciiStrnLenS (Source
, MIN (DestMax
, Length
));
1920 if (Length
>= DestMax
) {
1921 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
1925 // 5. Copying shall not take place between objects that overlap.
1927 if (SourceLen
> Length
) {
1930 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
1933 // The AsciiStrnCpyS function copies not more than Length successive characters (characters that
1934 // follow a null character are not copied) from the array pointed to by Source to the array
1935 // pointed to by Destination. If no null character was copied from Source, then Destination[Length] is set to a null
1938 while ((SourceLen
> 0) && (*Source
!= 0)) {
1939 *(Destination
++) = *(Source
++);
1944 return RETURN_SUCCESS
;
1948 Appends a copy of the string pointed to by Source (including the terminating
1949 null char) to the end of the string pointed to by Destination.
1951 This function is similar as strcat_s defined in C11.
1953 If an error would be returned, then the function will also ASSERT().
1955 If an error is returned, then the Destination is unmodified.
1957 @param Destination A pointer to a Null-terminated Ascii string.
1958 @param DestMax The maximum number of Destination Ascii
1959 char, including terminating null char.
1960 @param Source A pointer to a Null-terminated Ascii string.
1962 @retval RETURN_SUCCESS String is appended.
1963 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
1964 StrLen(Destination).
1965 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
1966 greater than StrLen(Source).
1967 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1969 If PcdMaximumAsciiStringLength is not zero,
1970 and DestMax is greater than
1971 PcdMaximumAsciiStringLength.
1973 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1978 IN OUT CHAR8
*Destination
,
1980 IN CONST CHAR8
*Source
1988 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrCatS.
1990 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
1991 CopyLen
= DestMax
- DestLen
;
1994 // 1. Neither Destination nor Source shall be a null pointer.
1996 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
1997 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2000 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX.
2002 if (ASCII_RSIZE_MAX
!= 0) {
2003 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2007 // 3. DestMax shall not equal zero.
2009 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2012 // 4. CopyLen shall not equal zero.
2014 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
2017 // 5. CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
2019 SourceLen
= AsciiStrnLenS (Source
, CopyLen
);
2020 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2023 // 6. Copying shall not take place between objects that overlap.
2025 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2028 // The AsciiStrCatS function appends a copy of the string pointed to by Source (including the
2029 // terminating null character) to the end of the string pointed to by Destination. The initial character
2030 // from Source overwrites the null character at the end of Destination.
2032 Destination
= Destination
+ DestLen
;
2033 while (*Source
!= 0) {
2034 *(Destination
++) = *(Source
++);
2038 return RETURN_SUCCESS
;
2042 Appends not more than Length successive char from the string pointed to by
2043 Source to the end of the string pointed to by Destination. If no null char is
2044 copied from Source, then Destination[StrLen(Destination) + Length] is always
2047 This function is similar as strncat_s defined in C11.
2049 If an error would be returned, then the function will also ASSERT().
2051 If an error is returned, then the Destination is unmodified.
2053 @param Destination A pointer to a Null-terminated Ascii string.
2054 @param DestMax The maximum number of Destination Ascii
2055 char, including terminating null char.
2056 @param Source A pointer to a Null-terminated Ascii string.
2057 @param Length The maximum number of Ascii characters to copy.
2059 @retval RETURN_SUCCESS String is appended.
2060 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
2061 StrLen(Destination).
2062 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
2063 greater than MIN(StrLen(Source), Length).
2064 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2066 If PcdMaximumAsciiStringLength is not zero,
2067 and DestMax is greater than
2068 PcdMaximumAsciiStringLength.
2070 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2075 IN OUT CHAR8
*Destination
,
2077 IN CONST CHAR8
*Source
,
2086 // Let CopyLen denote the value DestMax - AsciiStrnLenS(Destination, DestMax) upon entry to AsciiStrnCatS.
2088 DestLen
= AsciiStrnLenS (Destination
, DestMax
);
2089 CopyLen
= DestMax
- DestLen
;
2092 // 1. Neither Destination nor Source shall be a null pointer.
2094 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2095 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2098 // 2. Neither DestMax nor Length shall be greater than ASCII_RSIZE_MAX.
2100 if (ASCII_RSIZE_MAX
!= 0) {
2101 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2102 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2106 // 3. DestMax shall not equal zero.
2108 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2111 // 4. CopyLen shall not equal zero.
2113 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
!= 0), RETURN_BAD_BUFFER_SIZE
);
2116 // 5. If Length is not less than CopyLen, then CopyLen shall be greater than AsciiStrnLenS(Source, CopyLen).
2118 SourceLen
= AsciiStrnLenS (Source
, MIN (CopyLen
, Length
));
2119 if (Length
>= CopyLen
) {
2120 SAFE_STRING_CONSTRAINT_CHECK ((CopyLen
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2124 // 6. Copying shall not take place between objects that overlap.
2126 if (SourceLen
> Length
) {
2129 SAFE_STRING_CONSTRAINT_CHECK (InternalSafeStringNoAsciiStrOverlap (Destination
, DestMax
, (CHAR8
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2132 // The AsciiStrnCatS function appends not more than Length successive characters (characters
2133 // that follow a null character are not copied) from the array pointed to by Source to the end of
2134 // the string pointed to by Destination. The initial character from Source overwrites the null character at
2135 // the end of Destination. If no null character was copied from Source, then Destination[DestMax-CopyLen+Length] is set to
2136 // a null character.
2138 Destination
= Destination
+ DestLen
;
2139 while ((SourceLen
> 0) && (*Source
!= 0)) {
2140 *(Destination
++) = *(Source
++);
2145 return RETURN_SUCCESS
;
2149 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
2151 This function outputs a value of type UINTN by interpreting the contents of
2152 the Ascii string specified by String as a decimal number. The format of the
2153 input Ascii string String is:
2155 [spaces] [decimal digits].
2157 The valid decimal digit character is in the range [0-9]. The function will
2158 ignore the pad space, which includes spaces or tab characters, before
2159 [decimal digits]. The running zero in the beginning of [decimal digits] will
2160 be ignored. Then, the function stops at the first character that is a not a
2161 valid decimal character or a Null-terminator, whichever one comes first.
2163 If String is NULL, then ASSERT().
2164 If Data is NULL, then ASSERT().
2165 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2166 PcdMaximumAsciiStringLength Ascii characters, not including the
2167 Null-terminator, then ASSERT().
2169 If String has no valid decimal digits in the above format, then 0 is stored
2170 at the location pointed to by Data.
2171 If the number represented by String exceeds the range defined by UINTN, then
2172 MAX_UINTN is stored at the location pointed to by Data.
2174 If EndPointer is not NULL, a pointer to the character that stopped the scan
2175 is stored at the location pointed to by EndPointer. If String has no valid
2176 decimal digits right after the optional pad spaces, the value of String is
2177 stored at the location pointed to by EndPointer.
2179 @param String Pointer to a Null-terminated Ascii string.
2180 @param EndPointer Pointer to character that stops scan.
2181 @param Data Pointer to the converted value.
2183 @retval RETURN_SUCCESS Value is translated from String.
2184 @retval RETURN_INVALID_PARAMETER If String is NULL.
2186 If PcdMaximumAsciiStringLength is not zero,
2187 and String contains more than
2188 PcdMaximumAsciiStringLength Ascii
2189 characters, not including the
2191 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2192 the range defined by UINTN.
2197 AsciiStrDecimalToUintnS (
2198 IN CONST CHAR8
*String
,
2199 OUT CHAR8
**EndPointer
, OPTIONAL
2204 // 1. Neither String nor Data shall be a null pointer.
2206 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2207 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2210 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2212 if (ASCII_RSIZE_MAX
!= 0) {
2213 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2216 if (EndPointer
!= NULL
) {
2217 *EndPointer
= (CHAR8
*) String
;
2221 // Ignore the pad spaces (space or tab)
2223 while ((*String
== ' ') || (*String
== '\t')) {
2228 // Ignore leading Zeros after the spaces
2230 while (*String
== '0') {
2236 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2238 // If the number represented by String overflows according to the range
2239 // defined by UINTN, then MAX_UINTN is stored in *Data and
2240 // RETURN_UNSUPPORTED is returned.
2242 if (*Data
> ((MAX_UINTN
- (*String
- '0')) / 10)) {
2244 if (EndPointer
!= NULL
) {
2245 *EndPointer
= (CHAR8
*) String
;
2247 return RETURN_UNSUPPORTED
;
2250 *Data
= *Data
* 10 + (*String
- '0');
2254 if (EndPointer
!= NULL
) {
2255 *EndPointer
= (CHAR8
*) String
;
2257 return RETURN_SUCCESS
;
2261 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
2263 This function outputs a value of type UINT64 by interpreting the contents of
2264 the Ascii string specified by String as a decimal number. The format of the
2265 input Ascii string String is:
2267 [spaces] [decimal digits].
2269 The valid decimal digit character is in the range [0-9]. The function will
2270 ignore the pad space, which includes spaces or tab characters, before
2271 [decimal digits]. The running zero in the beginning of [decimal digits] will
2272 be ignored. Then, the function stops at the first character that is a not a
2273 valid decimal character or a Null-terminator, whichever one comes first.
2275 If String is NULL, then ASSERT().
2276 If Data is NULL, then ASSERT().
2277 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2278 PcdMaximumAsciiStringLength Ascii characters, not including the
2279 Null-terminator, then ASSERT().
2281 If String has no valid decimal digits in the above format, then 0 is stored
2282 at the location pointed to by Data.
2283 If the number represented by String exceeds the range defined by UINT64, then
2284 MAX_UINT64 is stored at the location pointed to by Data.
2286 If EndPointer is not NULL, a pointer to the character that stopped the scan
2287 is stored at the location pointed to by EndPointer. If String has no valid
2288 decimal digits right after the optional pad spaces, the value of String is
2289 stored at the location pointed to by EndPointer.
2291 @param String Pointer to a Null-terminated Ascii string.
2292 @param EndPointer Pointer to character that stops scan.
2293 @param Data Pointer to the converted value.
2295 @retval RETURN_SUCCESS Value is translated from String.
2296 @retval RETURN_INVALID_PARAMETER If String is NULL.
2298 If PcdMaximumAsciiStringLength is not zero,
2299 and String contains more than
2300 PcdMaximumAsciiStringLength Ascii
2301 characters, not including the
2303 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2304 the range defined by UINT64.
2309 AsciiStrDecimalToUint64S (
2310 IN CONST CHAR8
*String
,
2311 OUT CHAR8
**EndPointer
, OPTIONAL
2316 // 1. Neither String nor Data shall be a null pointer.
2318 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2319 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2322 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2324 if (ASCII_RSIZE_MAX
!= 0) {
2325 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2328 if (EndPointer
!= NULL
) {
2329 *EndPointer
= (CHAR8
*) String
;
2333 // Ignore the pad spaces (space or tab)
2335 while ((*String
== ' ') || (*String
== '\t')) {
2340 // Ignore leading Zeros after the spaces
2342 while (*String
== '0') {
2348 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
2350 // If the number represented by String overflows according to the range
2351 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2352 // RETURN_UNSUPPORTED is returned.
2354 if (*Data
> DivU64x32 (MAX_UINT64
- (*String
- '0'), 10)) {
2356 if (EndPointer
!= NULL
) {
2357 *EndPointer
= (CHAR8
*) String
;
2359 return RETURN_UNSUPPORTED
;
2362 *Data
= MultU64x32 (*Data
, 10) + (*String
- '0');
2366 if (EndPointer
!= NULL
) {
2367 *EndPointer
= (CHAR8
*) String
;
2369 return RETURN_SUCCESS
;
2373 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
2375 This function outputs a value of type UINTN by interpreting the contents of
2376 the Ascii string specified by String as a hexadecimal number. The format of
2377 the input Ascii string String is:
2379 [spaces][zeros][x][hexadecimal digits].
2381 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2382 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2383 "x" appears in the input string, it must be prefixed with at least one 0. The
2384 function will ignore the pad space, which includes spaces or tab characters,
2385 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2386 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2387 the first valid hexadecimal digit. Then, the function stops at the first
2388 character that is a not a valid hexadecimal character or Null-terminator,
2389 whichever on comes first.
2391 If String is NULL, then ASSERT().
2392 If Data is NULL, then ASSERT().
2393 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2394 PcdMaximumAsciiStringLength Ascii characters, not including the
2395 Null-terminator, then ASSERT().
2397 If String has no valid hexadecimal digits in the above format, then 0 is
2398 stored at the location pointed to by Data.
2399 If the number represented by String exceeds the range defined by UINTN, then
2400 MAX_UINTN is stored at the location pointed to by Data.
2402 If EndPointer is not NULL, a pointer to the character that stopped the scan
2403 is stored at the location pointed to by EndPointer. If String has no valid
2404 hexadecimal digits right after the optional pad spaces, the value of String
2405 is stored at the location pointed to by EndPointer.
2407 @param String Pointer to a Null-terminated Ascii string.
2408 @param EndPointer Pointer to character that stops scan.
2409 @param Data Pointer to the converted value.
2411 @retval RETURN_SUCCESS Value is translated from String.
2412 @retval RETURN_INVALID_PARAMETER If String is NULL.
2414 If PcdMaximumAsciiStringLength is not zero,
2415 and String contains more than
2416 PcdMaximumAsciiStringLength Ascii
2417 characters, not including the
2419 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2420 the range defined by UINTN.
2425 AsciiStrHexToUintnS (
2426 IN CONST CHAR8
*String
,
2427 OUT CHAR8
**EndPointer
, OPTIONAL
2432 // 1. Neither String nor Data shall be a null pointer.
2434 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2435 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2438 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2440 if (ASCII_RSIZE_MAX
!= 0) {
2441 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2444 if (EndPointer
!= NULL
) {
2445 *EndPointer
= (CHAR8
*) String
;
2449 // Ignore the pad spaces (space or tab)
2451 while ((*String
== ' ') || (*String
== '\t')) {
2456 // Ignore leading Zeros after the spaces
2458 while (*String
== '0') {
2462 if (InternalBaseLibAsciiToUpper (*String
) == 'X') {
2463 if (*(String
- 1) != '0') {
2465 return RETURN_SUCCESS
;
2475 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2477 // If the number represented by String overflows according to the range
2478 // defined by UINTN, then MAX_UINTN is stored in *Data and
2479 // RETURN_UNSUPPORTED is returned.
2481 if (*Data
> ((MAX_UINTN
- InternalAsciiHexCharToUintn (*String
)) >> 4)) {
2483 if (EndPointer
!= NULL
) {
2484 *EndPointer
= (CHAR8
*) String
;
2486 return RETURN_UNSUPPORTED
;
2489 *Data
= (*Data
<< 4) + InternalAsciiHexCharToUintn (*String
);
2493 if (EndPointer
!= NULL
) {
2494 *EndPointer
= (CHAR8
*) String
;
2496 return RETURN_SUCCESS
;
2500 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
2502 This function outputs a value of type UINT64 by interpreting the contents of
2503 the Ascii string specified by String as a hexadecimal number. The format of
2504 the input Ascii string String is:
2506 [spaces][zeros][x][hexadecimal digits].
2508 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2509 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
2510 "x" appears in the input string, it must be prefixed with at least one 0. The
2511 function will ignore the pad space, which includes spaces or tab characters,
2512 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
2513 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
2514 the first valid hexadecimal digit. Then, the function stops at the first
2515 character that is a not a valid hexadecimal character or Null-terminator,
2516 whichever on comes first.
2518 If String is NULL, then ASSERT().
2519 If Data is NULL, then ASSERT().
2520 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2521 PcdMaximumAsciiStringLength Ascii characters, not including the
2522 Null-terminator, then ASSERT().
2524 If String has no valid hexadecimal digits in the above format, then 0 is
2525 stored at the location pointed to by Data.
2526 If the number represented by String exceeds the range defined by UINT64, then
2527 MAX_UINT64 is stored at the location pointed to by Data.
2529 If EndPointer is not NULL, a pointer to the character that stopped the scan
2530 is stored at the location pointed to by EndPointer. If String has no valid
2531 hexadecimal digits right after the optional pad spaces, the value of String
2532 is stored at the location pointed to by EndPointer.
2534 @param String Pointer to a Null-terminated Ascii string.
2535 @param EndPointer Pointer to character that stops scan.
2536 @param Data Pointer to the converted value.
2538 @retval RETURN_SUCCESS Value is translated from String.
2539 @retval RETURN_INVALID_PARAMETER If String is NULL.
2541 If PcdMaximumAsciiStringLength is not zero,
2542 and String contains more than
2543 PcdMaximumAsciiStringLength Ascii
2544 characters, not including the
2546 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
2547 the range defined by UINT64.
2552 AsciiStrHexToUint64S (
2553 IN CONST CHAR8
*String
,
2554 OUT CHAR8
**EndPointer
, OPTIONAL
2559 // 1. Neither String nor Data shall be a null pointer.
2561 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
2562 SAFE_STRING_CONSTRAINT_CHECK ((Data
!= NULL
), RETURN_INVALID_PARAMETER
);
2565 // 2. The length of String shall not be greater than ASCII_RSIZE_MAX.
2567 if (ASCII_RSIZE_MAX
!= 0) {
2568 SAFE_STRING_CONSTRAINT_CHECK ((AsciiStrnLenS (String
, ASCII_RSIZE_MAX
+ 1) <= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2571 if (EndPointer
!= NULL
) {
2572 *EndPointer
= (CHAR8
*) String
;
2576 // Ignore the pad spaces (space or tab)
2578 while ((*String
== ' ') || (*String
== '\t')) {
2583 // Ignore leading Zeros after the spaces
2585 while (*String
== '0') {
2589 if (InternalBaseLibAsciiToUpper (*String
) == 'X') {
2590 if (*(String
- 1) != '0') {
2592 return RETURN_SUCCESS
;
2602 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
2604 // If the number represented by String overflows according to the range
2605 // defined by UINT64, then MAX_UINT64 is stored in *Data and
2606 // RETURN_UNSUPPORTED is returned.
2608 if (*Data
> RShiftU64 (MAX_UINT64
- InternalAsciiHexCharToUintn (*String
), 4)) {
2610 if (EndPointer
!= NULL
) {
2611 *EndPointer
= (CHAR8
*) String
;
2613 return RETURN_UNSUPPORTED
;
2616 *Data
= LShiftU64 (*Data
, 4) + InternalAsciiHexCharToUintn (*String
);
2620 if (EndPointer
!= NULL
) {
2621 *EndPointer
= (CHAR8
*) String
;
2623 return RETURN_SUCCESS
;
2627 Convert a Null-terminated Unicode string to a Null-terminated
2630 This function is similar to AsciiStrCpyS.
2632 This function converts the content of the Unicode string Source
2633 to the ASCII string Destination by copying the lower 8 bits of
2634 each Unicode character. The function terminates the ASCII string
2635 Destination by appending a Null-terminator character at the end.
2637 The caller is responsible to make sure Destination points to a buffer with size
2638 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
2640 If any Unicode characters in Source contain non-zero value in
2641 the upper 8 bits, then ASSERT().
2643 If Source is not aligned on a 16-bit boundary, then ASSERT().
2644 If an error would be returned, then the function will also ASSERT().
2646 If an error is returned, then the Destination is unmodified.
2648 @param Source The pointer to a Null-terminated Unicode string.
2649 @param Destination The pointer to a Null-terminated ASCII string.
2650 @param DestMax The maximum number of Destination Ascii
2651 char, including terminating null char.
2653 @retval RETURN_SUCCESS String is converted.
2654 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2655 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2657 If PcdMaximumAsciiStringLength is not zero,
2658 and DestMax is greater than
2659 PcdMaximumAsciiStringLength.
2660 If PcdMaximumUnicodeStringLength is not zero,
2661 and DestMax is greater than
2662 PcdMaximumUnicodeStringLength.
2664 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2669 UnicodeStrToAsciiStrS (
2670 IN CONST CHAR16
*Source
,
2671 OUT CHAR8
*Destination
,
2677 ASSERT (((UINTN
) Source
& BIT0
) == 0);
2680 // 1. Neither Destination nor Source shall be a null pointer.
2682 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2683 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2686 // 2. DestMax shall not be greater than ASCII_RSIZE_MAX or RSIZE_MAX.
2688 if (ASCII_RSIZE_MAX
!= 0) {
2689 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2691 if (RSIZE_MAX
!= 0) {
2692 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2696 // 3. DestMax shall not equal zero.
2698 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2701 // 4. DestMax shall be greater than StrnLenS (Source, DestMax).
2703 SourceLen
= StrnLenS (Source
, DestMax
);
2704 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2707 // 5. Copying shall not take place between objects that overlap.
2709 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof(CHAR16
)), RETURN_ACCESS_DENIED
);
2714 while (*Source
!= '\0') {
2716 // If any Unicode characters in Source contain
2717 // non-zero value in the upper 8 bits, then ASSERT().
2719 ASSERT (*Source
< 0x100);
2720 *(Destination
++) = (CHAR8
) *(Source
++);
2722 *Destination
= '\0';
2724 return RETURN_SUCCESS
;
2728 Convert not more than Length successive characters from a Null-terminated
2729 Unicode string to a Null-terminated Ascii string. If no null char is copied
2730 from Source, then Destination[Length] is always set to null.
2732 This function converts not more than Length successive characters from the
2733 Unicode string Source to the Ascii string Destination by copying the lower 8
2734 bits of each Unicode character. The function terminates the Ascii string
2735 Destination by appending a Null-terminator character at the end.
2737 The caller is responsible to make sure Destination points to a buffer with
2738 size not smaller than ((MIN(StrLen(Source), Length) + 1) * sizeof (CHAR8))
2741 If any Unicode characters in Source contain non-zero value in the upper 8
2742 bits, then ASSERT().
2743 If Source is not aligned on a 16-bit boundary, then ASSERT().
2744 If an error would be returned, then the function will also ASSERT().
2746 If an error is returned, then Destination and DestinationLength are
2749 @param Source The pointer to a Null-terminated Unicode string.
2750 @param Length The maximum number of Unicode characters to
2752 @param Destination The pointer to a Null-terminated Ascii string.
2753 @param DestMax The maximum number of Destination Ascii char,
2754 including terminating null char.
2755 @param DestinationLength The number of Unicode characters converted.
2757 @retval RETURN_SUCCESS String is converted.
2758 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2760 If DestinationLength is NULL.
2761 If PcdMaximumAsciiStringLength is not zero,
2762 and Length or DestMax is greater than
2763 PcdMaximumAsciiStringLength.
2764 If PcdMaximumUnicodeStringLength is not
2765 zero, and Length or DestMax is greater than
2766 PcdMaximumUnicodeStringLength.
2768 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2769 MIN(StrLen(Source), Length).
2770 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2775 UnicodeStrnToAsciiStrS (
2776 IN CONST CHAR16
*Source
,
2778 OUT CHAR8
*Destination
,
2780 OUT UINTN
*DestinationLength
2785 ASSERT (((UINTN
) Source
& BIT0
) == 0);
2788 // 1. None of Destination, Source or DestinationLength shall be a null
2791 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2792 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2793 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
2796 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
2799 if (ASCII_RSIZE_MAX
!= 0) {
2800 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2801 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2803 if (RSIZE_MAX
!= 0) {
2804 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2805 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2809 // 3. DestMax shall not equal zero.
2811 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2814 // 4. If Length is not less than DestMax, then DestMax shall be greater than
2815 // StrnLenS(Source, DestMax).
2817 SourceLen
= StrnLenS (Source
, DestMax
);
2818 if (Length
>= DestMax
) {
2819 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2823 // 5. Copying shall not take place between objects that overlap.
2825 if (SourceLen
> Length
) {
2828 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
, (VOID
*)Source
, (SourceLen
+ 1) * sizeof(CHAR16
)), RETURN_ACCESS_DENIED
);
2830 *DestinationLength
= 0;
2835 while ((*Source
!= 0) && (SourceLen
> 0)) {
2837 // If any Unicode characters in Source contain non-zero value in the upper
2838 // 8 bits, then ASSERT().
2840 ASSERT (*Source
< 0x100);
2841 *(Destination
++) = (CHAR8
) *(Source
++);
2843 (*DestinationLength
)++;
2847 return RETURN_SUCCESS
;
2851 Convert one Null-terminated ASCII string to a Null-terminated
2854 This function is similar to StrCpyS.
2856 This function converts the contents of the ASCII string Source to the Unicode
2857 string Destination. The function terminates the Unicode string Destination by
2858 appending a Null-terminator character at the end.
2860 The caller is responsible to make sure Destination points to a buffer with size
2861 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2863 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2864 If an error would be returned, then the function will also ASSERT().
2866 If an error is returned, then the Destination is unmodified.
2868 @param Source The pointer to a Null-terminated ASCII string.
2869 @param Destination The pointer to a Null-terminated Unicode string.
2870 @param DestMax The maximum number of Destination Unicode
2871 char, including terminating null char.
2873 @retval RETURN_SUCCESS String is converted.
2874 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2875 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2877 If PcdMaximumUnicodeStringLength is not zero,
2878 and DestMax is greater than
2879 PcdMaximumUnicodeStringLength.
2880 If PcdMaximumAsciiStringLength is not zero,
2881 and DestMax is greater than
2882 PcdMaximumAsciiStringLength.
2884 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2889 AsciiStrToUnicodeStrS (
2890 IN CONST CHAR8
*Source
,
2891 OUT CHAR16
*Destination
,
2897 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
2900 // 1. Neither Destination nor Source shall be a null pointer.
2902 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
2903 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
2906 // 2. DestMax shall not be greater than RSIZE_MAX or ASCII_RSIZE_MAX.
2908 if (RSIZE_MAX
!= 0) {
2909 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2911 if (ASCII_RSIZE_MAX
!= 0) {
2912 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
2916 // 3. DestMax shall not equal zero.
2918 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
2921 // 4. DestMax shall be greater than AsciiStrnLenS(Source, DestMax).
2923 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
2924 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
2927 // 5. Copying shall not take place between objects that overlap.
2929 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof(CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
2934 while (*Source
!= '\0') {
2935 *(Destination
++) = (CHAR16
)*(Source
++);
2937 *Destination
= '\0';
2939 return RETURN_SUCCESS
;
2943 Convert not more than Length successive characters from a Null-terminated
2944 Ascii string to a Null-terminated Unicode string. If no null char is copied
2945 from Source, then Destination[Length] is always set to null.
2947 This function converts not more than Length successive characters from the
2948 Ascii string Source to the Unicode string Destination. The function
2949 terminates the Unicode string Destination by appending a Null-terminator
2950 character at the end.
2952 The caller is responsible to make sure Destination points to a buffer with
2953 size not smaller than
2954 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2956 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2957 If an error would be returned, then the function will also ASSERT().
2959 If an error is returned, then Destination and DestinationLength are
2962 @param Source The pointer to a Null-terminated Ascii string.
2963 @param Length The maximum number of Ascii characters to convert.
2964 @param Destination The pointer to a Null-terminated Unicode string.
2965 @param DestMax The maximum number of Destination Unicode char,
2966 including terminating null char.
2967 @param DestinationLength The number of Ascii characters converted.
2969 @retval RETURN_SUCCESS String is converted.
2970 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2972 If DestinationLength is NULL.
2973 If PcdMaximumUnicodeStringLength is not
2974 zero, and Length or DestMax is greater than
2975 PcdMaximumUnicodeStringLength.
2976 If PcdMaximumAsciiStringLength is not zero,
2977 and Length or DestMax is greater than
2978 PcdMaximumAsciiStringLength.
2980 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2981 MIN(AsciiStrLen(Source), Length).
2982 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2987 AsciiStrnToUnicodeStrS (
2988 IN CONST CHAR8
*Source
,
2990 OUT CHAR16
*Destination
,
2992 OUT UINTN
*DestinationLength
2997 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
3000 // 1. None of Destination, Source or DestinationLength shall be a null
3003 SAFE_STRING_CONSTRAINT_CHECK ((Destination
!= NULL
), RETURN_INVALID_PARAMETER
);
3004 SAFE_STRING_CONSTRAINT_CHECK ((Source
!= NULL
), RETURN_INVALID_PARAMETER
);
3005 SAFE_STRING_CONSTRAINT_CHECK ((DestinationLength
!= NULL
), RETURN_INVALID_PARAMETER
);
3008 // 2. Neither Length nor DestMax shall be greater than ASCII_RSIZE_MAX or
3011 if (RSIZE_MAX
!= 0) {
3012 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3013 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3015 if (ASCII_RSIZE_MAX
!= 0) {
3016 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3017 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3021 // 3. DestMax shall not equal zero.
3023 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
!= 0), RETURN_INVALID_PARAMETER
);
3026 // 4. If Length is not less than DestMax, then DestMax shall be greater than
3027 // AsciiStrnLenS(Source, DestMax).
3029 SourceLen
= AsciiStrnLenS (Source
, DestMax
);
3030 if (Length
>= DestMax
) {
3031 SAFE_STRING_CONSTRAINT_CHECK ((DestMax
> SourceLen
), RETURN_BUFFER_TOO_SMALL
);
3035 // 5. Copying shall not take place between objects that overlap.
3037 if (SourceLen
> Length
) {
3040 SAFE_STRING_CONSTRAINT_CHECK (!InternalSafeStringIsOverlap (Destination
, DestMax
* sizeof(CHAR16
), (VOID
*)Source
, SourceLen
+ 1), RETURN_ACCESS_DENIED
);
3042 *DestinationLength
= 0;
3047 while ((*Source
!= 0) && (SourceLen
> 0)) {
3048 *(Destination
++) = (CHAR16
)*(Source
++);
3050 (*DestinationLength
)++;
3054 return RETURN_SUCCESS
;
3058 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
3060 This function outputs a value of type IPv6_ADDRESS and may output a value
3061 of type UINT8 by interpreting the contents of the ASCII string specified
3062 by String. The format of the input ASCII string String is as follows:
3066 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
3067 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
3068 memory address and high byte is stored in high memory address. P contains decimal
3069 digit characters in the range [0-9]. The running zero in the beginning of P will
3070 be ignored. /P is optional.
3072 When /P is not in the String, the function stops at the first character that is
3073 not a valid hexadecimal digit character after eight X's are converted.
3075 When /P is in the String, the function stops at the first character that is not
3076 a valid decimal digit character after P is converted.
3078 "::" can be used to compress one or more groups of X when X contains only 0.
3079 The "::" can only appear once in the String.
3081 If String is NULL, then ASSERT().
3083 If Address is NULL, then ASSERT().
3085 If EndPointer is not NULL and Address is translated from String, a pointer
3086 to the character that stopped the scan is stored at the location pointed to
3089 @param String Pointer to a Null-terminated ASCII string.
3090 @param EndPointer Pointer to character that stops scan.
3091 @param Address Pointer to the converted IPv6 address.
3092 @param PrefixLength Pointer to the converted IPv6 address prefix
3093 length. MAX_UINT8 is returned when /P is
3096 @retval RETURN_SUCCESS Address is translated from String.
3097 @retval RETURN_INVALID_PARAMETER If String is NULL.
3099 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
3101 If String contains "::" and number of X
3103 If P starts with character that is not a
3104 valid decimal digit character.
3105 If the decimal number converted from P
3111 AsciiStrToIpv6Address (
3112 IN CONST CHAR8
*String
,
3113 OUT CHAR8
**EndPointer
, OPTIONAL
3114 OUT IPv6_ADDRESS
*Address
,
3115 OUT UINT8
*PrefixLength OPTIONAL
3118 RETURN_STATUS Status
;
3121 IPv6_ADDRESS LocalAddress
;
3122 UINT8 LocalPrefixLength
;
3123 CONST CHAR8
*Pointer
;
3125 UINTN CompressStart
;
3126 BOOLEAN ExpectPrefix
;
3128 LocalPrefixLength
= MAX_UINT8
;
3129 CompressStart
= ARRAY_SIZE (Address
->Addr
);
3130 ExpectPrefix
= FALSE
;
3133 // None of String or Address shall be a null pointer.
3135 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3136 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3138 for (Pointer
= String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3139 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3140 if (*Pointer
!= ':') {
3142 // ":" or "/" should be followed by digit characters.
3144 return RETURN_UNSUPPORTED
;
3148 // Meet second ":" after previous ":" or "/"
3149 // or meet first ":" in the beginning of String.
3153 // ":" shall not be after "/"
3155 return RETURN_UNSUPPORTED
;
3158 if (CompressStart
!= ARRAY_SIZE (Address
->Addr
) || AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3160 // "::" can only appear once.
3161 // "::" can only appear when address is not full length.
3163 return RETURN_UNSUPPORTED
;
3166 // Remember the start of zero compressing.
3168 CompressStart
= AddressIndex
;
3171 if (CompressStart
== 0) {
3172 if (*Pointer
!= ':') {
3174 // Single ":" shall not be in the beginning of String.
3176 return RETURN_UNSUPPORTED
;
3183 if (!InternalAsciiIsHexaDecimalDigitCharacter (*Pointer
)) {
3184 if (*Pointer
== '/') {
3186 // Might be optional "/P" after "::".
3188 if (CompressStart
!= AddressIndex
) {
3189 return RETURN_UNSUPPORTED
;
3195 if (!ExpectPrefix
) {
3199 Status
= AsciiStrHexToUintnS (Pointer
, &End
, &Uintn
);
3200 if (RETURN_ERROR (Status
) || End
- Pointer
> 4) {
3202 // Number of hexadecimal digit characters is no more than 4.
3204 return RETURN_UNSUPPORTED
;
3208 // Uintn won't exceed MAX_UINT16 if number of hexadecimal digit characters is no more than 4.
3210 ASSERT (AddressIndex
+ 1 < ARRAY_SIZE (Address
->Addr
));
3211 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) ((UINT16
) Uintn
>> 8);
3212 LocalAddress
.Addr
[AddressIndex
+ 1] = (UINT8
) Uintn
;
3216 // Get P, then exit the loop.
3218 Status
= AsciiStrDecimalToUintnS (Pointer
, &End
, &Uintn
);
3219 if (RETURN_ERROR (Status
) || End
== Pointer
|| Uintn
> 128) {
3221 // Prefix length should not exceed 128.
3223 return RETURN_UNSUPPORTED
;
3225 LocalPrefixLength
= (UINT8
) Uintn
;
3234 if (*Pointer
== '/') {
3235 ExpectPrefix
= TRUE
;
3236 } else if (*Pointer
== ':') {
3237 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3239 // Meet additional ":" after all 8 16-bit address
3245 // Meet other character that is not "/" or ":" after all 8 16-bit address
3252 if ((AddressIndex
== ARRAY_SIZE (Address
->Addr
) && CompressStart
!= ARRAY_SIZE (Address
->Addr
)) ||
3253 (AddressIndex
!= ARRAY_SIZE (Address
->Addr
) && CompressStart
== ARRAY_SIZE (Address
->Addr
))
3256 // Full length of address shall not have compressing zeros.
3257 // Non-full length of address shall have compressing zeros.
3259 return RETURN_UNSUPPORTED
;
3261 CopyMem (&Address
->Addr
[0], &LocalAddress
.Addr
[0], CompressStart
);
3262 ZeroMem (&Address
->Addr
[CompressStart
], ARRAY_SIZE (Address
->Addr
) - AddressIndex
);
3263 if (AddressIndex
> CompressStart
) {
3265 &Address
->Addr
[CompressStart
+ ARRAY_SIZE (Address
->Addr
) - AddressIndex
],
3266 &LocalAddress
.Addr
[CompressStart
],
3267 AddressIndex
- CompressStart
3272 if (PrefixLength
!= NULL
) {
3273 *PrefixLength
= LocalPrefixLength
;
3275 if (EndPointer
!= NULL
) {
3276 *EndPointer
= (CHAR8
*) Pointer
;
3279 return RETURN_SUCCESS
;
3283 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
3285 This function outputs a value of type IPv4_ADDRESS and may output a value
3286 of type UINT8 by interpreting the contents of the ASCII string specified
3287 by String. The format of the input ASCII string String is as follows:
3291 D and P are decimal digit characters in the range [0-9]. The running zero in
3292 the beginning of D and P will be ignored. /P is optional.
3294 When /P is not in the String, the function stops at the first character that is
3295 not a valid decimal digit character after four D's are converted.
3297 When /P is in the String, the function stops at the first character that is not
3298 a valid decimal digit character after P is converted.
3300 If String is NULL, then ASSERT().
3302 If Address is NULL, then ASSERT().
3304 If EndPointer is not NULL and Address is translated from String, a pointer
3305 to the character that stopped the scan is stored at the location pointed to
3308 @param String Pointer to a Null-terminated ASCII string.
3309 @param EndPointer Pointer to character that stops scan.
3310 @param Address Pointer to the converted IPv4 address.
3311 @param PrefixLength Pointer to the converted IPv4 address prefix
3312 length. MAX_UINT8 is returned when /P is
3315 @retval RETURN_SUCCESS Address is translated from String.
3316 @retval RETURN_INVALID_PARAMETER If String is NULL.
3318 @retval RETURN_UNSUPPORTED If String is not in the correct format.
3319 If any decimal number converted from D
3321 If the decimal number converted from P
3327 AsciiStrToIpv4Address (
3328 IN CONST CHAR8
*String
,
3329 OUT CHAR8
**EndPointer
, OPTIONAL
3330 OUT IPv4_ADDRESS
*Address
,
3331 OUT UINT8
*PrefixLength OPTIONAL
3334 RETURN_STATUS Status
;
3337 IPv4_ADDRESS LocalAddress
;
3338 UINT8 LocalPrefixLength
;
3341 LocalPrefixLength
= MAX_UINT8
;
3344 // None of String or Address shall be a null pointer.
3346 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3347 SAFE_STRING_CONSTRAINT_CHECK ((Address
!= NULL
), RETURN_INVALID_PARAMETER
);
3349 for (Pointer
= (CHAR8
*) String
, AddressIndex
= 0; AddressIndex
< ARRAY_SIZE (Address
->Addr
) + 1;) {
3350 if (!InternalAsciiIsDecimalDigitCharacter (*Pointer
)) {
3352 // D or P contains invalid characters.
3360 Status
= AsciiStrDecimalToUintnS ((CONST CHAR8
*) Pointer
, &Pointer
, &Uintn
);
3361 if (RETURN_ERROR (Status
)) {
3362 return RETURN_UNSUPPORTED
;
3364 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3369 return RETURN_UNSUPPORTED
;
3371 LocalPrefixLength
= (UINT8
) Uintn
;
3376 if (Uintn
> MAX_UINT8
) {
3377 return RETURN_UNSUPPORTED
;
3379 LocalAddress
.Addr
[AddressIndex
] = (UINT8
) Uintn
;
3384 // Check the '.' or '/', depending on the AddressIndex.
3386 if (AddressIndex
== ARRAY_SIZE (Address
->Addr
)) {
3387 if (*Pointer
== '/') {
3389 // '/P' is in the String.
3390 // Skip "/" and get P in next loop.
3395 // '/P' is not in the String.
3399 } else if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3400 if (*Pointer
== '.') {
3402 // D should be followed by '.'
3406 return RETURN_UNSUPPORTED
;
3411 if (AddressIndex
< ARRAY_SIZE (Address
->Addr
)) {
3412 return RETURN_UNSUPPORTED
;
3415 CopyMem (Address
, &LocalAddress
, sizeof (*Address
));
3416 if (PrefixLength
!= NULL
) {
3417 *PrefixLength
= LocalPrefixLength
;
3419 if (EndPointer
!= NULL
) {
3420 *EndPointer
= Pointer
;
3423 return RETURN_SUCCESS
;
3427 Convert a Null-terminated ASCII GUID string to a value of type
3430 This function outputs a GUID value by interpreting the contents of
3431 the ASCII string specified by String. The format of the input
3432 ASCII string String consists of 36 characters, as follows:
3434 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
3436 The pairs aa - pp are two characters in the range [0-9], [a-f] and
3437 [A-F], with each pair representing a single byte hexadecimal value.
3439 The mapping between String and the EFI_GUID structure is as follows:
3457 If String is NULL, then ASSERT().
3458 If Guid is NULL, then ASSERT().
3460 @param String Pointer to a Null-terminated ASCII string.
3461 @param Guid Pointer to the converted GUID.
3463 @retval RETURN_SUCCESS Guid is translated from String.
3464 @retval RETURN_INVALID_PARAMETER If String is NULL.
3466 @retval RETURN_UNSUPPORTED If String is not as the above format.
3472 IN CONST CHAR8
*String
,
3476 RETURN_STATUS Status
;
3480 // None of String or Guid shall be a null pointer.
3482 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3483 SAFE_STRING_CONSTRAINT_CHECK ((Guid
!= NULL
), RETURN_INVALID_PARAMETER
);
3486 // Get aabbccdd in big-endian.
3488 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data1
), (UINT8
*) &LocalGuid
.Data1
, sizeof (LocalGuid
.Data1
));
3489 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data1
)] != '-') {
3490 return RETURN_UNSUPPORTED
;
3493 // Convert big-endian to little-endian.
3495 LocalGuid
.Data1
= SwapBytes32 (LocalGuid
.Data1
);
3496 String
+= 2 * sizeof (LocalGuid
.Data1
) + 1;
3499 // Get eeff in big-endian.
3501 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data2
), (UINT8
*) &LocalGuid
.Data2
, sizeof (LocalGuid
.Data2
));
3502 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data2
)] != '-') {
3503 return RETURN_UNSUPPORTED
;
3506 // Convert big-endian to little-endian.
3508 LocalGuid
.Data2
= SwapBytes16 (LocalGuid
.Data2
);
3509 String
+= 2 * sizeof (LocalGuid
.Data2
) + 1;
3512 // Get gghh in big-endian.
3514 Status
= AsciiStrHexToBytes (String
, 2 * sizeof (LocalGuid
.Data3
), (UINT8
*) &LocalGuid
.Data3
, sizeof (LocalGuid
.Data3
));
3515 if (RETURN_ERROR (Status
) || String
[2 * sizeof (LocalGuid
.Data3
)] != '-') {
3516 return RETURN_UNSUPPORTED
;
3519 // Convert big-endian to little-endian.
3521 LocalGuid
.Data3
= SwapBytes16 (LocalGuid
.Data3
);
3522 String
+= 2 * sizeof (LocalGuid
.Data3
) + 1;
3527 Status
= AsciiStrHexToBytes (String
, 2 * 2, &LocalGuid
.Data4
[0], 2);
3528 if (RETURN_ERROR (Status
) || String
[2 * 2] != '-') {
3529 return RETURN_UNSUPPORTED
;
3531 String
+= 2 * 2 + 1;
3534 // Get kkllmmnnoopp.
3536 Status
= AsciiStrHexToBytes (String
, 2 * 6, &LocalGuid
.Data4
[2], 6);
3537 if (RETURN_ERROR (Status
)) {
3538 return RETURN_UNSUPPORTED
;
3541 CopyGuid (Guid
, &LocalGuid
);
3542 return RETURN_SUCCESS
;
3546 Convert a Null-terminated ASCII hexadecimal string to a byte array.
3548 This function outputs a byte array by interpreting the contents of
3549 the ASCII string specified by String in hexadecimal format. The format of
3550 the input ASCII string String is:
3554 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
3555 The function decodes every two hexadecimal digit characters as one byte. The
3556 decoding stops after Length of characters and outputs Buffer containing
3559 If String is NULL, then ASSERT().
3561 If Buffer is NULL, then ASSERT().
3563 If Length is not multiple of 2, then ASSERT().
3565 If PcdMaximumAsciiStringLength is not zero and Length is greater than
3566 PcdMaximumAsciiStringLength, then ASSERT().
3568 If MaxBufferSize is less than (Length / 2), then ASSERT().
3570 @param String Pointer to a Null-terminated ASCII string.
3571 @param Length The number of ASCII characters to decode.
3572 @param Buffer Pointer to the converted bytes array.
3573 @param MaxBufferSize The maximum size of Buffer.
3575 @retval RETURN_SUCCESS Buffer is translated from String.
3576 @retval RETURN_INVALID_PARAMETER If String is NULL.
3578 If Length is not multiple of 2.
3579 If PcdMaximumAsciiStringLength is not zero,
3580 and Length is greater than
3581 PcdMaximumAsciiStringLength.
3582 @retval RETURN_UNSUPPORTED If Length of characters from String contain
3583 a character that is not valid hexadecimal
3584 digit characters, or a Null-terminator.
3585 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
3589 AsciiStrHexToBytes (
3590 IN CONST CHAR8
*String
,
3593 IN UINTN MaxBufferSize
3599 // 1. None of String or Buffer shall be a null pointer.
3601 SAFE_STRING_CONSTRAINT_CHECK ((String
!= NULL
), RETURN_INVALID_PARAMETER
);
3602 SAFE_STRING_CONSTRAINT_CHECK ((Buffer
!= NULL
), RETURN_INVALID_PARAMETER
);
3605 // 2. Length shall not be greater than ASCII_RSIZE_MAX.
3607 if (ASCII_RSIZE_MAX
!= 0) {
3608 SAFE_STRING_CONSTRAINT_CHECK ((Length
<= ASCII_RSIZE_MAX
), RETURN_INVALID_PARAMETER
);
3612 // 3. Length shall not be odd.
3614 SAFE_STRING_CONSTRAINT_CHECK (((Length
& BIT0
) == 0), RETURN_INVALID_PARAMETER
);
3617 // 4. MaxBufferSize shall equal to or greater than Length / 2.
3619 SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize
>= Length
/ 2), RETURN_BUFFER_TOO_SMALL
);
3622 // 5. String shall not contains invalid hexadecimal digits.
3624 for (Index
= 0; Index
< Length
; Index
++) {
3625 if (!InternalAsciiIsHexaDecimalDigitCharacter (String
[Index
])) {
3629 if (Index
!= Length
) {
3630 return RETURN_UNSUPPORTED
;
3634 // Convert the hex string to bytes.
3636 for(Index
= 0; Index
< Length
; Index
++) {
3639 // For even characters, write the upper nibble for each buffer byte,
3640 // and for even characters, the lower nibble.
3642 if ((Index
& BIT0
) == 0) {
3643 Buffer
[Index
/ 2] = (UINT8
) InternalAsciiHexCharToUintn (String
[Index
]) << 4;
3645 Buffer
[Index
/ 2] |= (UINT8
) InternalAsciiHexCharToUintn (String
[Index
]);
3648 return RETURN_SUCCESS
;