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

Add more comments:
1) EDKII version safe string function is similar as the one C11.
2) If error is returned, the Destination is unmodified.

Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Jiewen Yao <jiewen.yao@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index c41fa783df2bbe2b05fa06fcc6794937ae1c0582..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
 /**\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
   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
   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 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
   @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
   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 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
   @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
   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 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
   @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
   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 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
   @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
 /**\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
   @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
   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 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
   @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
   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 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
   @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
   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 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
   @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
   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 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
   @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

diff --git a/MdePkg/Library/BaseLib/SafeString.c b/MdePkg/Library/BaseLib/SafeString.c
index b0e1ce72e2986349f85e1ea8cb7af2cb7d6e9d6a..34d3efeafc94dabc4faaa3542a4acaf8db20a69e 100644 (file)
--- a/MdePkg/Library/BaseLib/SafeString.c
+++ b/MdePkg/Library/BaseLib/SafeString.c
@@ -106,6 +106,8 @@ InternalSafeStringNoAsciiStrOverlap (
 /**\r
   Returns the length of a Null-terminated Unicode string.\r
 \r
 /**\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
   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


@@ -151,10 +153,14 @@ StrnLenS (
   Copies the string pointed to by Source (including the terminating null char)\r
   to the array pointed to by Destination.\r
 \r
   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 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
   @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


@@ -229,10 +235,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
   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 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
   @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


@@ -318,10 +328,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
   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 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
   @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


@@ -415,10 +429,14 @@ StrCatS (
   copied from Source, then Destination[StrLen(Destination) + Length] is always\r
   set to null.\r
 \r
   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 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
   @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


@@ -520,6 +538,8 @@ StrnCatS (
 /**\r
   Returns the length of a Null-terminated Ascii string.\r
 \r
 /**\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
   @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


@@ -561,8 +581,12 @@ AsciiStrnLenS (
   Copies the string pointed to by Source (including the terminating null char)\r
   to the array pointed to by Destination.\r
 \r
   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 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
   @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


@@ -634,8 +658,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
   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 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
   @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


@@ -718,8 +746,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
   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 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
   @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


@@ -810,8 +842,12 @@ AsciiStrCatS (
   copied from Source, then Destination[StrLen(Destination) + Length] is always\r
   set to null.\r
 \r
   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 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
   @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