Platform SDK: Files and I/O

GetDiskFreeSpaceEx

The GetDiskFreeSpaceEx function retrieves information about the amount of space available on a disk volume: the total amount of space, the total amount of free space, and the total amount of free space available to the user associated with the calling thread.

BOOL GetDiskFreeSpaceEx(
  LPCTSTR lpDirectoryName,                 // directory name
  PULARGE_INTEGER lpFreeBytesAvailable,    // bytes available to caller
  PULARGE_INTEGER lpTotalNumberOfBytes,    // bytes on disk
  PULARGE_INTEGER lpTotalNumberOfFreeBytes // free bytes on disk
);

Parameters

lpDirectoryName
[in] Pointer to a null-terminated string that specifies a directory on the disk of interest. This string can be a UNC name. If this parameter is a UNC name, you must follow it with an additional backslash. For example, you would specify \\MyServer\MyShare as \\MyServer\MyShare\.

If lpDirectoryName is NULL, the GetDiskFreeSpaceEx function retrieves information about the disk that contains the current directory.

Note that lpDirectoryName does not have to specify the root directory on a disk. The function accepts any directory on the disk.

lpFreeBytesAvailable
[out] Pointer to a variable that receives the total number of free bytes on the disk that are available to the user associated with the calling thread.

Windows 2000: If per-user quotas are in use, this value may be less than the total number of free bytes on the disk.

lpTotalNumberOfBytes
[out] Pointer to a variable that receives the total number of bytes on the disk that are available to the user associated with the calling thread.

Windows 2000: If per-user quotas are in use, this value may be less than the total number of bytes on the disk.

lpTotalNumberOfFreeBytes
[out] Pointer to a variable that receives the total number of free bytes on the disk.

This parameter can be NULL.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Note that the values obtained by this function are of type ULARGE_INTEGER. Be careful not to truncate these values to 32 bits.

Windows NT and Windows 2000: GetDiskFreeSpaceEx is available on Windows NT version 4.0 and higher, including Windows 2000. See the following information for a method to determine at run time if it is available.

Windows 95 OSR2 and Windows 98: The GetDiskFreeSpaceEx function is available beginning with Windows 95 OEM Service Release 2 (OSR2).

To determine whether GetDiskFreeSpaceEx is available, call GetModuleHandle to get the handle to Kernel32.dll. Then you can call GetProcAddress.

The following code fragment shows one way to do this:

pGetDiskFreeSpaceEx = GetProcAddress( GetModuleHandle("kernel32.dll"),
                         "GetDiskFreeSpaceExA");

if (pGetDiskFreeSpaceEx)
{
   fResult = pGetDiskFreeSpaceEx (pszDrive,
                (PULARGE_INTEGER)&i64FreeBytesToCaller,
                (PULARGE_INTEGER)&i64TotalBytes,
                (PULARGE_INTEGER)&i64FreeBytes);

// Process GetDiskFreeSpaceEx results.
}

else 
{
   fResult = GetDiskFreeSpace (pszDrive, 
                &dwSectPerClust, 
                &dwBytesPerSect,
                &dwFreeClusters, 
                &dwTotalClusters)

// Process GetDiskFreeSpace results.

}

It is not necessary to call LoadLibrary on Kernel32.dll because it is already loaded into every Win32 process's address space.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

File I/O Overview, File I/O Functions, GetDiskFreeSpace, GetModuleHandle, GetProcAddress