Note that dio_fcntl() of the "Direct IO" extension can successfully exclusively 
lock the file, but this shouldn't be considered as a workaround as it's not always 
possible to install extensions.

If flock() couldn't be modified for backward compatibility reasons, options could 
be added to alter its behaviour, or a new call lockf() would be welcome too.

The key difference between Python and PHP here is that Python always uses fcntl() internally, whereas PHP will use flock() if it's available (which it obviously is on Linux) and will only fall back to fcntl() if it's not. flock() will never create a mandatory lock, so the manual page is wrong, which I'm pretty sure is my fault. Mea culpa.

We can probably fix this by switching to preferring fcntl() within our flock() function as Python does, since that's actually the more useful behaviour, but that would be a (mild) BC break in how flock() behaves in practice — although it would actually bring it into line with what's documented.

The options I see are:

1. Change the behaviour of flock() as described above to prefer fcntl().
2. Add a new lockf() function, as suggested.
3. Just bite the bullet and expose fcntl() as a PHP function on POSIX platforms.
4. Do nothing and update the manual. :)

Does anyone have any thoughts? I'm happy to do the donkey work, but am not really sure on the best way to proceed.

I like 3 :)

change the behavior of flock will intruduce a  visible bc break

A fifth option is to pull the "Direct IO" extension into the mainline.
http://pecl.php.net/package/dio

This extension already expose fcntl() as well as a few other low-level
POSIX routines, and have some amount of testing as it's in its fourth
version already (though it's said to be in beta state)

My worry there is that dio resources are (as I recall, anyway) completely distinct from normal file resources, so you couldn't fopen() a file and then dio_fcntl() it: it's all or nothing.

You're right, dio is a plain inteface to the underlying C function hence exposing 
real file descriptors (integers).

That's also what Python does: it exposes two different types of file objects: 
standard file objects via the builtin open() and file descriptors via os.open()

Is that is feasible with php?

That's true, but they're still somewhat interchangeable in Python — higher level file objects returned by open() work with fcntl methods. That wouldn't be the case if we bundled dio without further work.

You're right, Python is smart and the trick is simple: fnctl module functions 
are coded such that they detect the type of the object they're given as 
argument. If it's an integer they assume it is a file descriptor otherwise they 
call its fileno() method to retrieve the file descriptor integer.

So it's a matter of adding your own fileno() method to the PHP standard file 
object and making the dio_* routines calling it, when not provided with an 
integer.

Does that makes sense to you?

It's a suggestion, at the end of the day it's your decision of how to handle 
this issue, even though it seems to, I'm actually not pushing to get direct io 
integrated at any cost (I don't have any stake) but I just feel it's the way to 
go.

I am puzzled, what can the current behavior be possibly used for?

If the lock is not really locking (and it does not -- neither on Linux nor on FreeBSD), then why bother with it at all? And if nobody bothers, then why not fix it properly?

BTW, at least, on BSD the different locking mechanisms create compatible locks:

     The flock(), fcntl(2), and lockf(3) locks are compatible.
     Processes using different locking interfaces can cooperate
     over the same file safely. However, only one of such interfaces
     should be used within the same process.  If a file is locked by
     a process through flock(), any record within the file will be
     seen as locked from the viewpoint of another process using
     fcntl(2) or lockf(3), and vice versa.

I hope we're still speaking of MANDATORY locks (the ones provided by "mount -o 
mand") and not standard file locks? Other locks (advisory) behave as expected.

So what's the solution you chose to allow locking a file with a MANDATORY lock 
using PHP?

This is my test case:

<?php
function warn($message) {
	global $argv;
	fputs(STDERR, "$argv[0]: $message\n");
}

function add_dir($dir) {
	$lname = $dir . '/distd.pid';
	$lock = fopen($lname, 'c+');
	if (!$lock) {
		warn("$lname: can not open");
		return FALSE;
	}
	if (!flock($lock, LOCK_EX|LOCK_NB)) {
		warn("$lname: can not lock");
		return FALSE;
	}
	warn(getmypid() . " ". date('H:i:s') . " $lname successfully locked");
	return (fputs($lock, getmypid() . "\n". gethostname() . "\n") != FALSE);
}

date_default_timezone_set('America/New_York');
add_dir('/tmp');
sleep(3);
warn(getmypid() . " ". date('H:i:s') . " exiting in peace");
?>

Running TWO of the above in parallel:
% ( php t.php < /dev/null & php t.php < /dev/null )  >& l
I see BOTH of them claim to have "successfully" gotten the lock:
% cat l
[1] 26815
t.php: 26815 21:48:34 /tmp/distd.pid successfully locked
t.php: 26814 21:48:34 /tmp/distd.pid successfully locked
t.php: 26815 21:48:37 exiting in peace
t.php: 26814 21:48:37 exiting in peace

I appreciate your code and efforts but please stay focus on the topic: MANDATORY 
locks only. The issue is that PHP doesn't provide a standard way of triggering a 
mandatory lock.

MANDATORY locks are specific to Linux and occurs on a volume that is mounted 
with the "-o mand" mount flag.
ADVISORY locks exist on any system via flock() or lockf() calls and are not the 
subject of this thread.

Now I'm speaking to PHP developpers: how do you plan to fill in the gap?

Thanks

Eric, I'm confused. Are you saying, the problem I am illustrating with my test case is different? Should I file a separate bug-report?