#include "BaseLibInternals.h"

Macros
#define	RSIZE_MAX (PcdGet32 (PcdMaximumUnicodeStringLength))

#define	ASCII_RSIZE_MAX (PcdGet32 (PcdMaximumAsciiStringLength))

#define	SAFE_STRING_CONSTRAINT_CHECK(Expression, Status)

Functions
BOOLEAN	InternalSafeStringIsOverlap (IN VOID Base1, IN UINTN Size1, IN VOID Base2, IN UINTN Size2)

BOOLEAN	InternalSafeStringNoStrOverlap (IN CHAR16 Str1, IN UINTN Size1, IN CHAR16 Str2, IN UINTN Size2)

BOOLEAN	InternalSafeStringNoAsciiStrOverlap (IN CHAR8 Str1, IN UINTN Size1, IN CHAR8 Str2, IN UINTN Size2)

UINTN EFIAPI	StrnLenS (IN CONST CHAR16 *String, IN UINTN MaxSize)

UINTN EFIAPI	StrnSizeS (IN CONST CHAR16 *String, IN UINTN MaxSize)

RETURN_STATUS EFIAPI	StrCpyS (OUT CHAR16 Destination, IN UINTN DestMax, IN CONST CHAR16 Source)

RETURN_STATUS EFIAPI	StrnCpyS (OUT CHAR16 Destination, IN UINTN DestMax, IN CONST CHAR16 Source, IN UINTN Length)

RETURN_STATUS EFIAPI	StrCatS (IN OUT CHAR16 Destination, IN UINTN DestMax, IN CONST CHAR16 Source)

RETURN_STATUS EFIAPI	StrnCatS (IN OUT CHAR16 Destination, IN UINTN DestMax, IN CONST CHAR16 Source, IN UINTN Length)

RETURN_STATUS EFIAPI	StrDecimalToUintnS (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT UINTN Data)

RETURN_STATUS EFIAPI	StrDecimalToUint64S (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT UINT64 Data)

RETURN_STATUS EFIAPI	StrHexToUintnS (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT UINTN Data)

RETURN_STATUS EFIAPI	StrHexToUint64S (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT UINT64 Data)

RETURN_STATUS EFIAPI	StrToIpv6Address (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT IPv6_ADDRESS Address, OUT UINT8 *PrefixLength OPTIONAL)

RETURN_STATUS EFIAPI	StrToIpv4Address (IN CONST CHAR16 String, OUT CHAR16 EndPointer OPTIONAL, OUT IPv4_ADDRESS Address, OUT UINT8 *PrefixLength OPTIONAL)

RETURN_STATUS EFIAPI	StrToGuid (IN CONST CHAR16 String, OUT GUID Guid)

RETURN_STATUS EFIAPI	StrHexToBytes (IN CONST CHAR16 String, IN UINTN Length, OUT UINT8 Buffer, IN UINTN MaxBufferSize)

UINTN EFIAPI	AsciiStrnLenS (IN CONST CHAR8 *String, IN UINTN MaxSize)

UINTN EFIAPI	AsciiStrnSizeS (IN CONST CHAR8 *String, IN UINTN MaxSize)

RETURN_STATUS EFIAPI	AsciiStrCpyS (OUT CHAR8 Destination, IN UINTN DestMax, IN CONST CHAR8 Source)

RETURN_STATUS EFIAPI	AsciiStrnCpyS (OUT CHAR8 Destination, IN UINTN DestMax, IN CONST CHAR8 Source, IN UINTN Length)

RETURN_STATUS EFIAPI	AsciiStrCatS (IN OUT CHAR8 Destination, IN UINTN DestMax, IN CONST CHAR8 Source)

RETURN_STATUS EFIAPI	AsciiStrnCatS (IN OUT CHAR8 Destination, IN UINTN DestMax, IN CONST CHAR8 Source, IN UINTN Length)

RETURN_STATUS EFIAPI	AsciiStrDecimalToUintnS (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT UINTN Data)

RETURN_STATUS EFIAPI	AsciiStrDecimalToUint64S (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT UINT64 Data)

RETURN_STATUS EFIAPI	AsciiStrHexToUintnS (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT UINTN Data)

RETURN_STATUS EFIAPI	AsciiStrHexToUint64S (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT UINT64 Data)

RETURN_STATUS EFIAPI	UnicodeStrToAsciiStrS (IN CONST CHAR16 Source, OUT CHAR8 Destination, IN UINTN DestMax)

RETURN_STATUS EFIAPI	UnicodeStrnToAsciiStrS (IN CONST CHAR16 Source, IN UINTN Length, OUT CHAR8 Destination, IN UINTN DestMax, OUT UINTN *DestinationLength)

RETURN_STATUS EFIAPI	AsciiStrToUnicodeStrS (IN CONST CHAR8 Source, OUT CHAR16 Destination, IN UINTN DestMax)

RETURN_STATUS EFIAPI	AsciiStrnToUnicodeStrS (IN CONST CHAR8 Source, IN UINTN Length, OUT CHAR16 Destination, IN UINTN DestMax, OUT UINTN *DestinationLength)

RETURN_STATUS EFIAPI	AsciiStrToIpv6Address (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT IPv6_ADDRESS Address, OUT UINT8 *PrefixLength OPTIONAL)

