From nobody Sat Nov 2 16:25:52 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) client-ip=198.145.21.10; envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org; Authentication-Results: mx.zoho.com; spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) smtp.mailfrom=edk2-devel-bounces@lists.01.org; Return-Path: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 148661118301129.064953758840147; Wed, 8 Feb 2017 19:33:03 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id C393C82134; Wed, 8 Feb 2017 19:32:59 -0800 (PST) Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id CC68882134 for ; Wed, 8 Feb 2017 19:32:58 -0800 (PST) Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga104.jf.intel.com with ESMTP; 08 Feb 2017 19:32:58 -0800 Received: from shwdeopenpsi014.ccr.corp.intel.com ([10.239.9.13]) by orsmga004.jf.intel.com with ESMTP; 08 Feb 2017 19:32:57 -0800 X-Original-To: edk2-devel@lists.01.org X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.35,349,1484035200"; d="scan'208";a="56777749" From: Hao Wu To: edk2-devel@lists.01.org Date: Thu, 9 Feb 2017 11:32:41 +0800 Message-Id: <1486611161-37308-4-git-send-email-hao.a.wu@intel.com> X-Mailer: git-send-email 1.9.5.msysgit.0 In-Reply-To: <1486611161-37308-1-git-send-email-hao.a.wu@intel.com> References: <1486611161-37308-1-git-send-email-hao.a.wu@intel.com> Subject: [edk2] [PATCH v2 3/3] MdeModulePkg: Refine the services comments in EFI_PRINT2_PROTOCOL X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Hao Wu , Michael Kinney , Jiewen Yao , Liming Gao MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" For the following 8 services in EFI_PRINT2_PROTOCOL: UNICODE_BS_PRINT UNICODE_S_PRINT UNICODE_BS_PRINT_ASCII_FORMAT UNICODE_S_PRINT_ASCII_FORMAT ASCII_BS_PRINT ASCII_S_PRINT ASCII_BS_PRINT_UNICODE_FORMAT ASCII_S_PRINT_UNICODE_FORMAT They will ASSERT when: 1) The input parameter 'StartOfBuffer' is NULL if 'BufferSize' indicates at least 1 Ascii/Unicode character can be held. 2) The input parameter 'FormatString' is NULL if 'BufferSize' indicates at least 1 Ascii/Unicode character can be held. 3) The input parameter 'FormatString' contains more than PcdMaximum[Ascii|Unicode]StringLength Ascii/Unicode characters. 4) The produced string contains more than PcdMaximum[Ascii|Unicode]StringLength Ascii/Unicode characters. This commits removes the ASSERT case 4) and add the following new ASSERT case: 4) The input parameter 'BufferSize' is greater than (PcdMaximumAsciiStringLength * sizeof (CHAR8)) for Ascii format string or (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1) for Unicode format string. And for those ASSERT cases, 0 will be returned by those services. Cc: Jiewen Yao Cc: Liming Gao Cc: Michael Kinney Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Hao Wu --- MdeModulePkg/Include/Protocol/Print2.h | 361 +++++++++++--------- 1 file changed, 205 insertions(+), 156 deletions(-) diff --git a/MdeModulePkg/Include/Protocol/Print2.h b/MdeModulePkg/Include/= Protocol/Print2.h index 1c127d5..8cad6fd 100644 --- a/MdeModulePkg/Include/Protocol/Print2.h +++ b/MdeModulePkg/Include/Protocol/Print2.h @@ -3,7 +3,7 @@ This print protocol defines six basic print functions to=20 print the format unicode and ascii string. =20 -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.
+Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made availabl= e under=20 the terms and conditions of the BSD License that accompanies this distribu= tion. =20 The full text of the license may be found at @@ -26,35 +26,40 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITH= ER EXPRESS OR IMPLIED. typedef struct _EFI_PRINT2_PROTOCOL EFI_PRINT2_PROTOCOL; =20 /** - Produces a Null-terminated Unicode string in an output buffer, based on=20 - a Null-terminated Unicode format string and a BASE_LIST argument list - =20 - Produces a Null-terminated Unicode string in the output buffer=20 - specified by StartOfBuffer and BufferSize. =20 - The Unicode string is produced by parsing the format string specified by= FormatString. =20 - Arguments are pulled from the variable argument list specified by Marker. - Marker is constructed based on the contents of the format string. =20 - This function returns the number of Unicode characters in the produced o= utput buffer,=20 - not including the Null-terminator. - If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. + Produces a Null-terminated Unicode string in an output buffer based on + a Null-terminated Unicode format string and a BASE_LIST argument list. + + Produces a Null-terminated Unicode string in the output buffer specified= by StartOfBuffer + and BufferSize. + The Unicode string is produced by parsing the format string specified by= FormatString. + Arguments are pulled from the variable argument list specified by Marker= based on the + contents of the format string. + The number of Unicode characters in the produced output buffer is return= ed not including + the Null-terminator. =20 - If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary,= then ASSERT(). - If BufferSize > 1 and FormatString is NULL, then ASSERT(). - If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, = then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than=20 - PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminat= ed Unicode string - contains more than PcdMaximumUnicodeStringLength Unicode characters not = including the - Null-terminator, then ASSERT(). - - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). + If FormatString is not aligned on a 16-bit boundary, then ASSERT(). + + If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and BufferSize > + (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Al= so, the output + buffer is unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is r= eturned. + + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. + @param FormatString A Null-terminated Unicode format string. @param Marker BASE_LIST marker for the variable argument list. - =20 - @return The number of Unicode characters in the produced output buffer, = not including the + + @return The number of Unicode characters in the produced output buffer n= ot including the Null-terminator. =20 **/ @@ -68,34 +73,41 @@ UINTN ); =20 /** - Produces a Null-terminated Unicode string in an output buffer based on a= Null-terminated=20 + Produces a Null-terminated Unicode string in an output buffer based on a= Null-terminated Unicode format string and variable argument list. - =20 - Produces a Null-terminated Unicode string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + + This function is similar as snprintf_s defined in C11. + + Produces a Null-terminated Unicode string in the output buffer specified= by StartOfBuffer + and BufferSize. The Unicode string is produced by parsing the format string specified by= FormatString. Arguments are pulled from the variable argument list based on the conten= ts of the format string. - This function returns the number of Unicode characters in the produced o= utput buffer,=20 - not including the Null-terminator. - If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. + The number of Unicode characters in the produced output buffer is return= ed not including + the Null-terminator. + + If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). + If FormatString is not aligned on a 16-bit boundary, then ASSERT(). + + If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and BufferSize > + (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Al= so, the output + buffer is unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. =20 - If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary,= then ASSERT(). - If BufferSize > 1 and FormatString is NULL, then ASSERT(). - If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, = then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than=20 - PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminat= ed Unicode string - contains more than PcdMaximumUnicodeStringLength Unicode characters not = including the - Null-terminator, then ASSERT(). - - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is r= eturned. + + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. - @param ... Variable argument list whose contents are access= ed based on the=20 + @param FormatString A Null-terminated Unicode format string. + @param ... Variable argument list whose contents are access= ed based on the format string specified by FormatString. - =20 + @return The number of Unicode characters in the produced output buffer n= ot including the Null-terminator. =20 @@ -110,33 +122,38 @@ UINTN ); =20 /** - Produces a Null-terminated Unicode string in an output buffer, based on = a Null-terminated - ASCII format string and a BASE_LIST argument list - =20 - Produces a Null-terminated Unicode string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + Produces a Null-terminated Unicode string in an output buffer based on a= Null-terminated + ASCII format string and a BASE_LIST argument list. + + Produces a Null-terminated Unicode string in the output buffer specified= by StartOfBuffer + and BufferSize. The Unicode string is produced by parsing the format string specified by= FormatString. - Arguments are pulled from the variable argument list specified by Marker= based on the=20 + Arguments are pulled from the variable argument list specified by Marker= based on the contents of the format string. - This function returns the number of Unicode characters in the produced o= utput buffer,=20 - not including the Null-terminator. - If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. + The number of Unicode characters in the produced output buffer is return= ed not including + the Null-terminator. + + If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). =20 - If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary,= then ASSERT(). - If BufferSize > 1 and FormatString is NULL, then ASSERT(). + If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and BufferSize > + (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Al= so, the output + buffer is unmodified and 0 is returned. If PcdMaximumAsciiStringLength is not zero, and FormatString contains mo= re than - PcdMaximumAsciiStringLength ASCII characters not including the Null-term= inator, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminat= ed Unicode string - contains more than PcdMaximumUnicodeStringLength Unicode characters not = including the - Null-terminator, then ASSERT(). + PcdMaximumAsciiStringLength Ascii characters not including the Null-term= inator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated ASCII format string. + @param FormatString A Null-terminated ASCII format string. @param Marker BASE_LIST marker for the variable argument list. - =20 + @return The number of Unicode characters in the produced output buffer n= ot including the Null-terminator. =20 @@ -151,33 +168,41 @@ UINTN ); =20 /** - Produces a Null-terminated Unicode string in an output buffer based on a= Null-terminated=20 - ASCII format string and a variable argument list. - =20 - Produces a Null-terminated Unicode string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + Produces a Null-terminated Unicode string in an output buffer based on a= Null-terminated + ASCII format string and variable argument list. + + This function is similar as snprintf_s defined in C11. + + Produces a Null-terminated Unicode string in the output buffer specified= by StartOfBuffer + and BufferSize. The Unicode string is produced by parsing the format string specified by= FormatString. - Arguments are pulled from the variable argument list based on the conten= ts of the format string. - This function returns the number of Unicode characters in the produced o= utput buffer,=20 - not including the Null-terminator. - If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. + Arguments are pulled from the variable argument list based on the conten= ts of the + format string. + The number of Unicode characters in the produced output buffer is return= ed not including + the Null-terminator. =20 - If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary,= then ASSERT(). - If BufferSize > 1 and FormatString is NULL, then ASSERT(). + If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). + + If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and BufferSize > + (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Al= so, the output + buffer is unmodified and 0 is returned. If PcdMaximumAsciiStringLength is not zero, and FormatString contains mo= re than - PcdMaximumAsciiStringLength ASCII characters not including the Null-term= inator, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminat= ed Unicode string - contains more than PcdMaximumUnicodeStringLength Unicode characters not = including the - Null-terminator, then ASSERT(). + PcdMaximumAsciiStringLength Ascii characters not including the Null-term= inator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + If BufferSize is 0 or 1, then no output buffer is produced and 0 is retu= rned. + + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated ASCII format string. - @param ... Variable argument list whose contents are access= ed based on the=20 + @param FormatString A Null-terminated ASCII format string. + @param ... Variable argument list whose contents are access= ed based on the format string specified by FormatString. - =20 + @return The number of Unicode characters in the produced output buffer n= ot including the Null-terminator. =20 @@ -244,30 +269,34 @@ UINTN /** Produces a Null-terminated ASCII string in an output buffer based on a N= ull-terminated ASCII format string and a BASE_LIST argument list. - =20 - Produces a Null-terminated ASCII string in the output buffer=20 - pecified by StartOfBuffer and BufferSize. + + Produces a Null-terminated ASCII string in the output buffer specified b= y StartOfBuffer + and BufferSize. The ASCII string is produced by parsing the format string specified by F= ormatString. - Arguments are pulled from the variable argument list specified by Marker= based on=20 + Arguments are pulled from the variable argument list specified by Marker= based on the contents of the format string. - This function returns the number of ASCII characters in the output buffe= r,=20 - not including the Null-terminator. - If BufferSize is 0, then no output buffer is produced and 0 is returned. + The number of ASCII characters in the produced output buffer is returned= not including + the Null-terminator. =20 - If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is NULL, then ASSERT(). + If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumAsciiStringLength is not zero, and BufferSize > + (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the= output buffer + is unmodified and 0 is returned. If PcdMaximumAsciiStringLength is not zero, and FormatString contains mo= re than - PcdMaximumAsciiStringLength ASCII characters not including the Null-term= inator, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated= ASCII string - contains more than PcdMaximumAsciiStringLength ASCII characters not incl= uding the - Null-terminator, then ASSERT(). + PcdMaximumAsciiStringLength Ascii characters not including the Null-term= inator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0, then no output buffer is produced and 0 is returned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated ASCII format string. + @param FormatString A Null-terminated ASCII format string. @param Marker BASE_LIST marker for the variable argument list. - =20 + @return The number of ASCII characters in the produced output buffer not= including the Null-terminator. =20 @@ -283,31 +312,38 @@ UINTN =20 /** Produces a Null-terminated ASCII string in an output buffer based on a N= ull-terminated - ASCII format string and variable argument list. - =20 - Produces a Null-terminated ASCII string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + ASCII format string and variable argument list. + + This function is similar as snprintf_s defined in C11. + + Produces a Null-terminated ASCII string in the output buffer specified b= y StartOfBuffer + and BufferSize. The ASCII string is produced by parsing the format string specified by F= ormatString. - Arguments are pulled from the variable argument list based on the conten= ts of the format string. - This function returns the number of ASCII characters in the output buffe= r,=20 - not including the Null-terminator. - If BufferSize is 0, then no output buffer is produced and 0 is returned. + Arguments are pulled from the variable argument list based on the conten= ts of the + format string. + The number of ASCII characters in the produced output buffer is returned= not including + the Null-terminator. =20 - If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is NULL, then ASSERT(). + If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumAsciiStringLength is not zero, and BufferSize > + (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the= output buffer + is unmodified and 0 is returned. If PcdMaximumAsciiStringLength is not zero, and FormatString contains mo= re than - PcdMaximumAsciiStringLength ASCII characters not including the Null-term= inator, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated= ASCII string - contains more than PcdMaximumAsciiStringLength ASCII characters not incl= uding the - Null-terminator, then ASSERT(). + PcdMaximumAsciiStringLength Ascii characters not including the Null-term= inator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0, then no output buffer is produced and 0 is returned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated ASCII format string. - @param ... Variable argument list whose contents are access= ed based on the=20 + @param FormatString A Null-terminated ASCII format string. + @param ... Variable argument list whose contents are access= ed based on the format string specified by FormatString. - =20 + @return The number of ASCII characters in the produced output buffer not= including the Null-terminator. =20 @@ -324,31 +360,36 @@ UINTN /** Produces a Null-terminated ASCII string in an output buffer based on a N= ull-terminated Unicode format string and a BASE_LIST argument list. - =20 - Produces a Null-terminated ASCII string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + + Produces a Null-terminated ASCII string in the output buffer specified b= y StartOfBuffer + and BufferSize. The ASCII string is produced by parsing the format string specified by F= ormatString. - Arguments are pulled from the variable argument list specified by Marker= based on=20 + Arguments are pulled from the variable argument list specified by Marker= based on the contents of the format string. - This function returns the number of ASCII characters in the output buffe= r,=20 - not including the Null-terminator. - If BufferSize is 0, then no output buffer is produced and 0 is returned. + The number of ASCII characters in the produced output buffer is returned= not including + the Null-terminator. =20 - If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, = then ASSERT(). + If FormatString is not aligned on a 16-bit boundary, then ASSERT(). + + If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumAsciiStringLength is not zero, and BufferSize > + (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the= output buffer + is unmodified and 0 is returned. If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than - PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated= ASCII string - contains more than PcdMaximumAsciiStringLength ASCII characters not incl= uding the - Null-terminator, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0, then no output buffer is produced and 0 is returned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. + @param FormatString A Null-terminated Unicode format string. @param Marker BASE_LIST marker for the variable argument list. - =20 + @return The number of ASCII characters in the produced output buffer not= including the Null-terminator. =20 @@ -365,31 +406,39 @@ UINTN /** Produces a Null-terminated ASCII string in an output buffer based on a N= ull-terminated Unicode format string and variable argument list. - =20 - Produces a Null-terminated ASCII string in the output buffer=20 - specified by StartOfBuffer and BufferSize. + + This function is similar as snprintf_s defined in C11. + + Produces a Null-terminated ASCII string in the output buffer specified b= y StartOfBuffer + and BufferSize. The ASCII string is produced by parsing the format string specified by F= ormatString. - Arguments are pulled from the variable argument list based on the conten= ts of the format string. - This function returns the number of ASCII characters in the output buffe= r,=20 - not including the Null-terminator. - If BufferSize is 0, then no output buffer is produced and 0 is returned. + Arguments are pulled from the variable argument list based on the conten= ts of the + format string. + The number of ASCII characters in the produced output buffer is returned= not including + the Null-terminator. + + If FormatString is not aligned on a 16-bit boundary, then ASSERT(). =20 - If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is NULL, then ASSERT(). - If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, = then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than=20 - PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated= ASCII string - contains more than PcdMaximumAsciiStringLength ASCII characters not incl= uding the - Null-terminator, then ASSERT(). + If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the ou= tput buffer is + unmodified and 0 is returned. + If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the out= put buffer is + unmodified and 0 is returned. + If PcdMaximumAsciiStringLength is not zero, and BufferSize > + (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the= output buffer + is unmodified and 0 is returned. + If PcdMaximumUnicodeStringLength is not zero, and FormatString contains = more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-= terminator, then + ASSERT(). Also, the output buffer is unmodified and 0 is returned. + + If BufferSize is 0, then no output buffer is produced and 0 is returned. =20 - @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated=20 + @param StartOfBuffer A pointer to the output buffer for the produced = Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specifi= ed by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. - @param ... Variable argument list whose contents are access= ed based on the=20 + @param FormatString A Null-terminated Unicode format string. + @param ... Variable argument list whose contents are access= ed based on the format string specified by FormatString. - =20 + @return The number of ASCII characters in the produced output buffer not= including the Null-terminator. =20 --=20 1.9.5.msysgit.0 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel