* [PATCH 1/1] futex.2: do not reference futex.7 semantics
@ 2015-02-17 14:06 Heinrich Schuchardt
[not found] ` <1424181990-13202-1-git-send-email-xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
0 siblings, 1 reply; 2+ messages in thread
From: Heinrich Schuchardt @ 2015-02-17 14:06 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA, Heinrich Schuchardt
The futex.2 system call makes no assumption about the meaning
of the values of a futex.
It may check if the value changes.
The current futex.7 speaks of incrementing and decrementing
a futex. That choice is arbitrary and unwise as overflows may
occur.
If special considerations for the usage of futex.2 have to be made
in a futex.7 example, this should be explained in futex.7
Signed-off-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
---
man2/futex.2 | 33 +--------------------------------
1 file changed, 1 insertion(+), 32 deletions(-)
diff --git a/man2/futex.2 b/man2/futex.2
index 6c02da7..0ea7db2 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -68,16 +68,6 @@ When a futex operation did not finish uncontended in user space, a
call needs to be made to the kernel to arbitrate.
Arbitration can either mean putting the caller
to sleep or, conversely, waking a waiting process or thread.
-.PP
-Callers of
-.BR futex ()
-are expected to adhere to the semantics described in
-.BR futex (7).
-As these semantics involve writing nonportable assembly instructions
-(see the example library referred to in SEE ALSO),
-this in turn probably means that most users will in fact be
-library authors and not general application developers.
-.\"
.SS Arguments
The
.I uaddr
@@ -229,18 +219,6 @@ The arguments
and
.I val3
are ignored.
-
-For
-.BR futex (7),
-this call is executed if decrementing the count gave a negative value
-(indicating contention),
-and will sleep until another process or thread releases
-the futex and executes the
-.B FUTEX_WAKE
-operation.
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
.TP
.BR FUTEX_WAKE " (since Linux 2.6.0)"
.\" Strictly speaking, since Linux 2.5.x
@@ -266,15 +244,6 @@ The arguments
and
.I val3
are ignored.
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH 1/1] futex.2: do not reference futex.7 semantics
[not found] ` <1424181990-13202-1-git-send-email-xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
@ 2015-03-03 8:01 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 2+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-03-03 8:01 UTC (permalink / raw)
To: Heinrich Schuchardt
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w,
linux-man-u79uwXL29TY76Z2rM5mHXA, Torvald Riegel
Hello Heinrich,
On 02/17/2015 03:06 PM, Heinrich Schuchardt wrote:
> The futex.2 system call makes no assumption about the meaning
> of the values of a futex.
> It may check if the value changes.
>
> The current futex.7 speaks of incrementing and decrementing
> a futex. That choice is arbitrary and unwise as overflows may
> occur.
>
> If special considerations for the usage of futex.2 have to be made
> in a futex.7 example, this should be explained in futex.7
A recent patch by Torvald Riegel also proposed many of the same changes, and
I've applied that patch. Oone piece was not quite covered by Torvald's
patch see my comment below.
> Signed-off-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> ---
> man2/futex.2 | 33 +--------------------------------
> 1 file changed, 1 insertion(+), 32 deletions(-)
>
> diff --git a/man2/futex.2 b/man2/futex.2
> index 6c02da7..0ea7db2 100644
> --- a/man2/futex.2
> +++ b/man2/futex.2
> @@ -68,16 +68,6 @@ When a futex operation did not finish uncontended in user space, a
> call needs to be made to the kernel to arbitrate.
> Arbitration can either mean putting the caller
> to sleep or, conversely, waking a waiting process or thread.
> -.PP
> -Callers of
> -.BR futex ()
> -are expected to adhere to the semantics described in
> -.BR futex (7).
> -As these semantics involve writing nonportable assembly instructions
> -(see the example library referred to in SEE ALSO),
> -this in turn probably means that most users will in fact be
> -library authors and not general application developers.
> -.\"
> .SS Arguments
> The
> .I uaddr
> @@ -229,18 +219,6 @@ The arguments
> and
> .I val3
> are ignored.
> -
> -For
> -.BR futex (7),
> -this call is executed if decrementing the count gave a negative value
> -(indicating contention),
> -and will sleep until another process or thread releases
> -the futex and executes the
> -.B FUTEX_WAKE
> -operation.
> -.\"
> -.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
> -.\"
> .TP
> .BR FUTEX_WAKE " (since Linux 2.6.0)"
> .\" Strictly speaking, since Linux 2.5.x
> @@ -266,15 +244,6 @@ The arguments
> and
> .I val3
> are ignored.
> -
> -For
> -.BR futex (7),
> -this is executed if incrementing the count showed that there were waiters,
> -.\" FIXME How does "incrementing the count showed that there were waiters"?
> -once the futex value has been set to 1 (indicating that it is available).
> -.\"
> -.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
> -.\"
> .TP
> .BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)"
> .\" Strictly speaking, from Linux 2.5.x to 2.6.25
> @@ -304,7 +273,7 @@ and
> are ignored.
>
> To prevent race conditions, the caller should test if the futex has
> -been upped after
> +been changed after
Torvald also questioned this sentence; currently it has a FIXME
asking whether maybe it should just be removed altogether.
Thanks,
Michael
> .B FUTEX_FD
> returns.
>
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2015-03-03 8:01 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-02-17 14:06 [PATCH 1/1] futex.2: do not reference futex.7 semantics Heinrich Schuchardt
[not found] ` <1424181990-13202-1-git-send-email-xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
2015-03-03 8:01 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.