From: Jiewen Yao Date: Sun, 22 May 2016 13:01:37 +0000 (+0800) Subject: MdePkg/BaseLib: Add more comments for safe string functions. X-Git-Tag: edk2-stable201903~6965 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=328f84b1565165f35ea7755fb85b09fbf335c2cb;ds=sidebyside 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 --- 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.