diff options
Diffstat (limited to 'MdePkg/Include/Library/PrintLib.h')
| -rw-r--r-- | MdePkg/Include/Library/PrintLib.h | 209 |
1 files changed, 101 insertions, 108 deletions
diff --git a/MdePkg/Include/Library/PrintLib.h b/MdePkg/Include/Library/PrintLib.h index e9cd0842979d..8548e1ce5b62 100644 --- a/MdePkg/Include/Library/PrintLib.h +++ b/MdePkg/Include/Library/PrintLib.h @@ -2,45 +2,39 @@ Provides services to print a formatted string to a buffer. All combinations of Unicode and ASCII strings are supported. -Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - The Print Library functions provide a simple means to produce formatted output - strings. Many of the output functions use a format string to describe how to - format the output of variable arguments. The format string consists of normal - text and argument descriptors. There are no restrictions for how the normal - text and argument descriptors can be mixed. The following end of line(EOL) +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + The Print Library functions provide a simple means to produce formatted output + strings. Many of the output functions use a format string to describe how to + format the output of variable arguments. The format string consists of normal + text and argument descriptors. There are no restrictions for how the normal + text and argument descriptors can be mixed. The following end of line(EOL) translations must be performed on the contents of the format string: - + - '\\r' is translated to '\\r' - '\\r\\n' is translated to '\\r\\n' - - '\\n' is translated to '\\r\\n' + - '\\n' is translated to '\\r\\n' - '\\n\\r' is translated to '\\r\\n' - - This does not follow the ANSI C standard for sprint(). The format of argument - descriptors is described below. The ANSI C standard for sprint() has been - followed for some of the format types, and has not been followed for others. + + This does not follow the ANSI C standard for sprint(). The format of argument + descriptors is described below. The ANSI C standard for sprint() has been + followed for some of the format types, and has not been followed for others. The exceptions are noted below. %[flags][width][.precision]type [flags]: - - - - - The field is left justified. If not flag is not specified, then the + - - + - The field is left justified. If not flag is not specified, then the field is right justified. - - space + - space - Prefix a space character to a number. Only valid for types X, x, and d. - - + - - Prefix a plus character to a number. Only valid for types X, x, and d. + - + + - Prefix a plus character to a number. Only valid for types X, x, and d. If both space and + are specified, then space is ignored. - 0 - - Pad with 0 characters to the left of a number. Only valid for types + - Pad with 0 characters to the left of a number. Only valid for types X, x, and d. - , - Place a comma every 3rd digit of the number. Only valid for type d. @@ -53,20 +47,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. [width]: - * - - The width of the field is specified by a UINTN argument in the + - The width of the field is specified by a UINTN argument in the argument list. - number - - The number specified as a decimal value represents the width of + - The number specified as a decimal value represents the width of the field. - NOTE: If [width] is not specified, then a field width of 0 is assumed. [.precision]: - * - - The precision of the field is specified by a UINTN argument in the + - The precision of the field is specified by a UINTN argument in the argument list. - number - - The number specified as a decimal value represents the precision of + - The number specified as a decimal value represents the precision of the field. - NOTE: If [.precision] is not specified, then a precision of 0 is assumed. @@ -75,102 +69,102 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - % - Print a %%. - c - - The argument is a Unicode character. ASCII characters can be printed + - The argument is a Unicode character. ASCII characters can be printed using this type too by making sure bits 8..15 of the argument are set to 0. - x - - The argument is an unsigned hexadecimal number. The characters used are 0..9 and - A..F. If the flag 'L' is not specified, then the argument is assumed + - The argument is an unsigned hexadecimal number. The characters used are 0..9 and + A..F. If the flag 'L' is not specified, then the argument is assumed to be size int. This does not follow ANSI C. - X - - The argument is an unsigned hexadecimal number and the number is padded with - zeros. This is equivalent to a format string of "0x". If the flag - 'L' is not specified, then the argument is assumed to be size int. + - The argument is an unsigned hexadecimal number and the number is padded with + zeros. This is equivalent to a format string of "0x". If the flag + 'L' is not specified, then the argument is assumed to be size int. This does not follow ANSI C. - d - - The argument is a signed decimal number. If the flag 'L' is not specified, - then the argument is assumed to be size int. + - The argument is a signed decimal number. If the flag 'L' is not specified, + then the argument is assumed to be size int. - u - - The argument is a unsigned decimal number. If the flag 'L' is not specified, + - The argument is a unsigned decimal number. If the flag 'L' is not specified, then the argument is assumed to be size int. - p - - The argument is a pointer that is a (VOID *), and it is printed as an + - The argument is a pointer that is a (VOID *), and it is printed as an unsigned hexadecimal number The characters used are 0..9 and A..F. - a - - The argument is a pointer to an ASCII string. + - The argument is a pointer to an ASCII string. This does not follow ANSI C. - S, s - - The argument is a pointer to a Unicode string. + - The argument is a pointer to a Unicode string. This does not follow ANSI C. - g - - The argument is a pointer to a GUID structure. The GUID is printed - in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. + - The argument is a pointer to a GUID structure. The GUID is printed + in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. This does not follow ANSI C. - t - - The argument is a pointer to an EFI_TIME structure. The time and - date are printed in the format "mm/dd/yyyy hh:mm" where mm is the - month zero padded, dd is the day zero padded, yyyy is the year zero - padded, hh is the hour zero padded, and mm is minutes zero padded. - This does not follow ANSI C. + - The argument is a pointer to an EFI_TIME structure. The time and + date are printed in the format "mm/dd/yyyy hh:mm" where mm is the + month zero padded, dd is the day zero padded, yyyy is the year zero + padded, hh is the hour zero padded, and mm is minutes zero padded. + This does not follow ANSI C. - r - - The argument is a RETURN_STATUS value. This value is converted to - a string following the table below. This does not follow ANSI C. - - RETURN_SUCCESS + - The argument is a RETURN_STATUS value. This value is converted to + a string following the table below. This does not follow ANSI C. + - RETURN_SUCCESS - "Success" - - RETURN_LOAD_ERROR + - RETURN_LOAD_ERROR - "Load Error" - - RETURN_INVALID_PARAMETER + - RETURN_INVALID_PARAMETER - "Invalid Parameter" - - RETURN_UNSUPPORTED + - RETURN_UNSUPPORTED - "Unsupported" - - RETURN_BAD_BUFFER_SIZE + - RETURN_BAD_BUFFER_SIZE - "Bad Buffer Size" - - RETURN_BUFFER_TOO_SMALL + - RETURN_BUFFER_TOO_SMALL - "Buffer Too Small" - - RETURN_NOT_READY + - RETURN_NOT_READY - "Not Ready" - - RETURN_DEVICE_ERROR + - RETURN_DEVICE_ERROR - "Device Error" - - RETURN_WRITE_PROTECTED + - RETURN_WRITE_PROTECTED - "Write Protected" - - RETURN_OUT_OF_RESOURCES + - RETURN_OUT_OF_RESOURCES - "Out of Resources" - - RETURN_VOLUME_CORRUPTED + - RETURN_VOLUME_CORRUPTED - "Volume Corrupt" - - RETURN_VOLUME_FULL + - RETURN_VOLUME_FULL - "Volume Full" - - RETURN_NO_MEDIA + - RETURN_NO_MEDIA - "No Media" - - RETURN_MEDIA_CHANGED + - RETURN_MEDIA_CHANGED - "Media changed" - - RETURN_NOT_FOUND + - RETURN_NOT_FOUND - "Not Found" - - RETURN_ACCESS_DENIED + - RETURN_ACCESS_DENIED - "Access Denied" - - RETURN_NO_RESPONSE + - RETURN_NO_RESPONSE - "No Response" - - RETURN_NO_MAPPING + - RETURN_NO_MAPPING - "No mapping" - - RETURN_TIMEOUT + - RETURN_TIMEOUT - "Time out" - - RETURN_NOT_STARTED + - RETURN_NOT_STARTED - "Not started" - - RETURN_ALREADY_STARTED + - RETURN_ALREADY_STARTED - "Already started" - - RETURN_ABORTED + - RETURN_ABORTED - "Aborted" - - RETURN_ICMP_ERROR + - RETURN_ICMP_ERROR - "ICMP Error" - - RETURN_TFTP_ERROR + - RETURN_TFTP_ERROR - "TFTP Error" - - RETURN_PROTOCOL_ERROR + - RETURN_PROTOCOL_ERROR - "Protocol Error" - - RETURN_WARN_UNKNOWN_GLYPH + - RETURN_WARN_UNKNOWN_GLYPH - "Warning Unknown Glyph" - - RETURN_WARN_DELETE_FAILURE + - RETURN_WARN_DELETE_FAILURE - "Warning Delete Failure" - - RETURN_WARN_WRITE_FAILURE + - RETURN_WARN_WRITE_FAILURE - "Warning Write Failure" - - RETURN_WARN_BUFFER_TOO_SMALL + - RETURN_WARN_BUFFER_TOO_SMALL - "Warning Buffer Too Small" **/ @@ -180,9 +174,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /// /// Define the maximum number of characters that are required to -/// encode with a NULL terminator a decimal, hexadecimal, GUID, +/// encode with a NULL terminator a decimal, hexadecimal, GUID, /// or TIME value. -/// +/// /// Maximum Length Decimal String = 28 /// "-9,223,372,036,854,775,808" /// Maximum Length Hexadecimal String = 17 @@ -195,7 +189,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define MAXIMUM_VALUE_CHARACTERS 38 /// -/// Flags bitmask values use in UnicodeValueToString() and +/// Flags bitmask values use in UnicodeValueToString() and /// AsciiValueToString() /// #define LEFT_JUSTIFY 0x01 @@ -497,26 +491,26 @@ UnicodeSPrintAsciiFormat ( [ATTENTION] This function is deprecated for security reason. Converts a decimal value to a Null-terminated Unicode string. - - Converts the decimal number specified by Value to a Null-terminated Unicode - string specified by Buffer containing at most Width characters. No padding of spaces + + Converts the decimal number specified by Value to a Null-terminated Unicode + string specified by Buffer containing at most Width characters. No padding of spaces is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. The number of Unicode characters in Buffer is returned, not including the Null-terminator. If the conversion contains more than Width characters, then only the first - Width characters are returned, and the total number of characters + Width characters are returned, and the total number of characters required to perform the conversion is returned. - Additional conversion parameters are specified in Flags. - + Additional conversion parameters are specified in Flags. + The Flags bit LEFT_JUSTIFY is always ignored. All conversions are left justified in Buffer. If Width is 0, PREFIX_ZERO is ignored in Flags. If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas are inserted every 3rd digit starting from the right. - If RADIX_HEX is set in Flags, then the output buffer will be + If RADIX_HEX is set in Flags, then the output buffer will be formatted in hexadecimal format. If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, - then Buffer is padded with '0' characters so the combination of the optional '-' + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). @@ -532,7 +526,7 @@ UnicodeSPrintAsciiFormat ( @param Value The 64-bit signed value to convert to a string. @param Width The maximum number of Unicode characters to place in Buffer, not including the Null-terminator. - + @return The number of Unicode characters in Buffer, not including the Null-terminator. **/ @@ -894,29 +888,29 @@ AsciiSPrintUnicodeFormat ( [ATTENTION] This function is deprecated for security reason. Converts a decimal value to a Null-terminated ASCII string. - - Converts the decimal number specified by Value to a Null-terminated ASCII string - specified by Buffer containing at most Width characters. No padding of spaces + + Converts the decimal number specified by Value to a Null-terminated ASCII string + specified by Buffer containing at most Width characters. No padding of spaces is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. The number of ASCII characters in Buffer is returned, not including the Null-terminator. If the conversion contains more than Width characters, then only the first Width characters are returned, and the total number of characters required to perform the conversion is returned. - Additional conversion parameters are specified in Flags. + Additional conversion parameters are specified in Flags. The Flags bit LEFT_JUSTIFY is always ignored. All conversions are left justified in Buffer. If Width is 0, PREFIX_ZERO is ignored in Flags. If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas are inserted every 3rd digit starting from the right. - If RADIX_HEX is set in Flags, then the output buffer will be + If RADIX_HEX is set in Flags, then the output buffer will be formatted in hexadecimal format. If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, - then Buffer is padded with '0' characters so the combination of the optional '-' + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. - + If Buffer is NULL, then ASSERT(). If unsupported bits are set in Flags, then ASSERT(). If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). @@ -928,7 +922,7 @@ AsciiSPrintUnicodeFormat ( @param Value The 64-bit signed value to convert to a string. @param Width The maximum number of ASCII characters to place in Buffer, not including the Null-terminator. - + @return The number of ASCII characters in Buffer, not including the Null-terminator. **/ @@ -967,8 +961,7 @@ AsciiValueToString ( sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. - If Buffer 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 would be returned, then the function will ASSERT(). @param Buffer The pointer to the output buffer for the produced Null-terminated Ascii string. @@ -1004,7 +997,7 @@ AsciiValueToStringS ( ); /** - Returns the number of characters that would be produced by if the formatted + Returns the number of characters that would be produced by if the formatted output were produced not including the Null-terminator. If FormatString is not aligned on a 16-bit boundary, then ASSERT(). @@ -1017,7 +1010,7 @@ AsciiValueToStringS ( @param[in] FormatString A Null-terminated Unicode format string. @param[in] Marker VA_LIST marker for the variable argument list. - @return The number of characters that would be produced, not including the + @return The number of characters that would be produced, not including the Null-terminator. **/ UINTN @@ -1028,7 +1021,7 @@ SPrintLength ( ); /** - Returns the number of characters that would be produced by if the formatted + Returns the number of characters that would be produced by if the formatted output were produced not including the Null-terminator. If FormatString is NULL, then ASSERT() and 0 is returned. @@ -1039,7 +1032,7 @@ SPrintLength ( @param[in] FormatString A Null-terminated ASCII format string. @param[in] Marker VA_LIST marker for the variable argument list. - @return The number of characters that would be produced, not including the + @return The number of characters that would be produced, not including the Null-terminator. **/ UINTN |