GetDiskFreeSpace

The GetDiskFreeSpace function retrieves information about the specified disk, including the amount of free space on the disk.

This function has been superseded by the GetDiskFreeSpaceEx function. New Win32-based applications should use GetDiskFreeSpaceEx.

BOOL GetDiskFreeSpace(
  LPCTSTR lpRootPathName,          // root path
  LPDWORD lpSectorsPerCluster,     // sectors per cluster
  LPDWORD lpBytesPerSector,        // bytes per sector
  LPDWORD lpNumberOfFreeClusters,  // free clusters
  LPDWORD lpTotalNumberOfClusters  // total clusters
);

Parameters

lpRootPathName

[in] Pointer to a null-terminated string that specifies the root directory of the disk to return information about. If lpRootPathName is NULL, the function uses the root of the current directory. If this parameter is a UNC name, you must follow it with a trailing backslash. For example, you would specify \\MyServer\MyShare as \\MyServer\MyShare\. However, a drive specification such as "C:" cannot have a trailing backslash.

Windows 95: The initial release of Windows 95 does not support UNC paths for the lpszRootPathName parameter. To query the free disk space using a UNC path, temporarily map the UNC path to a drive letter, query the free disk space on the drive, then remove the temporary mapping. Windows 95 OSR2 and later: UNC paths are supported.

lpSectorsPerCluster

[out] Pointer to a variable for the number of sectors per cluster.

lpBytesPerSector

[out] Pointer to a variable for the number of bytes per sector.

lpNumberOfFreeClusters

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

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

lpTotalNumberOfClusters

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

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

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

The GetDiskFreeSpaceEx function lets you avoid the arithmetic required by the GetDiskFreeSpace function.

Windows 95:

For volumes that are larger than 2 gigabytes, the GetDiskFreeSpace function may return misleading values. The function caps the values stored into *lpNumberOfFreeClusters and *lpTotalNumberOfClusters so as to never report volume sizes that are greater than 2 gigabytes.

Even on volumes that are smaller than 2 gigabytes, the values stored into *lpSectorsPerCluster, *lpNumberOfFreeClusters, and *lpTotalNumberOfClusters values may be incorrect. That is because the operating system manipulates the values so that computations with them yield the correct volume size.

Windows 95 OSR2 and Windows 98:

The GetDiskFreeSpaceEx function is available beginning with Windows 95 OEM Service Release 2 (OSR2), and you should use it whenever possible. The GetDiskFreeSpaceEx function returns correct values for all volumes, including those that are larger than 2 gigabytes.

Windows NT and Windows 2000:

GetDiskFreeSpaceEx is available on Windows NT version 4.0 and higher, including Windows 2000.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 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, GetDiskFreeSpaceEx, GetDriveType