RETURN_STATUS EFIAPI	AsciiStrToIpv4Address (IN CONST CHAR8 String, OUT CHAR8 EndPointer OPTIONAL, OUT IPv4_ADDRESS Address, OUT UINT8 *PrefixLength OPTIONAL)

RETURN_STATUS EFIAPI	AsciiStrToGuid (IN CONST CHAR8 String, OUT GUID Guid)

RETURN_STATUS EFIAPI	AsciiStrHexToBytes (IN CONST CHAR8 String, IN UINTN Length, OUT UINT8 Buffer, IN UINTN MaxBufferSize)

Detailed Description

Safe String functions.

Copyright (c) 2014 - 2019, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file SafeString.c.

Macro Definition Documentation

◆ ASCII_RSIZE_MAX

#define ASCII_RSIZE_MAX (PcdGet32 (PcdMaximumAsciiStringLength))

Definition at line 13 of file SafeString.c.

◆ RSIZE_MAX

#define RSIZE_MAX (PcdGet32 (PcdMaximumUnicodeStringLength))

Definition at line 11 of file SafeString.c.

◆ SAFE_STRING_CONSTRAINT_CHECK

#define SAFE_STRING_CONSTRAINT_CHECK	(	Expression,
		Status
	)

Value:

  do { \
    if (!(Expression)) { \
      DEBUG ((DEBUG_VERBOSE, \
        "%a(%d) %a: SAFE_STRING_CONSTRAINT_CHECK(%a) failed.  Return %r\n", \
        __FILE__, DEBUG_LINE_NUMBER, __func__, DEBUG_EXPRESSION_STRING (Expression), Status)); \
      return Status; \
    } \
  } while (FALSE)

Definition at line 15 of file SafeString.c.

Function Documentation

◆ AsciiStrCatS()

RETURN_STATUS EFIAPI AsciiStrCatS	(	IN OUT CHAR8 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR8 *	Source
	)

Appends a copy of the string pointed to by Source (including the terminating null char) to the end of the string pointed to by Destination.

This function is similar as strcat_s defined in C11.

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Ascii string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.
Source	A pointer to a Null-terminated Ascii string.

Return values

RETURN_SUCCESS	String is appended.
RETURN_BAD_BUFFER_SIZE	If DestMax is NOT greater than StrLen(Destination).
RETURN_BUFFER_TOO_SMALL	If (DestMax - StrLen(Destination)) is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 1964 of file SafeString.c.

◆ AsciiStrCpyS()

RETURN_STATUS EFIAPI AsciiStrCpyS	(	OUT CHAR8 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR8 *	Source
	)

Copies the string pointed to by Source (including the terminating null char) to the array pointed to by Destination.

This function is similar as strcpy_s defined in C11.

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Ascii string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.
Source	A pointer to a Null-terminated Ascii string.

Return values

RETURN_SUCCESS	String is copied.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 1797 of file SafeString.c.

◆ AsciiStrDecimalToUint64S()

RETURN_STATUS EFIAPI AsciiStrDecimalToUint64S	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT UINT64 *	Data
	)

Convert a Null-terminated Ascii decimal string to a value of type UINT64.

This function outputs a value of type UINT64 by interpreting the contents of the Ascii string specified by String as a decimal number. The format of the input Ascii string String is:

            [spaces] [decimal digits].

The valid decimal digit character is in the range [0-9]. The function will ignore the pad space, which includes spaces or tab characters, before [decimal digits]. The running zero in the beginning of [decimal digits] will be ignored. Then, the function stops at the first character that is a not a valid decimal character or a Null-terminator, whichever one comes first.

If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then MAX_UINT64 is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid decimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Ascii string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumAsciiStringLength is not zero, and String contains more than PcdMaximumAsciiStringLength Ascii characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINT64.

Definition at line 2287 of file SafeString.c.

◆ AsciiStrDecimalToUintnS()

RETURN_STATUS EFIAPI AsciiStrDecimalToUintnS	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT UINTN *	Data
	)

Convert a Null-terminated Ascii decimal string to a value of type UINTN.

This function outputs a value of type UINTN by interpreting the contents of the Ascii string specified by String as a decimal number. The format of the input Ascii string String is:

            [spaces] [decimal digits].

The valid decimal digit character is in the range [0-9]. The function will ignore the pad space, which includes spaces or tab characters, before [decimal digits]. The running zero in the beginning of [decimal digits] will be ignored. Then, the function stops at the first character that is a not a valid decimal character or a Null-terminator, whichever one comes first.

If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then MAX_UINTN is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid decimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Ascii string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumAsciiStringLength is not zero, and String contains more than PcdMaximumAsciiStringLength Ascii characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINTN.

Definition at line 2179 of file SafeString.c.

◆ AsciiStrHexToBytes()

RETURN_STATUS EFIAPI AsciiStrHexToBytes	(	IN CONST CHAR8 *	String,
		IN UINTN	Length,
		OUT UINT8 *	Buffer,
		IN UINTN	MaxBufferSize
	)

Convert a Null-terminated ASCII hexadecimal string to a byte array.

This function outputs a byte array by interpreting the contents of the ASCII string specified by String in hexadecimal format. The format of the input ASCII string String is:

            [XX]*

X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F]. The function decodes every two hexadecimal digit characters as one byte. The decoding stops after Length of characters and outputs Buffer containing (Length / 2) bytes.

