NAME

Win32::DirSize - Calculate sizes of directories on Win32

DEPENDENCIES

Win32::API

SYNOPSIS

        ### Example one:

        use Win32::DirSize qw( DirSize ToMB );

        my $Directory   = "C:\\TEMP";
        my $DirInfo             = DirSize($Directory);

        printf("Directory %s has %u files and %u subdirectories, using %0.2f MB.\n",
                $Directory,
                $DirInfo->{FileCount},
                $DirInfo->{DirCount},
                ToMB($DirInfo),
        );

        ### Example two:

        use Win32::DirSize qw( DirSize ToBest );

        my $Directory   = "C:\\TEMP";
        my $DirInfo             = DirSize($Directory);
        my $SizeInfo    = ToBest($DirInfo);

        printf("Directory %s has %u files and %u subdirectories, using %0.2f %s.\n",
                $Directory,
                $DirInfo->{FileCount},
                $DirInfo->{DirCount},
                $SizeInfo->{Value},
                $SizeInfo->{Unit},
        );

        if ($DirInfo->{IsError}) {
                print "Errors encountered were:\n";
                foreach my $error (@{$DirInfo->{Errors}}) {
                        printf("Error #%u: %s in directory %s\n", 
                                $error->{ErrCode}, 
                                $error->{ErrText},
                                $error->{DirName} ? $error->{DirName} : 'N/A',
                        );
                }
        }

DESCRIPTION

        Win32::DirSize will calculate the total size used by any directory on your
        Win32 file system.  It can also give you the total count of files or directories
        under that directory.

        The main function is DirSize() - takes a directory as an argument and returns a single hashref.
        The hashref keys are: IsError, Errors, HighSize, LowSize, FileCount, DirCount.

        Since the maximum size a single integer can represent is 4 GB, Win32::DirSize uses
        two integers, HighSize to represent the upper 32 bits, and LowSize to represent the lower 32 bits.
        This allows a maximum size of over 16,000 exabytes.

        If you prefer to work with the raw size in bytes, I suggest the Math::BigInt module.

        There are four helper functions to convert these values into something more usable:
        ToMB(), ToGB(), ToTB(), and ToEB() to calculate megabytes, gigabytes, terabytes, 
        and exabytes respectively.  

        Note: For sizes over 4 terabytes, avoid ToKB().  Use one of the other functions.
        Note: For sizes over 4 exabytes, avoid ToKB() and ToMB().  Use one of the other functions.
        Note: For sizes over 4096 exabytes, avoid ToKB() and ToMB() and ToGB().  Use one of the other functions.

        If you don't know the general size of the directory before hand, you can use ToBest().
        This function will determine the best unit for the size and return a hashref with the 
        reduced size and chosen unit.  

        In the process of recursing through directories, any errors will set IsError to true.
        A description of the error in the form of a hashref is pushed onto the Errors array ref.
        Usually, these errors are "Access Denied" messages for locked or secured directories.

EXPORT

DirSize is exported by default.

EXPORT OK

Optional exports are: DirSize ToMB ToGB ToTB ToEB ToBest

AUTHOR

Adam Rich (ar3121@sbc.com)