NAME

Win32::DriveInfo - drives on Win32 systems

SYNOPSIS

    use Win32::DriveInfo;

    ($SectorsPerCluster,
     $BytesPerSector,
     $NumberOfFreeClusters,
     $TotalNumberOfClusters,
     $FreeBytesAvailableToCaller,
     $TotalNumberOfBytes,
     $TotalNumberOfFreeBytes) = Win32::DriveInfo::DriveSpace('f');

     $TotalNumberOfFreeBytes = (Win32::DriveInfo::DriveSpace('c:'))[6];

     $TotalNumberOfBytes = (Win32::DriveInfo::DriveSpace("\\\\serv\\share"))[5];

     @drives = Win32::DriveInfo::DrivesInUse();

     @freelet = Win32::DriveInfo::FreeDriveLetters();

     $type = Win32::DriveInfo::DriveType('a');

     ($VolumeName,
      $VolumeSerialNumber,
      $MaximumComponentLength,
      $FileSystemName, @attr) = Win32::DriveInfo::VolumeInfo('g');

     ($MajorVersion, $MinorVersion, $BuildNumber,
      $PlatformId, $BuildStr) = Win32::DriveInfo::GetVersionEx();

     # check is your CD-ROM loaded
     $CDROM = ( grep { Win32::DriveInfo::DriveType($_) == 5 }
        Win32::DriveInfo::DrivesInUse() )[0];
     $CD_inside = Win32::DriveInfo::IsReady($CDROM);

ABSTRACT

With this module you can get total/free space on Win32 drives, volume names, architecture, filesystem type, drive attributes, list of all available drives and free drive-letters. Additional function to determine Windows version info.

The intention was to have a part of Dave Roth's Win32::AdminMisc functionality on Win95/98.

The current version of Win32::DriveInfo is available at:

  http://base.dux.ru/guest/fno/perl/

DESCRIPTION

    Module provides few functions:

    DriveSpace ( drive )

    ($SectorsPerCluster, $BytesPerSector, $NumberOfFreeClusters, $TotalNumberOfClusters, $FreeBytesAvailableToCaller, $TotalNumberOfBytes, $TotalNumberOfFreeBytes) = Win32::DriveInfo::DriveSpace( drive );

       drive - drive-letter in either 'c' or 'c:' or 'c:\\' form or UNC path
               in either "\\\\server\\share" or "\\\\server\\share\\" form.
       $SectorsPerCluster          - number of sectors per cluster.
       $BytesPerSector             - number of bytes per sector.
       $NumberOfFreeClusters       - total number of free clusters on the disk.
       $TotalNumberOfClusters      - total number of clusters on the disk.
       $FreeBytesAvailableToCaller - total number of free bytes on the disk that
                                     are available to the user associated with the
                                     calling thread, b.
       $TotalNumberOfBytes         - total number of bytes on the disk, b.
       $TotalNumberOfFreeBytes     - total number of free bytes on the disk, b.

    Note: in case that UNC path was given first 4 values are undef.

    Win 95 note: Win32 API GetDiskFreeSpaceEx() function that is realized by internal (not intended for users) GetDiskFreeSpaceEx() subroutine is available on Windows 95 OSR2 (OEM Service Release 2) only. This means build numbers ($BuildNumber in GetVersionEx ( ) function, described here later) greater then 1000.

    On lower Win95 builds $FreeBytesAvailableToCaller, $TotalNumberOfBytes, $TotalNumberOfFreeBytes are realized through the internal GetDiskFreeSpace() function that is claimed less trustworthy in Win32 SDK documentation.

    That's why on lower Win 95 builds this function will return 7 undef's for UNC drives.

    To say in short: don't use DriveSpace ( ) for UNC paths on early Win 95! Where possible use

      net use * \\server\share

    and then usual '\w:' syntax.

    DrivesInUse ( )

    Returns sorted array of all drive-letters in use.

    FreeDriveLetters ( )

    Returns sorted array of all drive-letters that are available for allocation.

    DriveType ( drive )

    Returns integer value:

       0     - the drive type cannot be determined.
       1     - the root directory does not exist.
       2     - the drive can be removed from the drive (removable).
       3     - the disk cannot be removed from the drive (fixed).
       4     - the drive is a remote (network) drive.
       5     - the drive is a CD-ROM drive.
       6     - the drive is a RAM disk.
    
       drive - drive-letter in either 'c' or 'c:' or 'c:\\' form or UNC path
               in either "\\\\server\\share" or "\\\\server\\share\\" form.

    In case of UNC path 4 will be returned that means that networked drive is available (1 - if not available).

    IsReady ( drive )

    Returns TRUE if root of the drive is accessible, otherwise FALSE. This one isn't really something cool - the function just tries to chdir to the drive's root. This takes time and produces unpleasant sound in case the removable drive is not loaded. If somebody knows some better way to determine is there something inside your CD-ROM or FDD - please let me know (in fact CD-ROMs, RAM drives and network drives return their status fast, may be some other devices make problem, dunno).

       drive - drive-letter in either 'c' or 'c:' or 'c:\\' form or UNC path
               in either "\\\\server\\share" or "\\\\server\\share\\" form.

    VolumeInfo ( drive )

    ($VolumeName, $VolumeSerialNumber, $MaximumComponentLength, $FileSystemName, @attr) = Win32::DriveInfo::VolumeInfo ( drive );

       drive - drive-letter in either 'c' or 'c:' or 'c:\\' form.
    
       $VolumeName             - name of the specified volume.
       $VolumeSerialNumber     - volume serial number.
       $MaximumComponentLength -
            filename component supported by the specified file system.
            A filename component is that portion of a filename between backslashes.
            Indicate that long names are supported by the specified file system.
            For a FAT file system supporting long names, the function stores
            the value 255, rather than the previous 8.3 indicator. Long names can
            also be supported on systems that use the New Technology file system
            (NTFS).
       $FileSystemName         - name of the file system (such as FAT, FAT32, CDFS or NTFS).
       @attr                   - array of integers 1-6
         1 - file system preserves the case of filenames
         2 - file system supports case-sensitive filenames
         3 - file system supports Unicode in filenames as they appear on disk
         4 - file system preserves and enforces ACLs (access-control lists).
             For example, NTFS preserves and enforces ACLs, and FAT does not.
         5 - file system supports file-based compression
         6 - specified volume is a compressed volume; for ex., a DoubleSpace volume

    GetVersionEx ( )

    This function provides version of the OS in use.

    ($MajorVersion, $MinorVersion, $BuildNumber, $PlatformId, $BuildStr) = Win32::DriveInfo::GetVersionEx ( );

       $MajorVersion - major version number of the operating system. For Windows NT
                       version 3.51, it's 3; for Windows NT version 4.0, it's 4.
    
       $MinorVersion - minor version number of the operating system. For Windows NT
                       version 3.51, it's 51; for Windows NT version 4.0, it's 0.
       $BuildNumber  - build number of the operating system.
       $PlatformId   - 0 for Win32s, 1 for Win95/98, 2 for Win NT
       $BuildStr     - Windows NT: Contains string, such as "Service Pack 3".
                       Indicates the latest Service Pack installed on the system.
                       If no Service Pack has been installed, the string is empty.
                       Windows 95: Contains a null-terminated string that provides
                       arbitrary additional information about the operating system.

