StrFormatByteSizeEx function (shlwapi.h)

Article
02/22/2024

Converts a numeric value into a string that represents the number in bytes, kilobytes, megabytes, or gigabytes, depending on the size. Extends StrFormatByteSizeW by offering the option to round to the nearest displayed digit or to discard undisplayed digits.

Syntax

LWSTDAPI StrFormatByteSizeEx(
        ULONGLONG  ull,
        SFBS_FLAGS flags,
  [out] PWSTR      pszBuf,
        UINT       cchBuf
);

Parameters

ull

Type: ULONGLONG

The numeric value to be converted.

flags

Type: SFBS_FLAGS

One of the SFBS_FLAGS enumeration values that specifies whether to round or truncate undisplayed digits. This value cannot be NULL.

[out] pszBuf

Type: PWSTR

A pointer to a buffer that receives the converted string.

cchBuf

Type: UINT

The size of the buffer pointed to by pszBuf, in characters.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The following table illustrates how this function converts a numeric value into a text string in relation to the passed flag.

Numeric value	Flag	Text string
2147483647	SFBS_FLAGS_ROUND_TO_NEAREST_DISPLAYED_DIGIT	2.00 GB
2147483647	SFBS_FLAGS_TRUNCATE_UNDISPLAYED_DECIMAL_DIGITS	1.99 GB

In Windows 10, size is reported in base 10 rather than base 2. For example, 1 KB is 1000 bytes rather than 1024.

Requirements

Requirement	Value
Minimum supported client	Windows Vista with SP1 [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (version 6.0 or later)