[PATCH] epoll_ctl.2: replace input flag footnotes with a list section

[PATCH] epoll_ctl.2: replace input flag footnotes with a list section

[наб]

[-- Attachment #1: Type: text/plain, Size: 2524 bytes --]

This is shorter, clearly separates the events from the flags,
and more consistent (cf. EPOLLEXCLUSIVE which has a different message
than the rest)

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/epoll_ctl.2 | 33 +++------------------------------
 1 file changed, 3 insertions(+), 30 deletions(-)

diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
index ec31cac72..c9f9649a5 100644
--- a/man2/epoll_ctl.2
+++ b/man2/epoll_ctl.2
@@ -156,6 +156,9 @@ Note that when reading from a channel such as a pipe or a stream socket,
 this event merely indicates that the peer closed its end of the channel.
 Subsequent reads from the channel will return 0 (end of file)
 only after all outstanding data in the channel has been consumed.
+.PP
+And one of the following input flags, which are never returned by
+.BR epoll_wait (2):
 .TP
 .B EPOLLET
 Requests edge-triggered notification for the associated file descriptor.
@@ -166,13 +169,6 @@ See
 .BR epoll (7)
 for more detailed information about edge-triggered and
 level-triggered notification.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 Requests one-shot notification for the associated file descriptor.
@@ -187,13 +183,6 @@ The user must call
 with
 .B EPOLL_CTL_MOD
 to rearm the file descriptor with a new event mask.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLWAKEUP " (since Linux 3.5)"
 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
@@ -222,13 +211,6 @@ or the clearing of
 for the event file descriptor with
 .BR EPOLL_CTL_MOD .
 See also BUGS.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
 Sets an exclusive wakeup mode for the epoll file descriptor that is being
@@ -299,15 +281,6 @@ and specifies the target file descriptor
 as an epoll instance will likewise fail.
 The error in all of these cases is
 .BR EINVAL .
-.IP
-The
-.BR EPOLLEXCLUSIVE
-flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .SH RETURN VALUE
 When successful,
 .BR epoll_ctl ()
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] epoll_ctl.2: replace input flag footnotes with a list section

[Alejandro Colomar (man-pages)]

Hi, наб!

On 1/13/22 03:27, наб wrote:
> This is shorter, clearly separates the events from the flags,
> and more consistent (cf. EPOLLEXCLUSIVE which has a different message
> than the rest)
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man2/epoll_ctl.2 | 33 +++------------------------------
>   1 file changed, 3 insertions(+), 30 deletions(-)
> 
> diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
> index ec31cac72..c9f9649a5 100644
> --- a/man2/epoll_ctl.2
> +++ b/man2/epoll_ctl.2
> @@ -156,6 +156,9 @@ Note that when reading from a channel such as a pipe or a stream socket,
>   this event merely indicates that the peer closed its end of the channel.
>   Subsequent reads from the channel will return 0 (end of file)
>   only after all outstanding data in the channel has been consumed.
> +.PP
> +And one of the following input flags, which are never returned by

This sentence (as I understand it) is a continuation of _"The  events 
member of the epoll_event structure is a bit mask composed by ORing 
together zero or more of the following available event types:"_, right?

So, the bitmask is composed by _zero or more_ event types, and _exactly 
one_ input flags?  Just asking, I don't know the syscall.  I think we 
should mix both sentences into a single one where it is very clear what 
the bitmask is composed of.  And then a simple introduction sentence 
like: "The available event types are:"  and then below the event types 
another similar one for introducing the input flags.

Your thoughts?

Thanks,

Alex


-- 
Alejandro Colomar
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH v2] epoll_ctl.2: replace input flag footnotes with a list section

[наб]

