[patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Vince Weaver]

The Linux 3.14 release adds support for the PERF_FLAG_FD_CLOEXEC flag to
perf_event_open.2

This version tries to clarify that the close-on-exec behavior applies to 
the current file descriptor being created.

The wording is based on the description in kernel commit
a21b0b354d4ac39be691f51c53562e2c24443d9e 
by Yann Droneaud <ydroneaud-RlY5vtjFyJ3QT0dZR+AlfA@public.gmane.org>

Signed-off-by: Vince Weaver <vincent.weaver-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 30a2168..b4a49c4 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -164,6 +164,19 @@ must be passed as the
 parameter.
 cgroup monitoring is available only
 for system-wide events and may therefore require extra permissions.
+.TP
+.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)."
+This flag enables close-on-exec behavior for the created
+event file descriptor, removing it from the list of
+file descriptors inherited across exec.
+Setting this behavior atomically at creation time rather than
+later with
+.BR fctl (2)
+avoids potential race conditions between the current thread and
+another calling
+.BR fork (2)
+then
+.BR execve(2).
 .P
 The
 .I perf_event_attr
--
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

Re: [patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Michael Kerrisk (man-pages)]

On 04/01/2014 11:36 PM, Vince Weaver wrote:
> 
> The Linux 3.14 release adds support for the PERF_FLAG_FD_CLOEXEC flag to
> perf_event_open.2
> 
> This version tries to clarify that the close-on-exec behavior applies to 
> the current file descriptor being created.
> 
> The wording is based on the description in kernel commit
> a21b0b354d4ac39be691f51c53562e2c24443d9e 
> by Yann Droneaud <ydroneaud-RlY5vtjFyJ3QT0dZR+AlfA@public.gmane.org>

Thanks, Vince. 

I applied, and reworked the text to be:

       PERF_FLAG_FD_CLOEXEC (since Linux 3.14).
              This flag enables the close-on-exec flag for the created
              event  file  descriptor,  so that the file descriptor is
              automatically closed on execve(2).  Setting  the  close-
              on-exec  flags at  creation time, rather than later with
              fcntl(2), avoids potential  race  conditions  where  the
              calling  thread  invokes  perf_event_open()  at the same
              time as another thread calls fork(2) then execve(2).

Okay?

Cheers,

Michael

> Signed-off-by: Vince Weaver <vincent.weaver-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>
> 
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index 30a2168..b4a49c4 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -164,6 +164,19 @@ must be passed as the
>  parameter.
>  cgroup monitoring is available only
>  for system-wide events and may therefore require extra permissions.
> +.TP
> +.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)."
> +This flag enables close-on-exec behavior for the created
> +event file descriptor, removing it from the list of
> +file descriptors inherited across exec.
> +Setting this behavior atomically at creation time rather than
> +later with
> +.BR fctl (2)
> +avoids potential race conditions between the current thread and
> +another calling
> +.BR fork (2)
> +then
> +.BR execve(2).
>  .P
>  The
>  .I perf_event_attr
> 


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

Re: [patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Vince Weaver]

On Wed, 2 Apr 2014, Michael Kerrisk (man-pages) wrote:

> I applied, and reworked the text to be:
> 
>        PERF_FLAG_FD_CLOEXEC (since Linux 3.14).
>               This flag enables the close-on-exec flag for the created
>               event  file  descriptor,  so that the file descriptor is
>               automatically closed on execve(2).  Setting  the  close-
>               on-exec  flags at  creation time, rather than later with
>               fcntl(2), avoids potential  race  conditions  where  the
>               calling  thread  invokes  perf_event_open()  at the same
>               time as another thread calls fork(2) then execve(2).
> 
> Okay?

I think the actual race condition being worried about is this:


thread1                   thread2

fd=perf_event_open()         |
      |                    fork()
      |                    exec()
      |                      |
fcntl(CLOEXEC)               |
                          fd has escaped past exec because
                          fcntl didn't happen fast enough

so if you do a

fd=perf_event_open(...,PERF_FLAG_FD_CLOEXEC);

then fd is always CLOEXEC and you don't have a brief window of time
before the fcntl() where the fd can escape.


I'm not sure of a scuccint way to express that though.

Vince

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

Re: [patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Michael Kerrisk (man-pages)]

On 04/02/2014 05:22 PM, Vince Weaver wrote:
> On Wed, 2 Apr 2014, Michael Kerrisk (man-pages) wrote:
> 
>> I applied, and reworked the text to be:
>>
>>        PERF_FLAG_FD_CLOEXEC (since Linux 3.14).
>>               This flag enables the close-on-exec flag for the created
>>               event  file  descriptor,  so that the file descriptor is
>>               automatically closed on execve(2).  Setting  the  close-
>>               on-exec  flags at  creation time, rather than later with
>>               fcntl(2), avoids potential  race  conditions  where  the
>>               calling  thread  invokes  perf_event_open()  at the same
>>               time as another thread calls fork(2) then execve(2).
>>
>> Okay?
> 
> I think the actual race condition being worried about is this:
> 
> 
> thread1                   thread2
> 
> fd=perf_event_open()         |
>       |                    fork()
>       |                    exec()
>       |                      |
> fcntl(CLOEXEC)               |
>                           fd has escaped past exec because
>                           fcntl didn't happen fast enough

Yes, that's the one.

> so if you do a
> 
> fd=perf_event_open(...,PERF_FLAG_FD_CLOEXEC);
> 
> then fd is always CLOEXEC and you don't have a brief window of time
> before the fcntl() where the fd can escape.
> 
> 
> I'm not sure of a scuccint way to express that though.

I think the existing text suffices.

Cheers,

Michael


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

Re: [patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Vince Weaver]

On Fri, 4 Apr 2014, Michael Kerrisk (man-pages) wrote:

> >>               on-exec  flags at  creation time, rather than later with
> >>               fcntl(2), avoids potential  race  conditions  where  the
> >>               calling  thread  invokes  perf_event_open()  at the same
> >>               time as another thread calls fork(2) then execve(2).
> > 
> > I'm not sure of a scuccint way to express that though.
> 
> I think the existing text suffices.

My concern is that it should be 
    "where the calling thread invokes *fcntl()* at the same time..."
rather than
    "where the calling thread invokes *perf_event_open()* at the same time..."

but maybe that's just a small detail, I'm fine with the current text 
otherwise.

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

Re: [patch v2] perf_event_open.2 : document PERF_FLAG_FD_CLOEXEC flag

[Michael Kerrisk (man-pages)]

On 04/07/2014 07:02 AM, Vince Weaver wrote:
> On Fri, 4 Apr 2014, Michael Kerrisk (man-pages) wrote:
> 
>>>>               on-exec  flags at  creation time, rather than later with
>>>>               fcntl(2), avoids potential  race  conditions  where  the
>>>>               calling  thread  invokes  perf_event_open()  at the same
>>>>               time as another thread calls fork(2) then execve(2).
>>>
>>> I'm not sure of a scuccint way to express that though.
>>
>> I think the existing text suffices.
> 
> My concern is that it should be 
>     "where the calling thread invokes *fcntl()* at the same time..."
> rather than
>     "where the calling thread invokes *perf_event_open()* at the same time..."

Fair enough. I've added the words "and fcntl(2)" after invokes  perf_event_open().

Thanks,

Michael.


> but maybe that's just a small detail, I'm fine with the current text 
> otherwise.
> 
> Vince
> 


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