Verified behavior on Linux machine. I'm not sure if we should document this, however, because it's not portable at all.

Is there any reason why both OS's cannot perform in the same manner?

In checking filestat.c (/* $Id: filestat.c,v 1.160 2007/02/26 20:35:41 tony2001 Exp $ */), for OS2, only the first character of the path is used (char drive = path[0] & 95;).

Linux accepts a full path.
OS2 accepts a full path, but only uses the drive part.
Windows doesn't accept a full path, but could by checking to see if the supplied path is a file (php_stat() would do that) and if so, chop off the filename and try that.

Alternatively, only do the chopping part if the original test fails.

OK, then please  - either  -  

(1) fix the function to make Linux implementation behave the same way as Windows (eg. by adding a check to stop Linux users supplying a filename). 

- or - 

(2) add the following text (instead of my previous suggestion): 

"Given a file name instead of a directory, the behaviour of the function is unspecified and may differ between operating systems and PHP versions. "

Please advise your prefererence, I'm happy to raise a bug against the implementation if required.

OK, then please  - either  -  

(1) fix the function to make Linux implementation behave the same way as Windows (eg. by adding a check to stop Linux users supplying a filename). 

- or - 

(2) add the following text (instead of my previous suggestion): 

"Given a file name instead of a directory, the behaviour of the function is unspecified and may differ between operating systems and PHP versions. "

Please advise your preference, I'm happy to raise a bug against the implementation if required.

I would raise a bug as 2 of the 3 os's which have different implementations of this function support the supplying of a filename.
Only windows has (is?) the problem.

And it makes sense to ask how much space in on the drive holding a file.

Editing submission to change bug category from 'Documentation' to 'Filesystem function related', and to update Summary line.

As per preceding discussion, please change implementation of function disk_free_space()so that the behaviour is the same for Linux, OS2 and Windows. Ideal result would be for all 3 OS's to accept a directory or filename as input, ref. rquadling comment, 29 May 10:35am. 

If this is implemented, then please update doc also: 

"Given a string containing a directory <insert: "or filename">, this function will return the number of bytes available in the corresponding filesystem or disk partition.  "

Reclassified as feature request.
At the moment I see no reasons to apply some hacks to make it work on Win32 the way it works on decent platforms.

Well it would improve the functionality for Win32 users and provide useful behavioural consistency across platforms. 
Otherwise, to achieve consistency, we're back to 

(1) limit Linux and OS2 behaviour to give error when filename supplied
- or -
(2) change doc to cater for discrepancies in behaviour between OS's

as per tayloj1 comment, 29 May 11:09am

Changing this back to a documentation problem.

Here's the suggested patch: 

Index: en/reference/filesystem/functions/disk-free-space.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/filesystem/functions/disk-free-space.xml,v
retrieving revision 1.7
diff -u -r1.7 disk-free-space.xml
--- en/reference/filesystem/functions/disk-free-space.xml	20 Jun 2007 22:24:27 -0000	1.7
+++ en/reference/filesystem/functions/disk-free-space.xml	21 Jun 2007 16:57:49 -0000
@@ -17,6 +17,10 @@
    number of bytes available on the corresponding filesystem or disk
    partition.
   </para>
+  <para>
+   Given a file name instead of a directory, the behaviour of the function 
+   is unspecified and may differ between operating systems and PHP versions.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.