FileSystemUtils (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io

## Class FileSystemUtils

- java.lang.Object
- - org.apache.commons.io.FileSystemUtils

-     public class FileSystemUtils
      extends java.lang.Object

  General File System utilities.

  This class provides static utility methods for general file system functions not provided via the JDK `File` class.

  The current functions provided are:

  - Get the free space on a drive
  Since:
    1.1
  Version:
    $Id: FileSystemUtils.java 1686747 2015-06-21 18:44:49Z krosenvold $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static java.lang.String` | `DF` The path to df
    `private static int` | `INIT_PROBLEM` Operating system state flag for error.
    `private static FileSystemUtils` | `INSTANCE` Singleton instance, used mainly for testing.
    `private static int` | `OS` The operating system flag.
    `private static int` | `OTHER` Operating system state flag for neither Unix nor Windows.
    `private static int` | `POSIX_UNIX` Operating system state flag for Posix flavour Unix.
    `private static int` | `UNIX` Operating system state flag for Unix.
    `private static int` | `WINDOWS` Operating system state flag for Windows.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FileSystemUtils()` Instances should NOT be constructed in standard programming.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `freeSpace(java.lang.String path)` Deprecated. Use freeSpaceKb(String) Deprecated from 1.3, may be removed in 2.0
    `static long` | `freeSpaceKb()` Returns the disk size of the volume which holds the working directory.
    `static long` | `freeSpaceKb(long timeout)` Returns the disk size of the volume which holds the working directory.
    `static long` | `freeSpaceKb(java.lang.String path)` Returns the free space on a drive or volume in kilobytes by invoking the command line.
    `static long` | `freeSpaceKb(java.lang.String path, long timeout)` Returns the free space on a drive or volume in kilobytes by invoking the command line.
    `(package private) long` | `freeSpaceOS(java.lang.String path, int os, boolean kb, long timeout)` Returns the free space on a drive or volume in a cross-platform manner.
    `(package private) long` | `freeSpaceUnix(java.lang.String path, boolean kb, boolean posix, long timeout)` Find free space on the *nix platform using the 'df' command.
    `(package private) long` | `freeSpaceWindows(java.lang.String path, long timeout)` Find free space on the Windows platform using the 'dir' command.
    `(package private) java.lang.Process` | `openProcess(java.lang.String[] cmdAttribs)` Opens the process to the operating system.
    `(package private) long` | `parseBytes(java.lang.String freeSpace, java.lang.String path)` Parses the bytes from a string.
    `(package private) long` | `parseDir(java.lang.String line, java.lang.String path)` Parses the Windows dir response last line
    `(package private) java.util.List<java.lang.String>` | `performCommand(java.lang.String[] cmdAttribs, int max, long timeout)` Performs the os command.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### INSTANCE

          private static final FileSystemUtils INSTANCE

      Singleton instance, used mainly for testing.

    - #### INIT_PROBLEM

          private static final int INIT_PROBLEM

      Operating system state flag for error.
      See Also:
        Constant Field Values

    - #### OTHER

          private static final int OTHER

      Operating system state flag for neither Unix nor Windows.
      See Also:
        Constant Field Values

    - #### WINDOWS

          private static final int WINDOWS

      Operating system state flag for Windows.
      See Also:
        Constant Field Values

    - #### UNIX

          private static final int UNIX

      Operating system state flag for Unix.
      See Also:
        Constant Field Values

    - #### POSIX_UNIX

          private static final int POSIX_UNIX

      Operating system state flag for Posix flavour Unix.
      See Also:
        Constant Field Values

    - #### OS

          private static final int OS

      The operating system flag.

    - #### DF

          private static final java.lang.String DF

      The path to df

  - ### Constructor Detail

    - #### FileSystemUtils

          public FileSystemUtils()

      Instances should NOT be constructed in standard programming.

  - ### Method Detail

    - #### freeSpace

          @Deprecated
          public static long freeSpace(java.lang.String path)
                                throws java.io.IOException

      Deprecated. Use freeSpaceKb(String) Deprecated from 1.3, may be removed in 2.0
      Returns the free space on a drive or volume by invoking the command line. This method does not normalize the result, and typically returns bytes on Windows, 512 byte units on OS X and kilobytes on Unix. As this is not very useful, this method is deprecated in favour of `freeSpaceKb(String)` which returns a result in kilobytes.

      Note that some OS's are NOT currently supported, including OS/390, OpenVMS.

           FileSystemUtils.freeSpace("C:");       // Windows
           FileSystemUtils.freeSpace("/volume");  // *nix

      The free space is calculated via the command line. It uses 'dir /-c' on Windows and 'df' on *nix.
      Parameters:
        `path` - the path to get free space for, not null, not empty on Unix
      Returns:
        the amount of free drive space on the drive or volume
      Throws:
        `java.lang.IllegalArgumentException` - if the path is invalid
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space
      Since:
        1.1, enhanced OS support in 1.2 and 1.3

    - #### freeSpaceKb

          public static long freeSpaceKb(java.lang.String path)
                                  throws java.io.IOException

      Returns the free space on a drive or volume in kilobytes by invoking the command line.

           FileSystemUtils.freeSpaceKb("C:");       // Windows
           FileSystemUtils.freeSpaceKb("/volume");  // *nix

      The free space is calculated via the command line. It uses 'dir /-c' on Windows, 'df -kP' on AIX/HP-UX and 'df -k' on other Unix.

      In order to work, you must be running Windows, or have a implementation of Unix df that supports GNU format when passed -k (or -kP). If you are going to rely on this code, please check that it works on your OS by running some simple tests to compare the command line with the output from this class. If your operating system isn't supported, please raise a JIRA call detailing the exact result from df -k and as much other detail as possible, thanks.

      Parameters:
        `path` - the path to get free space for, not null, not empty on Unix
      Returns:
        the amount of free drive space on the drive or volume in kilobytes
      Throws:
        `java.lang.IllegalArgumentException` - if the path is invalid
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space
      Since:
        1.2, enhanced OS support in 1.3

    - #### freeSpaceKb

          public static long freeSpaceKb(java.lang.String path,
                         long timeout)
                                  throws java.io.IOException

      Returns the free space on a drive or volume in kilobytes by invoking the command line.

           FileSystemUtils.freeSpaceKb("C:");       // Windows
           FileSystemUtils.freeSpaceKb("/volume");  // *nix

      The free space is calculated via the command line. It uses 'dir /-c' on Windows, 'df -kP' on AIX/HP-UX and 'df -k' on other Unix.

      In order to work, you must be running Windows, or have a implementation of Unix df that supports GNU format when passed -k (or -kP). If you are going to rely on this code, please check that it works on your OS by running some simple tests to compare the command line with the output from this class. If your operating system isn't supported, please raise a JIRA call detailing the exact result from df -k and as much other detail as possible, thanks.

      Parameters:
        `path` - the path to get free space for, not null, not empty on Unix
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the amount of free drive space on the drive or volume in kilobytes
      Throws:
        `java.lang.IllegalArgumentException` - if the path is invalid
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space
      Since:
        2.0

    - #### freeSpaceKb

          public static long freeSpaceKb()
                                  throws java.io.IOException

      Returns the disk size of the volume which holds the working directory.

      Identical to:

           freeSpaceKb(new File(".").getAbsolutePath())

      Returns:
        the amount of free drive space on the drive or volume in kilobytes
      Throws:
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space
      Since:
        2.0

    - #### freeSpaceKb

          public static long freeSpaceKb(long timeout)
                                  throws java.io.IOException

      Returns the disk size of the volume which holds the working directory.

      Identical to:

           freeSpaceKb(new File(".").getAbsolutePath())

      Parameters:
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the amount of free drive space on the drive or volume in kilobytes
      Throws:
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space
      Since:
        2.0

    - #### freeSpaceOS

          long freeSpaceOS(java.lang.String path,
                         int os,
                         boolean kb,
                         long timeout)
                     throws java.io.IOException

      Returns the free space on a drive or volume in a cross-platform manner. Note that some OS's are NOT currently supported, including OS/390.

           FileSystemUtils.freeSpace("C:");  // Windows
           FileSystemUtils.freeSpace("/volume");  // *nix

      The free space is calculated via the command line. It uses 'dir /-c' on Windows and 'df' on *nix.
      Parameters:
        `path` - the path to get free space for, not null, not empty on Unix
        `os` - the operating system code
        `kb` - whether to normalize to kilobytes
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the amount of free drive space on the drive or volume
      Throws:
        `java.lang.IllegalArgumentException` - if the path is invalid
        `java.lang.IllegalStateException` - if an error occurred in initialisation
        `java.io.IOException` - if an error occurs when finding the free space

    - #### freeSpaceWindows

          long freeSpaceWindows(java.lang.String path,
                              long timeout)
                          throws java.io.IOException

      Find free space on the Windows platform using the 'dir' command.
      Parameters:
        `path` - the path to get free space for, including the colon
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the amount of free drive space on the drive
      Throws:
        `java.io.IOException` - if an error occurs

    - #### parseDir

          long parseDir(java.lang.String line,
                      java.lang.String path)
                  throws java.io.IOException

      Parses the Windows dir response last line
      Parameters:
        `line` - the line to parse
        `path` - the path that was sent
      Returns:
        the number of bytes
      Throws:
        `java.io.IOException` - if an error occurs

    - #### freeSpaceUnix

          long freeSpaceUnix(java.lang.String path,
                           boolean kb,
                           boolean posix,
                           long timeout)
                       throws java.io.IOException

      Find free space on the *nix platform using the 'df' command.
      Parameters:
        `path` - the path to get free space for
        `kb` - whether to normalize to kilobytes
        `posix` - whether to use the POSIX standard format flag
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the amount of free drive space on the volume
      Throws:
        `java.io.IOException` - if an error occurs

    - #### parseBytes

          long parseBytes(java.lang.String freeSpace,
                        java.lang.String path)
                    throws java.io.IOException

      Parses the bytes from a string.
      Parameters:
        `freeSpace` - the free space string
        `path` - the path
      Returns:
        the number of bytes
      Throws:
        `java.io.IOException` - if an error occurs

    - #### performCommand

          java.util.List<java.lang.String> performCommand(java.lang.String[] cmdAttribs,
                                                        int max,
                                                        long timeout)
                                                    throws java.io.IOException

      Performs the os command.
      Parameters:
        `cmdAttribs` - the command line parameters
        `max` - The maximum limit for the lines returned
        `timeout` - The timeout amount in milliseconds or no timeout if the value is zero or less
      Returns:
        the lines returned by the command, converted to lower-case
      Throws:
        `java.io.IOException` - if an error occurs

    - #### openProcess

          java.lang.Process openProcess(java.lang.String[] cmdAttribs)
                                  throws java.io.IOException

      Opens the process to the operating system.
      Parameters:
        `cmdAttribs` - the command line parameters
      Returns:
        the process
      Throws:
        `java.io.IOException` - if an error occurs

Copyright (c) 2002-2016 Apache Software Foundation