Parameters

String	Pointer to a Null-terminated ASCII string.
Length	The number of ASCII characters to decode.
Buffer	Pointer to the converted bytes array.
MaxBufferSize	The maximum size of Buffer.

Return values

RETURN_SUCCESS	Buffer is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If Length is not multiple of 2. If PcdMaximumAsciiStringLength is not zero, and Length is greater than PcdMaximumAsciiStringLength.
RETURN_UNSUPPORTED	If Length of characters from String contain a character that is not valid hexadecimal digit characters, or a Null-terminator.
RETURN_BUFFER_TOO_SMALL	If MaxBufferSize is less than (Length / 2).

Definition at line 3569 of file SafeString.c.

◆ AsciiStrHexToUint64S()

RETURN_STATUS EFIAPI AsciiStrHexToUint64S	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT UINT64 *	Data
	)

Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.

This function outputs a value of type UINT64 by interpreting the contents of the Ascii string specified by String as a hexadecimal number. The format of the input Ascii string String is:

            [spaces][zeros][x][hexadecimal digits].

The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" appears in the input string, it must be prefixed with at least one 0. The function will ignore the pad space, which includes spaces or tab characters, before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal digit. Then, the function stops at the first character that is a not a valid hexadecimal character or Null-terminator, whichever on comes first.

If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then MAX_UINT64 is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid hexadecimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Ascii string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumAsciiStringLength is not zero, and String contains more than PcdMaximumAsciiStringLength Ascii characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINT64.

Definition at line 2527 of file SafeString.c.

◆ AsciiStrHexToUintnS()

RETURN_STATUS EFIAPI AsciiStrHexToUintnS	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT UINTN *	Data
	)

Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.

This function outputs a value of type UINTN by interpreting the contents of the Ascii string specified by String as a hexadecimal number. The format of the input Ascii string String is:

            [spaces][zeros][x][hexadecimal digits].

The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" appears in the input string, it must be prefixed with at least one 0. The function will ignore the pad space, which includes spaces or tab characters, before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal digit. Then, the function stops at the first character that is a not a valid hexadecimal character or Null-terminator, whichever on comes first.

If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then MAX_UINTN is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid hexadecimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Ascii string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumAsciiStringLength is not zero, and String contains more than PcdMaximumAsciiStringLength Ascii characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINTN.

Definition at line 2399 of file SafeString.c.

◆ AsciiStrnCatS()

RETURN_STATUS EFIAPI AsciiStrnCatS	(	IN OUT CHAR8 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR8 *	Source,
		IN UINTN	Length
	)

Appends not more than Length successive char from the string pointed to by Source to the end of the string pointed to by Destination. If no null char is copied from Source, then Destination[StrLen(Destination) + Length] is always set to null.

This function is similar as strncat_s defined in C11.

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Ascii string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.
Source	A pointer to a Null-terminated Ascii string.
Length	The maximum number of Ascii characters to copy.

Return values

RETURN_SUCCESS	String is appended.
RETURN_BAD_BUFFER_SIZE	If DestMax is NOT greater than StrLen(Destination).
RETURN_BUFFER_TOO_SMALL	If (DestMax - StrLen(Destination)) is NOT greater than MIN(StrLen(Source), Length).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 2060 of file SafeString.c.

◆ AsciiStrnCpyS()

RETURN_STATUS EFIAPI AsciiStrnCpyS	(	OUT CHAR8 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR8 *	Source,
		IN UINTN	Length
	)

Copies not more than Length successive char from the string pointed to by Source to the array pointed to by Destination. If no null char is copied from Source, then Destination[Length] is always set to null.

This function is similar as strncpy_s defined in C11.

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Ascii string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.
Source	A pointer to a Null-terminated Ascii string.
Length	The maximum number of Ascii characters to copy.

Return values

RETURN_SUCCESS	String is copied.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than MIN(StrLen(Source), Length).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 1875 of file SafeString.c.

◆ AsciiStrnLenS()

UINTN EFIAPI AsciiStrnLenS	(	IN CONST CHAR8 *	String,
		IN UINTN	MaxSize
	)

Returns the length of a Null-terminated Ascii string.

This function is similar as strlen_s defined in C11.

Parameters

String	A pointer to a Null-terminated Ascii string.
MaxSize	The maximum number of Destination Ascii char, including terminating null char.

Return values

0	If String is NULL.
MaxSize	If there is no null character in the first MaxSize characters of String.

Returns: The number of characters that percede the terminating null character.

Definition at line 1696 of file SafeString.c.

◆ AsciiStrnSizeS()

UINTN EFIAPI AsciiStrnSizeS	(	IN CONST CHAR8 *	String,
		IN UINTN	MaxSize
	)

Returns the size of a Null-terminated Ascii string in bytes, including the Null terminator.

This function returns the size of the Null-terminated Ascii string specified by String in bytes, including the Null terminator.

Parameters

String	A pointer to a Null-terminated Ascii string.
MaxSize	The maximum number of Destination Ascii char, including the Null terminator.

Return values

0	If String is NULL.
(sizeof	(CHAR8) * (MaxSize + 1)) If there is no Null terminator in the first MaxSize characters of String.

Returns: The size of the Null-terminated Ascii string in bytes, including the Null terminator.

