fix #829: disk_usage().percent takes reserved root space into account

4 files changed, 46 insertions, 14 deletions

diff --git a/HISTORY.rst b/HISTORY.rst
index b45e0183..1adcc669 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -3,8 +3,12 @@ Bug tracker at https://github.com/giampaolo/psutil/issues
 4.3.0 - XXXX-XX-XX
 ==================
 
+**Bug fixes**
+
 - #812: [NetBSD] fix compilation on NetBSD-5.x.
 - #823: [NetBSD] virtual_memory() raises TypeError on Python 3.
+- #829: [UNIX] psutil.disk_usage() percent field takes root reserved space
+  into account.
 
 
 4.2.0 - 2016-05-14
diff --git a/docs/index.rst b/docs/index.rst
index fd17601c..2778e36c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -278,20 +278,28 @@ Disks
   **total**, **used** and **free** space expressed in bytes, plus the
   **percentage** usage.
   `OSError <http://docs.python.org/3/library/exceptions.html#OSError>`__ is
-  raised if *path* does not exist. See
-  `scripts/disk_usage.py <https://github.com/giampaolo/psutil/blob/master/scripts/disk_usage.py>`__
-  script providing an example usage. Starting from
-  `Python 3.3 <http://bugs.python.org/issue12442>`__  this is also
-  available as
+  raised if *path* does not exist.
+  Starting from `Python 3.3 <http://bugs.python.org/issue12442>`__  this is
+  also available as
   `shutil.disk_usage() <http://docs.python.org/3/library/shutil.html#shutil.disk_usage>`__.
-  See
-  `disk_usage.py <https://github.com/giampaolo/psutil/blob/master/scripts/disk_usage.py>`__
-  script providing an example usage.
+  See `disk_usage.py <https://github.com/giampaolo/psutil/blob/master/scripts/disk_usage.py>`__ script providing an example usage.
 
     >>> import psutil
     >>> psutil.disk_usage('/')
     sdiskusage(total=21378641920, used=4809781248, free=15482871808, percent=22.5)
 
+  .. note::
+    UNIX usually reserves 5% of the total disk space for the root user.
+    *total* and *used* fields on UNIX refer to the overall total and used
+    space, whereas *free* represents the space available for the **user** and
+    *percent* represents the **user** utilization.
+    That is why *percent* value may look 5% bigger than what you would expect
+    it to be.
+    Also note that both 4 values match "df" cmdline utility.
+
+  .. versionchanged::
+    4.3.0 *percent* value takes root reserved space into account.
+
 .. function:: disk_io_counters(perdisk=False)
 
   Return system-wide disk I/O statistics as a namedtuple including the
diff --git a/psutil/__init__.py b/psutil/__init__.py
index 1265768d..60ab9c3d 100644
--- a/psutil/__init__.py
+++ b/psutil/__init__.py
@@ -187,7 +187,7 @@ __all__ = [
 ]
 __all__.extend(_psplatform.__extra__all__)
 __author__ = "Giampaolo Rodola'"
-__version__ = "4.2.0"
+__version__ = "4.3.0"
 version_info = tuple([int(num) for num in __version__.split('.')])
 AF_LINK = _psplatform.AF_LINK
 _TOTAL_PHYMEM = None
diff --git a/psutil/_psposix.py b/psutil/_psposix.py
index df5d4780..a564bcc5 100644
--- a/psutil/_psposix.py
+++ b/psutil/_psposix.py
@@ -121,7 +121,12 @@ def wait_pid(pid, timeout=None):
 
 
 def disk_usage(path):
-    """Return disk usage associated with path."""
+    """Return disk usage associated with path.
+    Note: UNIX usually reserves 5% disk space which is not accessible
+    by user. In this function "total" and "used" values reflect the
+    total and used disk space whereas "free" and "percent" represent
+    the "free" and "used percent" user disk space.
+    """
     try:
         st = os.statvfs(path)
     except UnicodeEncodeError:
@@ -137,14 +142,29 @@ def disk_usage(path):
             st = os.statvfs(path)
         else:
             raise
-    free = (st.f_bavail * st.f_frsize)
+
+    # Total space which is only available to root (unless changed
+    # at system level).
     total = (st.f_blocks * st.f_frsize)
-    used = (st.f_blocks - st.f_bfree) * st.f_frsize
-    percent = usage_percent(used, total, _round=1)
+    # Remaining free space usable by root.
+    avail_to_root = (st.f_bfree * st.f_frsize)
+    # Remaining free space usable by user.
+    avail_to_user = (st.f_bavail * st.f_frsize)
+    # Total space being used in general.
+    used = (total - avail_to_root)
+    # Total space which is available to user (same as 'total' but
+    # for the user).
+    total_user = used + avail_to_user
+    # User usage percent compared to the total amount of space
+    # the user can use. This number would be higher if compared
+    # to root's because the user has less space (usually -5%).
+    usage_percent_user = usage_percent(used, total_user, _round=1)
+
     # NB: the percentage is -5% than what shown by df due to
     # reserved blocks that we are currently not considering:
     # https://github.com/giampaolo/psutil/issues/829#issuecomment-223750462
-    return sdiskusage(total, used, free, percent)
+    return sdiskusage(
+        total=total, used=used, free=avail_to_user, percent=usage_percent_user)
 
 
 @memoize