Correct function comments on DxeServicesLib GetFileBufferByFilePath API.

[mirror_edk2.git] / MdePkg / Library / BasePrintLib / PrintLib.c

diff --git a/MdePkg/Library/BasePrintLib/PrintLib.c b/MdePkg/Library/BasePrintLib/PrintLib.c
index 1faf51a560b11a784d1b71ebf33b83bb3991bb9d..43b2b3c1d3c0c3bb71da4b239e58d46a45cabcea 100644 (file)
--- a/MdePkg/Library/BasePrintLib/PrintLib.c
+++ b/MdePkg/Library/BasePrintLib/PrintLib.c
@@ -1,12 +1,12 @@
 /** @file\r
   Base Print Library instance implementation.\r
 \r
-  Copyright (c) 2006 - 2009, Intel Corporation<BR>\r
-  Portions copyright (c) 2008-2009 Apple Inc. All rights reserved.<BR>\r
-  All rights reserved. This program and the accompanying materials\r
+  Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>\r
+  Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
+  This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
   which accompanies this distribution.  The full text of the license may be found at\r
-  http://opensource.org/licenses/bsd-license.php\r
+  http://opensource.org/licenses/bsd-license.php.\r
 \r
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
@@ -52,7 +52,7 @@ VA_LIST gNullVaList;
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  Marker          VA_LIST marker for the variable argument list.\r
   \r
   @return The number of Unicode characters in the produced output buffer not including the\r
@@ -100,7 +100,7 @@ UnicodeVSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  Marker          BASE_LIST marker for the variable argument list.\r
   \r
   @return The number of Unicode characters in the produced output buffer not including the\r
@@ -147,7 +147,7 @@ UnicodeBSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  ...             Variable argument list whose contents are accessed based on the \r
                           format string specified by FormatString.\r
   \r
@@ -165,9 +165,12 @@ UnicodeSPrint (
   )\r
 {\r
   VA_LIST Marker;\r
+  UINTN   NumberOfPrinted;\r
 \r
   VA_START (Marker, FormatString);\r
-  return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  NumberOfPrinted = UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  VA_END (Marker);\r
+  return NumberOfPrinted;\r
 }\r
 \r
 /**\r
@@ -196,7 +199,7 @@ UnicodeSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  Marker          VA_LIST marker for the variable argument list.\r
   \r
   @return The number of Unicode characters in the produced output buffer not including the\r
@@ -242,7 +245,7 @@ UnicodeVSPrintAsciiFormat (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  Marker          BASE_LIST marker for the variable argument list.\r
   \r
   @return The number of Unicode characters in the produced output buffer not including the\r
@@ -288,7 +291,7 @@ UnicodeBSPrintAsciiFormat (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           Unicode string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  ...             Variable argument list whose contents are accessed based on the \r
                           format string specified by FormatString.\r
   \r
@@ -306,9 +309,12 @@ UnicodeSPrintAsciiFormat (
   )\r
 {\r
   VA_LIST Marker;\r
+  UINTN   NumberOfPrinted;\r
 \r
   VA_START (Marker, FormatString);\r
-  return UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  NumberOfPrinted = UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  VA_END (Marker);\r
+  return NumberOfPrinted;\r
 }\r
 \r
 /**\r
@@ -342,7 +348,7 @@ UnicodeSPrintAsciiFormat (
   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().\r
   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
 \r
-  @param  Buffer  Pointer to the output buffer for the produced Null-terminated\r
+  @param  Buffer  The pointer to the output buffer for the produced Null-terminated\r
                   Unicode string.\r
   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.\r
   @param  Value   The 64-bit signed value to convert to a string.\r
@@ -390,7 +396,7 @@ UnicodeValueToString (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  Marker          VA_LIST marker for the variable argument list.\r
   \r
   @return The number of ASCII characters in the produced output buffer not including the\r
@@ -434,7 +440,7 @@ AsciiVSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  Marker          BASE_LIST marker for the variable argument list.\r
   \r
   @return The number of ASCII characters in the produced output buffer not including the\r
@@ -478,7 +484,7 @@ AsciiBSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated ASCII format string.\r
+  @param  FormatString    A Null-terminated ASCII format string.\r
   @param  ...             Variable argument list whose contents are accessed based on the \r
                           format string specified by FormatString.\r
    \r
@@ -496,9 +502,12 @@ AsciiSPrint (
   )\r
 {\r
   VA_LIST Marker;\r
+  UINTN   NumberOfPrinted;\r
 \r
   VA_START (Marker, FormatString);\r
-  return AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  NumberOfPrinted = AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  VA_END (Marker);\r
+  return NumberOfPrinted;\r
 }\r
 \r
 /**\r
@@ -527,7 +536,7 @@ AsciiSPrint (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  Marker          VA_LIST marker for the variable argument list.\r
   \r
   @return The number of ASCII characters in the produced output buffer not including the\r
@@ -573,7 +582,7 @@ AsciiVSPrintUnicodeFormat (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  Marker          BASE_LIST marker for the variable argument list.\r
   \r
   @return The number of ASCII characters in the produced output buffer not including the\r
@@ -619,7 +628,7 @@ AsciiBSPrintUnicodeFormat (
   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated \r
                           ASCII string.\r
   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
-  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  FormatString    A Null-terminated Unicode format string.\r
   @param  ...             Variable argument list whose contents are accessed based on the \r
                           format string specified by FormatString.\r
   \r
@@ -637,9 +646,12 @@ AsciiSPrintUnicodeFormat (
   )\r
 {\r
   VA_LIST Marker;\r
+  UINTN   NumberOfPrinted;\r
 \r
   VA_START (Marker, FormatString);\r
-  return AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  NumberOfPrinted = AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);\r
+  VA_END (Marker);\r
+  return NumberOfPrinted;\r
 }\r
 \r
 \r
@@ -673,7 +685,7 @@ AsciiSPrintUnicodeFormat (
   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().\r
   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
 \r
-  @param  Buffer  Pointer to the output buffer for the produced Null-terminated\r
+  @param  Buffer  The pointer to the output buffer for the produced Null-terminated\r
                   ASCII string.\r
   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.\r
   @param  Value   The 64-bit signed value to convert to a string.\r
@@ -694,3 +706,51 @@ AsciiValueToString (
 {\r
   return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);\r
 }\r
+\r
+/**\r
+  Returns the number of characters that would be produced by if the formatted \r
+  output were produced not including the Null-terminator.\r
+\r
+  If FormatString is NULL, then ASSERT().\r
+  If FormatString is not aligned on a 16-bit boundary, then ASSERT().\r
+\r
+  @param[in]  FormatString    A Null-terminated Unicode format string.\r
+  @param[in]  Marker          VA_LIST marker for the variable argument list.\r
+\r
+  @return The number of characters that would be produced, not including the \r
+          Null-terminator.\r
+**/\r
+UINTN\r
+EFIAPI\r
+SPrintLength (\r
+  IN  CONST CHAR16   *FormatString,\r
+  IN  VA_LIST       Marker\r
+  )\r
+{\r
+  ASSERT(FormatString != NULL);\r
+  ASSERT_UNICODE_BUFFER (FormatString);\r
+  return BasePrintLibSPrintMarker (NULL, 0, FORMAT_UNICODE | OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);\r
+}\r
+\r
+/**\r
+  Returns the number of characters that would be produced by if the formatted \r
+  output were produced not including the Null-terminator.\r
+\r
+  If FormatString is NULL, then ASSERT().\r
+\r
+  @param[in]  FormatString    A Null-terminated ASCII format string.\r
+  @param[in]  Marker          VA_LIST marker for the variable argument list.\r
+\r
+  @return The number of characters that would be produced, not including the \r
+          Null-terminator.\r
+**/\r
+UINTN\r
+EFIAPI\r
+SPrintLengthAsciiFormat (\r
+  IN  CONST CHAR8   *FormatString,\r
+  IN  VA_LIST       Marker\r
+  )\r
+{\r
+  ASSERT(FormatString != NULL);\r
+  return BasePrintLibSPrintMarker (NULL, 0, OUTPUT_UNICODE | COUNT_ONLY_NO_PRINT, (CHAR8 *)FormatString, Marker, NULL);\r
+}\r