Definition at line 1749 of file SafeString.c.

◆ AsciiStrnToUnicodeStrS()

RETURN_STATUS EFIAPI AsciiStrnToUnicodeStrS	(	IN CONST CHAR8 *	Source,
		IN UINTN	Length,
		OUT CHAR16 *	Destination,
		IN UINTN	DestMax,
		OUT UINTN *	DestinationLength
	)

Convert not more than Length successive characters from a Null-terminated Ascii string to a Null-terminated Unicode string. If no null char is copied from Source, then Destination[Length] is always set to null.

This function converts not more than Length successive characters from the Ascii string Source to the Unicode string Destination. The function terminates the Unicode string Destination by appending a Null-terminator character at the end.

The caller is responsible to make sure Destination points to a buffer with size not smaller than ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.

If Destination is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then Destination and DestinationLength are unmodified.

Parameters

Source	The pointer to a Null-terminated Ascii string.
Length	The maximum number of Ascii characters to convert.
Destination	The pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.
DestinationLength	The number of Ascii characters converted.

Return values

RETURN_SUCCESS	String is converted.
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If DestinationLength is NULL. If PcdMaximumUnicodeStringLength is not zero, and Length or DestMax is greater than PcdMaximumUnicodeStringLength. If PcdMaximumAsciiStringLength is not zero, and Length or DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than MIN(AsciiStrLen(Source), Length).
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 2972 of file SafeString.c.

◆ AsciiStrToGuid()

RETURN_STATUS EFIAPI AsciiStrToGuid	(	IN CONST CHAR8 *	String,
		OUT GUID *	Guid
	)

Convert a Null-terminated ASCII GUID string to a value of type EFI_GUID.

This function outputs a GUID value by interpreting the contents of the ASCII string specified by String. The format of the input ASCII string String consists of 36 characters, as follows:

            aabbccdd-eeff-gghh-iijj-kkllmmnnoopp

The pairs aa - pp are two characters in the range [0-9], [a-f] and [A-F], with each pair representing a single byte hexadecimal value.

The mapping between String and the EFI_GUID structure is as follows: aa Data1[24:31] bb Data1[16:23] cc Data1[8:15] dd Data1[0:7] ee Data2[8:15] ff Data2[0:7] gg Data3[8:15] hh Data3[0:7] ii Data4[0:7] jj Data4[8:15] kk Data4[16:23] ll Data4[24:31] mm Data4[32:39] nn Data4[40:47] oo Data4[48:55] pp Data4[56:63]

Parameters

String	Pointer to a Null-terminated ASCII string.
Guid	Pointer to the converted GUID.

Return values

RETURN_SUCCESS	Guid is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If String is not as the above format.

Definition at line 3458 of file SafeString.c.

◆ AsciiStrToIpv4Address()

RETURN_STATUS EFIAPI AsciiStrToIpv4Address	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT IPv4_ADDRESS *	Address,
		OUT UINT8 *PrefixLength	OPTIONAL
	)

Convert a Null-terminated ASCII string to IPv4 address and prefix length.

This function outputs a value of type IPv4_ADDRESS and may output a value of type UINT8 by interpreting the contents of the ASCII string specified by String. The format of the input ASCII string String is as follows:

            D.D.D.D[/P]

D and P are decimal digit characters in the range [0-9]. The running zero in the beginning of D and P will be ignored. /P is optional.

When /P is not in the String, the function stops at the first character that is not a valid decimal digit character after four D's are converted.

When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted.

If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated ASCII string.
EndPointer	Pointer to character that stops scan.
Address	Pointer to the converted IPv4 address.
PrefixLength	Pointer to the converted IPv4 address prefix length. MAX_UINT8 is returned when /P is not in the String.

Return values

RETURN_SUCCESS	Address is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If String is not in the correct format. If any decimal number converted from D exceeds 255. If the decimal number converted from P exceeds 32.

Definition at line 3313 of file SafeString.c.

◆ AsciiStrToIpv6Address()

RETURN_STATUS EFIAPI AsciiStrToIpv6Address	(	IN CONST CHAR8 *	String,
		OUT CHAR8 **EndPointer	OPTIONAL,
		OUT IPv6_ADDRESS *	Address,
		OUT UINT8 *PrefixLength	OPTIONAL
	)

Convert a Null-terminated ASCII string to IPv6 address and prefix length.

This function outputs a value of type IPv6_ADDRESS and may output a value of type UINT8 by interpreting the contents of the ASCII string specified by String. The format of the input ASCII string String is as follows:

            X:X:X:X:X:X:X:X[/P]

X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low memory address and high byte is stored in high memory address. P contains decimal digit characters in the range [0-9]. The running zero in the beginning of P will be ignored. /P is optional.

When /P is not in the String, the function stops at the first character that is not a valid hexadecimal digit character after eight X's are converted.

When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted.

"::" can be used to compress one or more groups of X when X contains only 0. The "::" can only appear once in the String.

If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated ASCII string.
EndPointer	Pointer to character that stops scan.
Address	Pointer to the converted IPv6 address.
PrefixLength	Pointer to the converted IPv6 address prefix length. MAX_UINT8 is returned when /P is not in the String.

Return values

