/** @file\r
Provides string functions, linked list functions, math functions, synchronization\r
- functions, and CPU architecture-specific functions.\r
+ functions, file path functions, and CPU architecture-specific functions.\r
\r
-Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>\r
Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
// String Services\r
//\r
\r
+\r
/**\r
+ Returns the length of a Null-terminated Unicode string.\r
+\r
+ If String is not aligned on a 16-bit boundary, then ASSERT().\r
+\r
+ @param String A pointer to a Null-terminated Unicode string.\r
+ @param MaxSize The maximum number of Destination Unicode\r
+ char, including terminating null char.\r
+\r
+ @retval 0 If String is NULL.\r
+ @retval MaxSize If there is no null character in the first MaxSize characters of String.\r
+ @return The number of characters that percede the terminating null character.\r
+\r
+**/\r
+UINTN\r
+EFIAPI\r
+StrnLenS (\r
+ IN CONST CHAR16 *String,\r
+ IN UINTN MaxSize\r
+ );\r
+\r
+/**\r
+ Copies the string pointed to by Source (including the terminating null char)\r
+ to the array pointed to by Destination.\r
+\r
+ If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
+ If Source is not aligned on a 16-bit boundary, then ASSERT().\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Unicode string.\r
+ @param DestMax The maximum number of Destination Unicode\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Unicode string.\r
+\r
+ @retval RETURN_SUCCESS String is copied.\r
+ @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumUnicodeStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumUnicodeStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+StrCpyS (\r
+ OUT CHAR16 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR16 *Source\r
+ );\r
+\r
+/**\r
+ Copies not more than Length successive char from the string pointed to by\r
+ Source to the array pointed to by Destination. If no null char is copied from\r
+ Source, then Destination[Length] is always set to null.\r
+\r
+ If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().\r
+ If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Unicode string.\r
+ @param DestMax The maximum number of Destination Unicode\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Unicode string.\r
+ @param Length The maximum number of Unicode characters to copy.\r
+\r
+ @retval RETURN_SUCCESS String is copied.\r
+ @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than \r
+ MIN(StrLen(Source), Length).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumUnicodeStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumUnicodeStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+StrnCpyS (\r
+ OUT CHAR16 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR16 *Source,\r
+ IN UINTN Length\r
+ );\r
+\r
+/**\r
+ Appends a copy of the string pointed to by Source (including the terminating\r
+ null char) to the end of the string pointed to by Destination.\r
+\r
+ If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
+ If Source is not aligned on a 16-bit boundary, then ASSERT().\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Unicode string.\r
+ @param DestMax The maximum number of Destination Unicode\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Unicode string.\r
+\r
+ @retval RETURN_SUCCESS String is appended.\r
+ @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than \r
+ StrLen(Destination).\r
+ @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
+ greater than StrLen(Source).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumUnicodeStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumUnicodeStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+StrCatS (\r
+ IN OUT CHAR16 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR16 *Source\r
+ );\r
+\r
+/**\r
+ Appends not more than Length successive char from the string pointed to by\r
+ Source to the end of the string pointed to by Destination. If no null char is\r
+ copied from Source, then Destination[StrLen(Destination) + Length] is always\r
+ set to null.\r
+\r
+ If Destination is not aligned on a 16-bit boundary, then ASSERT().\r
+ If Source is not aligned on a 16-bit boundary, then ASSERT().\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Unicode string.\r
+ @param DestMax The maximum number of Destination Unicode\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Unicode string.\r
+ @param Length The maximum number of Unicode characters to copy.\r
+\r
+ @retval RETURN_SUCCESS String is appended.\r
+ @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
+ StrLen(Destination).\r
+ @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
+ greater than MIN(StrLen(Source), Length).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumUnicodeStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumUnicodeStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+StrnCatS (\r
+ IN OUT CHAR16 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR16 *Source,\r
+ IN UINTN Length\r
+ );\r
+\r
+/**\r
+ Returns the length of a Null-terminated Ascii string.\r
+\r
+ @param String A pointer to a Null-terminated Ascii string.\r
+ @param MaxSize The maximum number of Destination Ascii\r
+ char, including terminating null char.\r
+\r
+ @retval 0 If String is NULL.\r
+ @retval MaxSize If there is no null character in the first MaxSize characters of String.\r
+ @return The number of characters that percede the terminating null character.\r
+\r
+**/\r
+UINTN\r
+EFIAPI\r
+AsciiStrnLenS (\r
+ IN CONST CHAR8 *String,\r
+ IN UINTN MaxSize\r
+ );\r
+\r
+/**\r
+ Copies the string pointed to by Source (including the terminating null char)\r
+ to the array pointed to by Destination.\r
+\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Ascii string.\r
+ @param DestMax The maximum number of Destination Ascii\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Ascii string.\r
+\r
+ @retval RETURN_SUCCESS String is copied.\r
+ @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumAsciiStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumAsciiStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+AsciiStrCpyS (\r
+ OUT CHAR8 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR8 *Source\r
+ );\r
+\r
+/**\r
+ Copies not more than Length successive char from the string pointed to by\r
+ Source to the array pointed to by Destination. If no null char is copied from\r
+ Source, then Destination[Length] is always set to null.\r
+\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Ascii string.\r
+ @param DestMax The maximum number of Destination Ascii\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Ascii string.\r
+ @param Length The maximum number of Ascii characters to copy.\r
+\r
+ @retval RETURN_SUCCESS String is copied.\r
+ @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than \r
+ MIN(StrLen(Source), Length).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumAsciiStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumAsciiStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+AsciiStrnCpyS (\r
+ OUT CHAR8 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR8 *Source,\r
+ IN UINTN Length\r
+ );\r
+\r
+/**\r
+ Appends a copy of the string pointed to by Source (including the terminating\r
+ null char) to the end of the string pointed to by Destination.\r
+\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Ascii string.\r
+ @param DestMax The maximum number of Destination Ascii\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Ascii string.\r
+\r
+ @retval RETURN_SUCCESS String is appended.\r
+ @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than \r
+ StrLen(Destination).\r
+ @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
+ greater than StrLen(Source).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumAsciiStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumAsciiStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+AsciiStrCatS (\r
+ IN OUT CHAR8 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR8 *Source\r
+ );\r
+\r
+/**\r
+ Appends not more than Length successive char from the string pointed to by\r
+ Source to the end of the string pointed to by Destination. If no null char is\r
+ copied from Source, then Destination[StrLen(Destination) + Length] is always\r
+ set to null.\r
+\r
+ If an error would be returned, then the function will also ASSERT().\r
+\r
+ @param Destination A pointer to a Null-terminated Ascii string.\r
+ @param DestMax The maximum number of Destination Ascii\r
+ char, including terminating null char.\r
+ @param Source A pointer to a Null-terminated Ascii string.\r
+ @param Length The maximum number of Ascii characters to copy.\r
+\r
+ @retval RETURN_SUCCESS String is appended.\r
+ @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than\r
+ StrLen(Destination).\r
+ @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT\r
+ greater than MIN(StrLen(Source), Length).\r
+ @retval RETURN_INVALID_PARAMETER If Destination is NULL.\r
+ If Source is NULL.\r
+ If PcdMaximumAsciiStringLength is not zero,\r
+ and DestMax is greater than \r
+ PcdMaximumAsciiStringLength.\r
+ If DestMax is 0.\r
+ @retval RETURN_ACCESS_DENIED If Source and Destination overlap.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+AsciiStrnCatS (\r
+ IN OUT CHAR8 *Destination,\r
+ IN UINTN DestMax,\r
+ IN CONST CHAR8 *Source,\r
+ IN UINTN Length\r
+ );\r
+\r
+\r
+#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
+\r
+/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Copies one Null-terminated Unicode string to another Null-terminated Unicode\r
string and returns the new Unicode string.\r
\r
\r
\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Copies up to a specified length from one Null-terminated Unicode string to \r
another Null-terminated Unicode string and returns the new Unicode string.\r
\r
IN CONST CHAR16 *Source,\r
IN UINTN Length\r
);\r
-\r
+#endif\r
\r
/**\r
Returns the length of a Null-terminated Unicode string.\r
);\r
\r
\r
+#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
+\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Concatenates one Null-terminated Unicode string to another Null-terminated\r
Unicode string, and returns the concatenated Unicode string.\r
\r
\r
\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Concatenates up to a specified length one Null-terminated Unicode to the end \r
of another Null-terminated Unicode string, and returns the concatenated \r
Unicode string.\r
IN CONST CHAR16 *Source,\r
IN UINTN Length\r
);\r
+#endif\r
\r
/**\r
Returns the first occurrence of a Null-terminated Unicode sub-string\r
);\r
\r
\r
+#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
+\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Copies one Null-terminated ASCII string to another Null-terminated ASCII\r
string and returns the new ASCII string.\r
\r
\r
\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Copies up to a specified length one Null-terminated ASCII string to another \r
Null-terminated ASCII string and returns the new ASCII string.\r
\r
IN CONST CHAR8 *Source,\r
IN UINTN Length\r
);\r
-\r
+#endif\r
\r
/**\r
Returns the length of a Null-terminated ASCII string.\r
);\r
\r
\r
+#ifndef DISABLE_NEW_DEPRECATED_INTERFACES\r
+\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Concatenates one Null-terminated ASCII string to another Null-terminated\r
ASCII string, and returns the concatenated ASCII string.\r
\r
\r
\r
/**\r
+ [ATTENTION] This function is deprecated for security reason.\r
+\r
Concatenates up to a specified length one Null-terminated ASCII string to \r
the end of another Null-terminated ASCII string, and returns the \r
concatenated ASCII string.\r
IN CONST CHAR8 *Source,\r
IN UINTN Length\r
);\r
-\r
+#endif\r
\r
/**\r
Returns the first occurrence of a Null-terminated ASCII sub-string\r
IN UINT8 Value\r
);\r
\r
+//\r
+// File Path Manipulation Functions\r
+//\r
+\r
+/**\r
+ Removes the last directory or file entry in a path by changing the last\r
+ L'\' to a CHAR_NULL.\r
+\r
+ @param[in, out] Path The pointer to the path to modify.\r
+\r
+ @retval FALSE Nothing was found to remove.\r
+ @retval TRUE A directory or file was removed.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+PathRemoveLastItem(\r
+ IN OUT CHAR16 *Path\r
+ );\r
+\r
+/**\r
+ Function to clean up paths.\r
+ - Single periods in the path are removed.\r
+ - Double periods in the path are removed along with a single parent directory.\r
+ - Forward slashes L'/' are converted to backward slashes L'\'.\r
+\r
+ This will be done inline and the existing buffer may be larger than required\r
+ upon completion.\r
+\r
+ @param[in] Path The pointer to the string containing the path.\r
+\r
+ @return Returns Path, otherwise returns NULL to indicate that an error has occured.\r
+**/\r
+CHAR16*\r
+EFIAPI\r
+PathCleanUpDirectories(\r
+ IN CHAR16 *Path\r
+ );\r
\r
//\r
// Linked List Functions and Macros\r
IN OUT THUNK_CONTEXT *ThunkContext\r
);\r
\r
+/**\r
+ Generates a 16-bit random number through RDRAND instruction.\r
+\r
+ if Rand is NULL, then ASSERT().\r
+\r
+ @param[out] Rand Buffer pointer to store the random result.\r
+\r
+ @retval TRUE RDRAND call was successful.\r
+ @retval FALSE Failed attempts to call RDRAND.\r
+\r
+ **/\r
+BOOLEAN\r
+EFIAPI\r
+AsmRdRand16 (\r
+ OUT UINT16 *Rand\r
+ );\r
+\r
+/**\r
+ Generates a 32-bit random number through RDRAND instruction.\r
+\r
+ if Rand is NULL, then ASSERT().\r
+\r
+ @param[out] Rand Buffer pointer to store the random result.\r
+\r
+ @retval TRUE RDRAND call was successful.\r
+ @retval FALSE Failed attempts to call RDRAND.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+AsmRdRand32 (\r
+ OUT UINT32 *Rand\r
+ );\r
+\r
+/**\r
+ Generates a 64-bit random number through RDRAND instruction.\r
+\r
+ if Rand is NULL, then ASSERT().\r
+\r
+ @param[out] Rand Buffer pointer to store the random result.\r
+\r
+ @retval TRUE RDRAND call was successful.\r
+ @retval FALSE Failed attempts to call RDRAND.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+AsmRdRand64 (\r
+ OUT UINT64 *Rand\r
+ );\r
+\r
#endif\r
#endif\r
\r