[-- Attachment #1: Type: text/plain, Size: 3122 bytes --]

This is shorter, clearly separates the events from the flags,
and more consistent (cf. EPOLLEXCLUSIVE which has a different message
than the rest)

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
You're right, and in the 3am curse I missed that I specified >=1
instead of >=0. Rewrote that as you suggested: one sentence at the top,
and two lists with short headings referencing it.

 man2/epoll_ctl.2 | 39 +++++++--------------------------------
 1 file changed, 7 insertions(+), 32 deletions(-)

diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
index ec31cac72..de6bcfb33 100644
--- a/man2/epoll_ctl.2
+++ b/man2/epoll_ctl.2
@@ -106,8 +106,11 @@ The
 .I events
 member of the
 .I epoll_event
-structure is a bit mask composed by ORing together zero or more of
-the following available event types:
+structure is a bit mask composed by ORing together zero or more event types,
+returned by
+.BR epoll_wait (2),
+and input flags, which affect its behaviour, but aren't returned.
+The available event types are:
 .TP
 .B EPOLLIN
 The associated file is available for
@@ -156,6 +159,8 @@ Note that when reading from a channel such as a pipe or a stream socket,
 this event merely indicates that the peer closed its end of the channel.
 Subsequent reads from the channel will return 0 (end of file)
 only after all outstanding data in the channel has been consumed.
+.PP
+And the available input flags are:
 .TP
 .B EPOLLET
 Requests edge-triggered notification for the associated file descriptor.
@@ -166,13 +171,6 @@ See
 .BR epoll (7)
 for more detailed information about edge-triggered and
 level-triggered notification.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLONESHOT " (since Linux 2.6.2)"
 Requests one-shot notification for the associated file descriptor.
@@ -187,13 +185,6 @@ The user must call
 with
 .B EPOLL_CTL_MOD
 to rearm the file descriptor with a new event mask.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLWAKEUP " (since Linux 3.5)"
 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
@@ -222,13 +213,6 @@ or the clearing of
 for the event file descriptor with
 .BR EPOLL_CTL_MOD .
 See also BUGS.
-.IP
-This flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .TP
 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
 Sets an exclusive wakeup mode for the epoll file descriptor that is being
@@ -299,15 +283,6 @@ and specifies the target file descriptor
 as an epoll instance will likewise fail.
 The error in all of these cases is
 .BR EINVAL .
-.IP
-The
-.BR EPOLLEXCLUSIVE
-flag is an input flag for the
-.I event.events
-field when calling
-.BR epoll_ctl ();
-it is never returned by
-.BR epoll_wait (2).
 .SH RETURN VALUE
 When successful,
 .BR epoll_ctl ()
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] epoll_ctl.2: replace input flag footnotes with a list section

[Alejandro Colomar (man-pages)]

On 1/13/22 16:14, наб wrote:
> This is shorter, clearly separates the events from the flags,
> and more consistent (cf. EPOLLEXCLUSIVE which has a different message
> than the rest)
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
> You're right, and in the 3am curse I missed that I specified >=1
> instead of >=0. Rewrote that as you suggested: one sentence at the top,
> and two lists with short headings referencing it.


Patch applied, наб.

Thanks,

Alex

> 
>  man2/epoll_ctl.2 | 39 +++++++--------------------------------
>  1 file changed, 7 insertions(+), 32 deletions(-)
> 
> diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2
> index ec31cac72..de6bcfb33 100644
> --- a/man2/epoll_ctl.2
> +++ b/man2/epoll_ctl.2
> @@ -106,8 +106,11 @@ The
>  .I events
>  member of the
>  .I epoll_event
> -structure is a bit mask composed by ORing together zero or more of
> -the following available event types:
> +structure is a bit mask composed by ORing together zero or more event types,
> +returned by
> +.BR epoll_wait (2),
> +and input flags, which affect its behaviour, but aren't returned.
> +The available event types are:
>  .TP
>  .B EPOLLIN
>  The associated file is available for
> @@ -156,6 +159,8 @@ Note that when reading from a channel such as a pipe or a stream socket,
>  this event merely indicates that the peer closed its end of the channel.
>  Subsequent reads from the channel will return 0 (end of file)
>  only after all outstanding data in the channel has been consumed.
> +.PP
> +And the available input flags are:
>  .TP
>  .B EPOLLET
>  Requests edge-triggered notification for the associated file descriptor.
> @@ -166,13 +171,6 @@ See
>  .BR epoll (7)
>  for more detailed information about edge-triggered and
>  level-triggered notification.
> -.IP
> -This flag is an input flag for the
> -.I event.events
> -field when calling
> -.BR epoll_ctl ();
> -it is never returned by
> -.BR epoll_wait (2).
>  .TP
>  .BR EPOLLONESHOT " (since Linux 2.6.2)"
>  Requests one-shot notification for the associated file descriptor.
> @@ -187,13 +185,6 @@ The user must call
>  with
>  .B EPOLL_CTL_MOD
>  to rearm the file descriptor with a new event mask.
> -.IP
> -This flag is an input flag for the
> -.I event.events
> -field when calling
> -.BR epoll_ctl ();
> -it is never returned by
> -.BR epoll_wait (2).
>  .TP
>  .BR EPOLLWAKEUP " (since Linux 3.5)"
>  .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
> @@ -222,13 +213,6 @@ or the clearing of
>  for the event file descriptor with
>  .BR EPOLL_CTL_MOD .
>  See also BUGS.
> -.IP
> -This flag is an input flag for the
> -.I event.events
> -field when calling
> -.BR epoll_ctl ();
> -it is never returned by
> -.BR epoll_wait (2).
>  .TP
>  .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
>  Sets an exclusive wakeup mode for the epoll file descriptor that is being
> @@ -299,15 +283,6 @@ and specifies the target file descriptor
>  as an epoll instance will likewise fail.
>  The error in all of these cases is
>  .BR EINVAL .
> -.IP
> -The
> -.BR EPOLLEXCLUSIVE
> -flag is an input flag for the
> -.I event.events
> -field when calling
> -.BR epoll_ctl ();
> -it is never returned by
> -.BR epoll_wait (2).
>  .SH RETURN VALUE
>  When successful,
>  .BR epoll_ctl ()

-- 
Alejandro Colomar
Linux man-pages maintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/