Home Library Learn Downloads Support Community
Sign in | United States - English | |
9 out of 26 rated this helpful - Rate this topic

GetDiskFreeSpaceEx function

Applies to: desktop apps | Metro style apps

Retrieves information about the amount of space that is available on a disk volume, which is the total amount of space, the total amount of free space, and the total amount of free space available to the user that is associated with the calling thread.

Syntax

Copy 
BOOL WINAPI GetDiskFreeSpaceEx(
  __in_opt   LPCTSTR lpDirectoryName,
  __out_opt  PULARGE_INTEGER lpFreeBytesAvailable,
  __out_opt  PULARGE_INTEGER lpTotalNumberOfBytes,
  __out_opt  PULARGE_INTEGER lpTotalNumberOfFreeBytes
);

Parameters

lpDirectoryName [in, optional]

A directory on the disk.

If this parameter is NULL, the function uses the root of the current disk.

If this parameter is a UNC name, it must include a trailing backslash, for example, "\\MyServer\MyShare\".

This parameter does not have to specify the root directory on a disk. The function accepts any directory on a disk.

The calling application must have FILE_LIST_DIRECTORY access rights for this directory.

lpFreeBytesAvailable [out, optional]

A pointer to a variable that receives the total number of free bytes on a disk that are available to the user who is associated with the calling thread.

This parameter can be NULL.

If per-user quotas are being used, this value may be less than the total number of free bytes on a disk.

lpTotalNumberOfBytes [out, optional]

A pointer to a variable that receives the total number of bytes on a disk that are available to the user who is associated with the calling thread.

This parameter can be NULL.

If per-user quotas are being used, this value may be less than the total number of bytes on a disk.

To determine the total number of bytes on a disk or volume, use IOCTL_DISK_GET_LENGTH_INFO.

lpTotalNumberOfFreeBytes [out, optional]

A pointer to a variable that receives the total number of free bytes on a disk.

This parameter can be NULL.

Return value

If the function succeeds, the return value is nonzero.

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

Remarks

The values obtained by this function are of the type ULARGE_INTEGER. Do not truncate these values to 32 bits.

The GetDiskFreeSpaceEx function returns zero (0) for lpTotalNumberOfFreeBytes and lpFreeBytesAvailable for all CD requests unless the disk is an unwritten CD in a CD-RW drive.

Symbolic link behavior—If the path points to a symbolic link, the operation is performed on the target.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
FileAPI.h (include Windows.h);
WinBase.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

Unicode and ANSI names

GetDiskFreeSpaceExW (Unicode) and GetDiskFreeSpaceExA (ANSI)

See also

Disk Management Functions
GetDiskFreeSpace
GetModuleHandle

 

 

Send comments about this topic to Microsoft

Build date: 4/17/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
UNC Sharenames
As an alternative to using this unmanaged API, you could also consider using the System.IO.DriveInfo class. This managed class has a AvailableFreeSpace property that you could use for the same purposes as this API.

Unfortunately the System.IO.DriveInfo class only takes drive letters not UNC sharenames.
History
Error in param description.

WAS
lpDirectoryName [in, optional]
A directory on the disk.
If this parameter is NULL, the function uses the root of the current disk.

SHOULD BE
lpDirectoryName [in, optional]
A directory on the disk.
If this parameter is NULL, the function uses the current working folder's drive letter.

I created a demo to test this after a error showed up in our production.

First img shows running the EXE direct, second shows as a shortcut with C:\ as the working folder.
http://www.chizl.com/downloads/DiskspaceDemo/Diskspace.jpg

VC++ Console App - Source Code of Demo
http://www.chizl.com/downloads/DiskspaceDemo/Diskspace.cpp
Compiled Demo
http://www.chizl.com/downloads/DiskspaceDemo/Diskspace.exe

History
SetErrorMode for floppy
To bad it pops up an awful dialog box.

Peter Smith in Redmond,
I think that you should be able to use SetErrorMode() to supress this dialog. Although not tested on Vista it should work.

SetErrorMode(SEM_FAILCRITICALERRORS)

// do work

SetErrorMode(0)
History
To bad it pops up an awful dialog box...
This function, regretfully, pops up a horrid dialog box on Vista for drive "A:\" when it doesn't have anything in the disk drive. Which is one of the few reasons to loath Vista.
History
Allternative to using unmanaged code

As an alternative to using this unmanaged API, you could also consider using the System.IO.DriveInfo class. This managed class has a AvailableFreeSpace property that you could use for the same purposes as this API.

For more information on the DriveInfo class, see: http://msdn.microsoft.com/en-us/library/system.io.driveinfo(VS.85).aspx

History