Nothing is exported by default. All functions return undef on errors.

INSTALLATION

As this is just a plain module no special installation is needed. Just put it into /Win32 subdir somewhere in your @INC. The standard

 Makefile.PL
 make
 make test
 make install

installation procedure is provided. In addition

 make html

will produce the HTML-docs.

This module requires

Win32::API module by Aldo Calpini

CAVEATS

This module has been created and tested in a Win95 environment on GS port of Perl 5.004_02. As it uses Win32::API module I expect it would work fine with other ports like ActiveState if Win32::API (API.dll) is compiled for this port.

CHANGES

 0.02 - Austin Durbin <adurbin@earthlink.net> tested module on Win NT
        and discovered small bug in UNC paths handling. Fixed.
        Thanks Austin!

 0.03 - fixed bug that returned incorrect values for volumes that are
        larger than 0x7fffffff bytes (2 GB). Approved on Win98 with FAT32.

 0.04 - added IsReady() function and MakeMaker compartible distribution.
        Empty SerialNumber fixed. Now it's empty string, previously it
        was evaluated to 0000:0000.
        Minor enhancements.

 0.05 - test.pl fixed, other minor fixes. 
        The last 0.0x version before the major update (soon!)

 0.06 - test.pl fixed more ;-)

BUGS

DriveSpace ( ) returns incorrect $NumberOfFreeClusters, $TotalNumberOfClusters values on the large ( >2M ) drives. Dunno whether somebody use these values or not but I'll try to fix this in the next release.

Please report if any bugs.

VERSION

This man page documents Win32::DriveInfo version 0.06

February 19, 2001

AUTHOR

Mike Blazer <blazer@mail.nevalink.ru>

COPYRIGHT

Copyright (C) 1998-2001 by Mike Blazer. All rights reserved.

LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 311:

You can't have =items (as at line 315) unless the first thing after the =over is an =item