RETURN_SUCCESS	Address is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If X contains more than four hexadecimal digit characters. If String contains "::" and number of X is not less than 8. If P starts with character that is not a valid decimal digit character. If the decimal number converted from P exceeds 128.

Definition at line 3095 of file SafeString.c.

◆ AsciiStrToUnicodeStrS()

RETURN_STATUS EFIAPI AsciiStrToUnicodeStrS	(	IN CONST CHAR8 *	Source,
		OUT CHAR16 *	Destination,
		IN UINTN	DestMax
	)

Convert one Null-terminated ASCII string to a Null-terminated Unicode string.

This function is similar to StrCpyS.

This function converts the contents of the ASCII string Source to the Unicode string Destination. The function terminates the Unicode string Destination by appending a Null-terminator character at the end.

The caller is responsible to make sure Destination points to a buffer with size equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.

If Destination is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Source	The pointer to a Null-terminated ASCII string.
Destination	The pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.

Return values

RETURN_SUCCESS	String is converted.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 2873 of file SafeString.c.

◆ InternalSafeStringIsOverlap()

BOOLEAN InternalSafeStringIsOverlap	(	IN VOID *	Base1,
		IN UINTN	Size1,
		IN VOID *	Base2,
		IN UINTN	Size2
	)

Returns if 2 memory blocks are overlapped.

Parameters

Base1	Base address of 1st memory block.
Size1	Size of 1st memory block.
Base2	Base address of 2nd memory block.
Size2	Size of 2nd memory block.

Return values

TRUE	2 memory blocks are overlapped.
FALSE	2 memory blocks are not overlapped.

Definition at line 37 of file SafeString.c.

◆ InternalSafeStringNoAsciiStrOverlap()

BOOLEAN InternalSafeStringNoAsciiStrOverlap	(	IN CHAR8 *	Str1,
		IN UINTN	Size1,
		IN CHAR8 *	Str2,
		IN UINTN	Size2
	)

Returns if 2 Ascii strings are not overlapped.

Parameters

Str1	Start address of 1st Ascii string.
Size1	The number of char in 1st Ascii string, including terminating null char.
Str2	Start address of 2nd Ascii string.
Size2	The number of char in 2nd Ascii string, including terminating null char.

Return values

TRUE	2 Ascii strings are NOT overlapped.
FALSE	2 Ascii strings are overlapped.

Definition at line 91 of file SafeString.c.

◆ InternalSafeStringNoStrOverlap()

BOOLEAN InternalSafeStringNoStrOverlap	(	IN CHAR16 *	Str1,
		IN UINTN	Size1,
		IN CHAR16 *	Str2,
		IN UINTN	Size2
	)

Returns if 2 Unicode strings are not overlapped.

Parameters

Str1	Start address of 1st Unicode string.
Size1	The number of char in 1st Unicode string, including terminating null char.
Str2	Start address of 2nd Unicode string.
Size2	The number of char in 2nd Unicode string, including terminating null char.

Return values

TRUE	2 Unicode strings are NOT overlapped.
FALSE	2 Unicode strings are overlapped.

Definition at line 67 of file SafeString.c.

◆ StrCatS()

RETURN_STATUS EFIAPI StrCatS	(	IN OUT CHAR16 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR16 *	Source
	)

Appends a copy of the string pointed to by Source (including the terminating null char) to the end of the string pointed to by Destination.

This function is similar as strcat_s defined in C11.

If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.
Source	A pointer to a Null-terminated Unicode string.

Return values

RETURN_SUCCESS	String is appended.
RETURN_BAD_BUFFER_SIZE	If DestMax is NOT greater than StrLen(Destination).
RETURN_BUFFER_TOO_SMALL	If (DestMax - StrLen(Destination)) is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 405 of file SafeString.c.

◆ StrCpyS()

RETURN_STATUS EFIAPI StrCpyS	(	OUT CHAR16 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR16 *	Source
	)

Copies the string pointed to by Source (including the terminating null char) to the array pointed to by Destination.

This function is similar as strcpy_s defined in C11.

If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.
Source	A pointer to a Null-terminated Unicode string.

Return values

RETURN_SUCCESS	String is copied.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 226 of file SafeString.c.

◆ StrDecimalToUint64S()

RETURN_STATUS EFIAPI StrDecimalToUint64S	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT UINT64 *	Data
	)

Convert a Null-terminated Unicode decimal string to a value of type UINT64.

This function outputs a value of type UINT64 by interpreting the contents of the Unicode string specified by String as a decimal number. The format of the input Unicode string String is:

            [spaces] [decimal digits].

The valid decimal digit character is in the range [0-9]. The function will ignore the pad space, which includes spaces or tab characters, before [decimal digits]. The running zero in the beginning of [decimal digits] will be ignored. Then, the function stops at the first character that is a not a valid decimal character or a Null-terminator, whichever one comes first.

If String is not aligned in a 16-bit boundary, then ASSERT().

If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then MAX_UINT64 is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid decimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumUnicodeStringLength is not zero, and String contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINT64.

Definition at line 743 of file SafeString.c.

◆ StrDecimalToUintnS()

RETURN_STATUS EFIAPI StrDecimalToUintnS	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT UINTN *	Data
	)

Convert a Null-terminated Unicode decimal string to a value of type UINTN.

This function outputs a value of type UINTN by interpreting the contents of the Unicode string specified by String as a decimal number. The format of the input Unicode string String is:

            [spaces] [decimal digits].

