Skip to content
AntinomieAntinomie0.8.0 docs

futex

Partial in Antinomie 0.7.0 · Syscall list

Synopsis

Section titled “Synopsis”
long futex(u32 *uaddr, int op, u32 val, const struct __kernel_timespec *utime, u32 *uaddr2, u32 val3);
Number (x86-64) 202
ABI common
Kernel entry point sys_futex

This is the raw kernel prototype from the pinned Linux 6.12.94 schema, not the libc wrapper.

Description

Section titled “Description”

Low-level wait/wake primitive on a 32-bit word in user memory, the basis of locks, with many operations selected by a command.

Arguments

Section titled “Arguments”
Name Type Meaning
uaddr (arg0) u32 * Address of a 32-bit futex word.
op (arg1) int Futex operation (FUTEX_WAIT, FUTEX_WAKE, …) with optional FUTEX_PRIVATE_FLAG and FUTEX_CLOCK_REALTIME.
val (arg2) u32 Expected word value for waits, or the number of waiters for wakes.
utime (arg3) const struct __kernel_timespec * Pointer to a timeout, for operations that wait.
uaddr2 (arg4) u32 * Second futex address, for requeue operations.
val3 (arg5) u32 Third futex value.

Return value

Section titled “Return value”

On success: an operation-specific value.

In an Antinomie trace the Return column and the ret filter field show the raw kernel return value. On failure that is the negative errno, for example -2 for ENOENT, not the -1 plus errno that the libc wrapper gives. syscall.errno holds the positive errno and syscall.success is false.

Common errors

Section titled “Common errors”
Raw return Name Meaning
-11 EAGAIN The call would block, or a resource is temporarily unavailable.
-4 EINTR The call was interrupted by a signal.
-110 ETIMEDOUT The operation timed out.

Man page

Section titled “Man page”

futex(2) on man7.org

Captured by Antinomie

Section titled “Captured by Antinomie”

Coverage mark: Partial. Known futex operations decode the futex words and timeouts. An unknown operation records a futex.unknown_selector “no decoder” gap.

Every call is recorded as an Entry record (the six argument words and the pointees copied at entry) and an Exit record (the return value and the pointees copied at exit).

Arguments

Section titled “Arguments”
Argument When How Recorded field key Condition
uaddr (arg0) Entry the pointer itself, as a raw word args.0, args.raw[0]
↳ pointee Entry the 32-bit futex word arg0.futex.observed the operation is a known one; at exit only for operations that modify it and when result is 0 or greater
op (arg1) Entry raw scalar word; Syscall Trace also decodes it into flag names (futex group), listing unknown bits separately args.1, args.op
val (arg2) Entry raw scalar word args.2, args.val
utime (arg3) Entry the pointer itself, as a raw word args.3, args.raw[3]
↳ pointee Entry structure timespec arg3.timeout wait and lock operations
uaddr2 (arg4) Entry the pointer itself, as a raw word args.4, args.raw[4]
↳ pointee Entry the second 32-bit futex word arg4.futex.observed requeue, wake-op and requeue-PI operations
val3 (arg5) Entry raw scalar word args.5, args.val3

Filter fields

Section titled “Filter fields”
  • Result: ret, syscall.errno, syscall.success, syscall.duration_ns.
  • Argument words: args.uaddr (arg0), args.op (arg1), args.val (arg2), args.utime (arg3), args.uaddr2 (arg4), args.val3 (arg5); args.0 to args.5 by position.
  • Structure u32 behind uaddr (arg0): args.uaddr.<member> for value.
  • Structure timespec[2] behind utime (arg3): args.utime.<member> for tv_nsec, tv_sec.
  • Structure u32 behind uaddr2 (arg4): args.uaddr2.<member> for value.

See Syscall Trace filter for the full syntax.

Known gaps

Section titled “Known gaps”
  • An unknown operation records futex.unknown_selector with the “no decoder” status.
  • See the coverage mark above for the code paths that record a gap.

For what the capture statuses mean, see Capture statuses. For what is never recorded, see Known gaps.