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. |