The valid decimal digit character is in the range [0-9]. The function will ignore the pad space, which includes spaces or tab characters, before [decimal digits]. The running zero in the beginning of [decimal digits] will be ignored. Then, the function stops at the first character that is a not a valid decimal character or a Null-terminator, whichever one comes first.

If String is not aligned in a 16-bit boundary, then ASSERT().

If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then MAX_UINTN is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid decimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumUnicodeStringLength is not zero, and String contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINTN.

Definition at line 631 of file SafeString.c.

◆ StrHexToBytes()

RETURN_STATUS EFIAPI StrHexToBytes	(	IN CONST CHAR16 *	String,
		IN UINTN	Length,
		OUT UINT8 *	Buffer,
		IN UINTN	MaxBufferSize
	)

Convert a Null-terminated Unicode hexadecimal string to a byte array.

This function outputs a byte array by interpreting the contents of the Unicode string specified by String in hexadecimal format. The format of the input Unicode string String is:

            [XX]*

X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F]. The function decodes every two hexadecimal digit characters as one byte. The decoding stops after Length of characters and outputs Buffer containing (Length / 2) bytes.

If String is not aligned in a 16-bit boundary, then ASSERT().

Parameters

String	Pointer to a Null-terminated Unicode string.
Length	The number of Unicode characters to decode.
Buffer	Pointer to the converted bytes array.
MaxBufferSize	The maximum size of Buffer.

Return values

RETURN_SUCCESS	Buffer is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If Length is not multiple of 2. If PcdMaximumUnicodeStringLength is not zero, and Length is greater than PcdMaximumUnicodeStringLength.
RETURN_UNSUPPORTED	If Length of characters from String contain a character that is not valid hexadecimal digit characters, or a Null-terminator.
RETURN_BUFFER_TOO_SMALL	If MaxBufferSize is less than (Length / 2).

Definition at line 1615 of file SafeString.c.

◆ StrHexToUint64S()

RETURN_STATUS EFIAPI StrHexToUint64S	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT UINT64 *	Data
	)

Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.

This function outputs a value of type UINT64 by interpreting the contents of the Unicode string specified by String as a hexadecimal number. The format of the input Unicode string String is:

            [spaces][zeros][x][hexadecimal digits].

The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" appears in the input string, it must be prefixed with at least one 0. The function will ignore the pad space, which includes spaces or tab characters, before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal digit. Then, the function stops at the first character that is a not a valid hexadecimal character or NULL, whichever one comes first.

If String is not aligned in a 16-bit boundary, then ASSERT().

If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then MAX_UINT64 is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid hexadecimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumUnicodeStringLength is not zero, and String contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINT64.

Definition at line 994 of file SafeString.c.

◆ StrHexToUintnS()

RETURN_STATUS EFIAPI StrHexToUintnS	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT UINTN *	Data
	)

Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.

This function outputs a value of type UINTN by interpreting the contents of the Unicode string specified by String as a hexadecimal number. The format of the input Unicode string String is:

            [spaces][zeros][x][hexadecimal digits].

The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" appears in the input string, it must be prefixed with at least one 0. The function will ignore the pad space, which includes spaces or tab characters, before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal digit. Then, the function stops at the first character that is a not a valid hexadecimal character or NULL, whichever one comes first.

If String is not aligned in a 16-bit boundary, then ASSERT().

If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then MAX_UINTN is stored at the location pointed to by Data.

If EndPointer is not NULL, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. If String has no valid hexadecimal digits right after the optional pad spaces, the value of String is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Data	Pointer to the converted value.

Return values

RETURN_SUCCESS	Value is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL. If PcdMaximumUnicodeStringLength is not zero, and String contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator.
RETURN_UNSUPPORTED	If the number represented by String exceeds the range defined by UINTN.

Definition at line 860 of file SafeString.c.

◆ StrnCatS()

RETURN_STATUS EFIAPI StrnCatS	(	IN OUT CHAR16 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR16 *	Source,
		IN UINTN	Length
	)

Appends not more than Length successive char from the string pointed to by Source to the end of the string pointed to by Destination. If no null char is copied from Source, then Destination[StrLen(Destination) + Length] is always set to null.

This function is similar as strncat_s defined in C11.

If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.
Source	A pointer to a Null-terminated Unicode string.
Length	The maximum number of Unicode characters to copy.

Return values

RETURN_SUCCESS	String is appended.
RETURN_BAD_BUFFER_SIZE	If DestMax is NOT greater than StrLen(Destination).
RETURN_BUFFER_TOO_SMALL	If (DestMax - StrLen(Destination)) is NOT greater than MIN(StrLen(Source), Length).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 507 of file SafeString.c.

◆ StrnCpyS()

RETURN_STATUS EFIAPI StrnCpyS	(	OUT CHAR16 *	Destination,
		IN UINTN	DestMax,
		IN CONST CHAR16 *	Source,
		IN UINTN	Length
	)

Copies not more than Length successive char from the string pointed to by Source to the array pointed to by Destination. If no null char is copied from Source, then Destination[Length] is always set to null.

This function is similar as strncpy_s defined in C11.

