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>

2 files changed, 72 insertions, 0 deletions

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index c41fa783df..6f6bd85157 100644
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -187,6 +187,8 @@ typedef struct {
 /**

   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().

 

   @param  String   A pointer to a Null-terminated Unicode string.

@@ -209,10 +211,14 @@ StrnLenS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -241,10 +247,14 @@ StrCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -275,10 +285,14 @@ StrnCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -311,10 +325,14 @@ StrCatS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -346,6 +364,8 @@ StrnCatS (
 /**

   Returns the length of a Null-terminated Ascii string.

 

+  This function is similar as strlen_s defined in C11.

+

   @param  String   A pointer to a Null-terminated Ascii string.

   @param  MaxSize  The maximum number of Destination Ascii

                    char, including terminating null char.

@@ -366,8 +386,12 @@ AsciiStrnLenS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -396,8 +420,12 @@ AsciiStrCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -428,8 +456,12 @@ AsciiStrnCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -462,8 +494,12 @@ AsciiStrCatS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

diff --git a/MdePkg/Library/BaseLib/SafeString.c b/MdePkg/Library/BaseLib/SafeString.c
index b0e1ce72e2..34d3efeafc 100644
--- a/MdePkg/Library/BaseLib/SafeString.c
+++ b/MdePkg/Library/BaseLib/SafeString.c
@@ -106,6 +106,8 @@ InternalSafeStringNoAsciiStrOverlap (
 /**

   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().

 

   @param  String   A pointer to a Null-terminated Unicode string.

@@ -151,10 +153,14 @@ StrnLenS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -229,10 +235,14 @@ StrCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -318,10 +328,14 @@ StrnCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -415,10 +429,14 @@ StrCatS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Unicode string.

   @param  DestMax                  The maximum number of Destination Unicode

                                    char, including terminating null char.

@@ -520,6 +538,8 @@ StrnCatS (
 /**

   Returns the length of a Null-terminated Ascii string.

 

+  This function is similar as strlen_s defined in C11.

+

   @param  String   A pointer to a Null-terminated Ascii string.

   @param  MaxSize  The maximum number of Destination Ascii

                    char, including terminating null char.

@@ -561,8 +581,12 @@ AsciiStrnLenS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -634,8 +658,12 @@ AsciiStrCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -718,8 +746,12 @@ AsciiStrnCpyS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.

@@ -810,8 +842,12 @@ AsciiStrCatS (
   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 would be returned, then the function will also ASSERT().

 

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

+

   @param  Destination              A pointer to a Null-terminated Ascii string.

   @param  DestMax                  The maximum number of Destination Ascii

                                    char, including terminating null char.