From 328f84b1565165f35ea7755fb85b09fbf335c2cb Mon Sep 17 00:00:00 2001 From: Jiewen Yao Date: Sun, 22 May 2016 21:01:37 +0800 Subject: [PATCH] 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 Cc: Liming Gao Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Jiewen Yao Reviewed-by: Liming Gao --- MdePkg/Include/Library/BaseLib.h | 36 +++++++++++++++++++++++++++++ MdePkg/Library/BaseLib/SafeString.c | 36 +++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) 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. -- 2.39.2