sys_futex  [kernel/futex.c]


Fast userspace locking mechanism.
Provides a method for a program to wait for a value at a given address to change, and a method to wake up anyone waiting on a particular address (while the addresses for the same memory in separate processes may not be equal, the kernel maps them internally so the same memory mapped in different locations will correspond for sys_futex calls). It is typically used to implement the contended case of a lock in shared memory.

Arguments

eax 240
ebx A pointer to an aligned integer which stores the counter.
ecx Operation to execute. It may be one of the following values:
FUTEX_WAIT This operation atomically verifies that the futex address pointed by ebx still contains the value specified by edx, and sleeps awaiting FUTEX_WAKE on this futex address. If the esi argument is non-NULL, it's points to a timespec structure describing the maximum duration of the wait, which is infinite otherwise. The arguments edi and ebp are ignored.
FUTEX_WAKE This operation wakes at most edx processes waiting on this futex address (ie. inside FUTEX_WAIT). The arguments esi, edi and ebp are ignored.
FUTEX_FD To support asynchronous wakeups, this operation associates a file descriptor with a futex. If another process executes a FUTEX_WAKE, the process will receive the signal number that was passed in edx. The calling process must close the returned file descriptor after use. The arguments esi, edi and ebp are ignored.

To prevent race conditions, the caller should test if the futex has been upped after FUTEX_FD returns.
FUTEX_REQUEUE This operation was introduced in order to avoid a "thundering herd" effect when FUTEX_WAKE is used and all processes woken up need to acquire another futex. This call wakes up edx processes, and requires all other waiters on the futex pointed by edi (aligned integer). The arguments esi and ebp are ignored.
FUTEX_CMP_REQUEUE There was a race in the intended use of FUTEX_REQUEUE, so FUTEX_CMP_REQUEUE was introduced. This is similar to FUTEX_REQUEUE, but first checks whether the location pointed by ebx still contains the value specified by edx. If not, an error -EAGAIN is returned. The argument esi is ignored.
FUTEX_WAKE_OP *to be documented*
edx This argument depends on the operation used (ecx). See above.
esi This argument depends on the operation used (ecx). See above.
edi This argument depends on the operation used (ecx). See above.
ebp This argument depends on the operation used (ecx). See above.

Return values

If the system call succeeds the return value is depends on a particular operation:

FUTEX_WAIT Returns 0 if the process was woken by a FUTEX_WAKE call. In case of timeout, ETIMEDOUT is returned. If the futex was not equal to the expected value, the operation returns EWOULDBLOCK. Signals (or other spurious wakeups) cause FUTEX_WAIT to return EINTR.
FUTEX_WAKE Returns the number of processes woken up.
FUTEX_FD Returns the new file descriptor associated with the futex.
FUTEX_REQUEUE Returns the number of processes woken up.
FUTEX_CMP_REQUEUE Returns the number of processes woken up.
FUTEX_WAKE_OP *to be documented*

If the system call fails the return value is one of the following errno values:

-EACCES No read access to futex memory.
-EAGAIN FUTEX_CMP_REQUEUE found an unexpected futex value. (This probably indicates a race; use the safe FUTEX_WAKE now.)
-EFAULT Error in getting timespec information from userspace.
-EINVAL An operation was not defined or error in page alignment.
-ENFILE The system limit on the total number of open files has been reached.

Remarks

n/a

Compatibility

In Linux 2.6.7 a sixth parameter was added.