If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT(). If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Destination	A pointer to a Null-terminated Unicode string.
DestMax	The maximum number of Destination Unicode char, including terminating null char.
Source	A pointer to a Null-terminated Unicode string.
Length	The maximum number of Unicode characters to copy.

Return values

RETURN_SUCCESS	String is copied.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than MIN(StrLen(Source), Length).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 310 of file SafeString.c.

◆ StrnLenS()

UINTN EFIAPI StrnLenS	(	IN CONST CHAR16 *	String,
		IN UINTN	MaxSize
	)

Returns the length of a Null-terminated Unicode string.

This function is similar as strlen_s defined in C11.

If String is not aligned on a 16-bit boundary, then ASSERT().

Parameters

String	A pointer to a Null-terminated Unicode string.
MaxSize	The maximum number of Destination Unicode char, including terminating null char.

Return values

0	If String is NULL.
MaxSize	If there is no null character in the first MaxSize characters of String.

Returns: The number of characters that percede the terminating null character.

Definition at line 119 of file SafeString.c.

◆ StrnSizeS()

UINTN EFIAPI StrnSizeS	(	IN CONST CHAR16 *	String,
		IN UINTN	MaxSize
	)

Returns the size of a Null-terminated Unicode string in bytes, including the Null terminator.

This function returns the size of the Null-terminated Unicode string specified by String in bytes, including the Null terminator.

If String is not aligned on a 16-bit boundary, then ASSERT().

Parameters

String	A pointer to a Null-terminated Unicode string.
MaxSize	The maximum number of Destination Unicode char, including the Null terminator.

Return values

0	If String is NULL.
(sizeof	(CHAR16) * (MaxSize + 1)) If there is no Null terminator in the first MaxSize characters of String.

Returns: The size of the Null-terminated Unicode string in bytes, including the Null terminator.

Definition at line 176 of file SafeString.c.

◆ StrToGuid()

RETURN_STATUS EFIAPI StrToGuid	(	IN CONST CHAR16 *	String,
		OUT GUID *	Guid
	)

Convert a Null-terminated Unicode GUID string to a value of type EFI_GUID.

This function outputs a GUID value by interpreting the contents of the Unicode string specified by String. The format of the input Unicode string String consists of 36 characters, as follows:

            aabbccdd-eeff-gghh-iijj-kkllmmnnoopp

The pairs aa - pp are two characters in the range [0-9], [a-f] and [A-F], with each pair representing a single byte hexadecimal value.

The mapping between String and the EFI_GUID structure is as follows: aa Data1[24:31] bb Data1[16:23] cc Data1[8:15] dd Data1[0:7] ee Data2[8:15] ff Data2[0:7] gg Data3[8:15] hh Data3[0:7] ii Data4[0:7] jj Data4[8:15] kk Data4[16:23] ll Data4[24:31] mm Data4[32:39] nn Data4[40:47] oo Data4[48:55] pp Data4[56:63]

If String is not aligned in a 16-bit boundary, then ASSERT().

Parameters

String	Pointer to a Null-terminated Unicode string.
Guid	Pointer to the converted GUID.

Return values

RETURN_SUCCESS	Guid is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If String is not as the above format.

Definition at line 1500 of file SafeString.c.

◆ StrToIpv4Address()

RETURN_STATUS EFIAPI StrToIpv4Address	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT IPv4_ADDRESS *	Address,
		OUT UINT8 *PrefixLength	OPTIONAL
	)

Convert a Null-terminated Unicode string to IPv4 address and prefix length.

This function outputs a value of type IPv4_ADDRESS and may output a value of type UINT8 by interpreting the contents of the Unicode string specified by String. The format of the input Unicode string String is as follows:

            D.D.D.D[/P]

D and P are decimal digit characters in the range [0-9]. The running zero in the beginning of D and P will be ignored. /P is optional.

When /P is not in the String, the function stops at the first character that is not a valid decimal digit character after four D's are converted.

When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted.

If String is not aligned in a 16-bit boundary, then ASSERT().

If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Address	Pointer to the converted IPv4 address.
PrefixLength	Pointer to the converted IPv4 address prefix length. MAX_UINT8 is returned when /P is not in the String.

Return values

RETURN_SUCCESS	Address is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If String is not in the correct format. If any decimal number converted from D exceeds 255. If the decimal number converted from P exceeds 32.

Definition at line 1351 of file SafeString.c.

◆ StrToIpv6Address()

RETURN_STATUS EFIAPI StrToIpv6Address	(	IN CONST CHAR16 *	String,
		OUT CHAR16 **EndPointer	OPTIONAL,
		OUT IPv6_ADDRESS *	Address,
		OUT UINT8 *PrefixLength	OPTIONAL
	)

Convert a Null-terminated Unicode string to IPv6 address and prefix length.

This function outputs a value of type IPv6_ADDRESS and may output a value of type UINT8 by interpreting the contents of the Unicode string specified by String. The format of the input Unicode string String is as follows:

            X:X:X:X:X:X:X:X[/P]

X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low memory address and high byte is stored in high memory address. P contains decimal digit characters in the range [0-9]. The running zero in the beginning of P will be ignored. /P is optional.

When /P is not in the String, the function stops at the first character that is not a valid hexadecimal digit character after eight X's are converted.

When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted.

"::" can be used to compress one or more groups of X when X contains only 0. The "::" can only appear once in the String.

