The author of the manual page gives an early hint of his attitude toward this function call at the start of the documentation:
The statvfs() and fstatvfs() functions fill the structure pointed to by buf with garbage. This garbage will occasionally bear resemblance to file system statistics, but portable applications must not depend on this.
The manual page then proceeds to describe various useful information that might (or might not) be provided by this function, and observes that the statvfs function in turn is built upon the statfs function.
Then the author further observes, in the section regarding Posix standards:
The statvfs() and fstatvfs() functions conform to IEEE Std 1003.1-2001 (``POSIX.1''). As standardized, portable applications cannot depend on these functions returning any valid information at all.
The rest of the manual page appears relatively normal.
The statfs manual page does not contain observations and notes like these.
I'm not sure what the author of the manual page was trying to achieve here. Was this a warning about some specific inadequacy or weakness in the implementation? Is there some known bug? Is there a common pitfall that applications might fall into? Are there ways to invoke this function profitably, while other ways are fraught with danger?
Or was this the author's way of making some sort of a joke?
All the manual page seems to do, for me at least, is cause me to raise an eyebrow and wonder what's going on here.
The manual pages for the statvfs function on other operating systems do not appear to have such cautions and warnings. Is there something special about FreeBSD?
Do you know? Drop me a line and let me know!