MdePkg/BaseLib: Add more comments for safe string functions.

[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index 7e10804082d185c1c9bb02f5c6d02cca6952b31f..6f6bd8515766d146c9f6863f38f88074eef0330b 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -187,6 +187,8 @@ typedef struct {
 /**\r
   Returns the length of a Null-terminated Unicode string.\r
 \r
+  This function is similar as strlen_s defined in C11.\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
@@ -209,10 +211,14 @@ StrnLenS (
   Copies the string pointed to by Source (including the terminating null char)\r
   to the array pointed to by Destination.\r
 \r
+  This function is similar as strcpy_s defined in C11.\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
+  If an error is returned, then the Destination is unmodified.\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
@@ -241,10 +247,14 @@ StrCpyS (
   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
+  This function is similar as strncpy_s defined in C11.\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
+  If an error is returned, then the Destination is unmodified.\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
@@ -275,10 +285,14 @@ StrnCpyS (
   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
+  This function is similar as strcat_s defined in C11.\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
+  If an error is returned, then the Destination is unmodified.\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
@@ -311,10 +325,14 @@ StrCatS (
   copied from Source, then Destination[StrLen(Destination) + Length] is always\r
   set to null.\r
 \r
+  This function is similar as strncat_s defined in C11.\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
+  If an error is returned, then the Destination is unmodified.\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
@@ -346,6 +364,8 @@ StrnCatS (
 /**\r
   Returns the length of a Null-terminated Ascii string.\r
 \r
+  This function is similar as strlen_s defined in C11.\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
@@ -366,8 +386,12 @@ AsciiStrnLenS (
   Copies the string pointed to by Source (including the terminating null char)\r
   to the array pointed to by Destination.\r
 \r
+  This function is similar as strcpy_s defined in C11.\r
+\r
   If an error would be returned, then the function will also ASSERT().\r
 \r
+  If an error is returned, then the Destination is unmodified.\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
@@ -396,8 +420,12 @@ AsciiStrCpyS (
   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
+  This function is similar as strncpy_s defined in C11.\r
+\r
   If an error would be returned, then the function will also ASSERT().\r
 \r
+  If an error is returned, then the Destination is unmodified.\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
@@ -428,8 +456,12 @@ AsciiStrnCpyS (
   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
+  This function is similar as strcat_s defined in C11.\r
+\r
   If an error would be returned, then the function will also ASSERT().\r
 \r
+  If an error is returned, then the Destination is unmodified.\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
@@ -462,8 +494,12 @@ AsciiStrCatS (
   copied from Source, then Destination[StrLen(Destination) + Length] is always\r
   set to null.\r
 \r
+  This function is similar as strncat_s defined in C11.\r
+\r
   If an error would be returned, then the function will also ASSERT().\r
 \r
+  If an error is returned, then the Destination is unmodified.\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
@@ -7647,6 +7683,57 @@ AsmPrepareAndThunk16 (
   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