If String is not aligned in a 16-bit boundary, then ASSERT().

If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer.

Parameters

String	Pointer to a Null-terminated Unicode string.
EndPointer	Pointer to character that stops scan.
Address	Pointer to the converted IPv6 address.
PrefixLength	Pointer to the converted IPv6 address prefix length. MAX_UINT8 is returned when /P is not in the String.

Return values

RETURN_SUCCESS	Address is translated from String.
RETURN_INVALID_PARAMETER	If String is NULL. If Data is NULL.
RETURN_UNSUPPORTED	If X contains more than four hexadecimal digit characters. If String contains "::" and number of X is not less than 8. If P starts with character that is not a valid decimal digit character. If the decimal number converted from P exceeds 128.

Definition at line 1129 of file SafeString.c.

◆ UnicodeStrnToAsciiStrS()

RETURN_STATUS EFIAPI UnicodeStrnToAsciiStrS	(	IN CONST CHAR16 *	Source,
		IN UINTN	Length,
		OUT CHAR8 *	Destination,
		IN UINTN	DestMax,
		OUT UINTN *	DestinationLength
	)

Convert not more than Length successive characters from a Null-terminated Unicode string to a Null-terminated Ascii string. If no null char is copied from Source, then Destination[Length] is always set to null.

This function converts not more than Length successive characters from the Unicode string Source to the Ascii string Destination by copying the lower 8 bits of each Unicode character. The function terminates the Ascii string Destination by appending a Null-terminator character at the end.

The caller is responsible to make sure Destination points to a buffer with size not smaller than ((MIN(StrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.

If any Unicode characters in Source contain non-zero value in the upper 8 bits, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then Destination and DestinationLength are unmodified.

Parameters

Source	The pointer to a Null-terminated Unicode string.
Length	The maximum number of Unicode characters to convert.
Destination	The pointer to a Null-terminated Ascii string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.
DestinationLength	The number of Unicode characters converted.

Return values

RETURN_SUCCESS	String is converted.
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If DestinationLength is NULL. If PcdMaximumAsciiStringLength is not zero, and Length or DestMax is greater than PcdMaximumAsciiStringLength. If PcdMaximumUnicodeStringLength is not zero, and Length or DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than MIN(StrLen(Source), Length).
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 2757 of file SafeString.c.

◆ UnicodeStrToAsciiStrS()

RETURN_STATUS EFIAPI UnicodeStrToAsciiStrS	(	IN CONST CHAR16 *	Source,
		OUT CHAR8 *	Destination,
		IN UINTN	DestMax
	)

Convert a Null-terminated Unicode string to a Null-terminated ASCII string.

This function is similar to AsciiStrCpyS.

This function converts the content of the Unicode string Source to the ASCII string Destination by copying the lower 8 bits of each Unicode character. The function terminates the ASCII string Destination by appending a Null-terminator character at the end.

The caller is responsible to make sure Destination points to a buffer with size equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.

If any Unicode characters in Source contain non-zero value in the upper 8 bits, then ASSERT().

If Source is not aligned on a 16-bit boundary, then ASSERT().

If an error is returned, then the Destination is unmodified.

Parameters

Source	The pointer to a Null-terminated Unicode string.
Destination	The pointer to a Null-terminated ASCII string.
DestMax	The maximum number of Destination Ascii char, including terminating null char.

Return values

RETURN_SUCCESS	String is converted.
RETURN_BUFFER_TOO_SMALL	If DestMax is NOT greater than StrLen(Source).
RETURN_INVALID_PARAMETER	If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, and DestMax is greater than PcdMaximumAsciiStringLength. If PcdMaximumUnicodeStringLength is not zero, and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0.
RETURN_ACCESS_DENIED	If Source and Destination overlap.

Definition at line 2650 of file SafeString.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ASCII_RSIZE_MAX

◆ RSIZE_MAX

◆ SAFE_STRING_CONSTRAINT_CHECK

Function Documentation

◆ AsciiStrCatS()

◆ AsciiStrCpyS()

◆ AsciiStrDecimalToUint64S()

◆ AsciiStrDecimalToUintnS()

◆ AsciiStrHexToBytes()

◆ AsciiStrHexToUint64S()

◆ AsciiStrHexToUintnS()

◆ AsciiStrnCatS()

◆ AsciiStrnCpyS()

◆ AsciiStrnLenS()

◆ AsciiStrnSizeS()

◆ AsciiStrnToUnicodeStrS()

◆ AsciiStrToGuid()

◆ AsciiStrToIpv4Address()

◆ AsciiStrToIpv6Address()

◆ AsciiStrToUnicodeStrS()

◆ InternalSafeStringIsOverlap()

◆ InternalSafeStringNoAsciiStrOverlap()

◆ InternalSafeStringNoStrOverlap()

◆ StrCatS()

◆ StrCpyS()

◆ StrDecimalToUint64S()

◆ StrDecimalToUintnS()

◆ StrHexToBytes()

◆ StrHexToUint64S()

◆ StrHexToUintnS()

◆ StrnCatS()

◆ StrnCpyS()

◆ StrnLenS()

◆ StrnSizeS()

◆ StrToGuid()

◆ StrToIpv4Address()

◆ StrToIpv6Address()

◆ UnicodeStrnToAsciiStrS()

◆ UnicodeStrToAsciiStrS()