[patch] perf_event_open.2 -- expand ERRORS section

[patch] perf_event_open.2 -- expand ERRORS section

[Vince Weaver]

Expand the perf_event_open.2 ERRORS section to be more comprehensive.

These were determined both by code inspection and by writing a large
number of test programs.

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 42146a9..cd7f60d 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -2362,6 +2362,10 @@ returns the new file descriptor, or \-1 if an error occurred
 .I errno
 is set appropriately).
 .SH ERRORS
+The errors returned by
+.BR perf_event_open ()
+can be inconsistent, and may
+vary across processor architectures and performance monitoring units.
 .TP
 .B E2BIG
 Returned if the perf_event_attr
@@ -2378,8 +2382,68 @@ is returned, the perf_event_attr
 field is overwritten by the kernel to be the size of the structure
 it was expecting.
 .TP
+.B EACCES
+Returned when the requested event requires root permissions
+(or a more permissive perf_event paranoid setting).
+Some common causes are attaching to a process owned by a different user,
+monitoring all processes on a given cpu,
+or not setting exclude_kernel and the paranoid setting requires it.
+.TP
+.B EBADF
+Returned if the
+.I group_fd
+file descriptor is not valid, or, if PERF_FLAG_PID_CGROUP is set,
+the cgroup file descriptor in
+.I pid
+is not valid.
+.TP
+.B EFAULT
+Returned if the
+.I attr
+pointer points at an invalid memory address.
+.TP
 .B EINVAL
-Returned if the specified event is not available.
+Returned if the specified event is invalid.
+There are many possible reasons for this.
+A not-exhaustive list:
+.I sample_freq
+higher than the maximum setting,
+the
+.I cpu
+to monitor does not exist,
+.I read_format
+is out of range,
+.I sample_type
+is out of range,
+the
+.I flags
+value is out of range,
+.I exclusive
+or
+.I pinned
+set and the event is not a group leader,
+the event
+.I config
+values are out of range or set reserved bits,
+the generic event selected is not supported, or
+there is not enough room to add the selected event.
+.TP
+.B EMFILE
+Each opened event uses one file descriptor.
+If a large number of events are opened the per-user file
+descriptor limit (often 1024) will be hit and no more
+events can be created.
+.TP
+.B ENODEV
+Returned when the event involves a feature not supported
+by the current cpu.
+.TP
+.B ENOENT
+Returned if the
+.I type
+setting is not valid.
+Also returned for
+some unsupported generic events.
 .TP
 .B ENOSPC
 Prior to Linux 3.3, if there was not enough room for the event,
@@ -2388,8 +2452,30 @@ was returned.
 Linus did not like this, and this was changed to
 .BR EINVAL .
 .B ENOSPC
-is still returned if you try to read results into
-too small of a buffer.
+is still returned if you try to add more breakpoint events
+than supported by hardware.
+.TP
+.B ENOSYS
+Returned if
+.B PERF_SAMPLE_STACK_USER
+is set in
+.I sample_type
+and it is not supported by hardware.
+.TP
+.B EOPNOTSUPP
+Returned if an event requiring a specific hardware feature is
+requested but there is no hardware support.
+This includes requesting low-skid events if not supported,
+branch tracing if it is not available, sampling if no PMU
+interrupt is available, and branch stacks for software events.
+.TP
+.B EPERM
+Returned if sufficient permissions not available to create the event.
+This includes attempting to set a breakpoint on a kernel address
+and setting a ftrace function trace tracepoint.
+.TP
+.B ESRCH
+Returned if attempting to attach to a process that does not exist.
 .SH VERSION
 .BR perf_event_open ()
 was introduced in Linux 2.6.31 but was called
--
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] perf_event_open.2 -- expand ERRORS section

[Michael Kerrisk (man-pages)]

Hi Vince,

I've applied this, but have a question or two below.

On 04/07/2014 06:56 AM, Vince Weaver wrote:
> 
> Expand the perf_event_open.2 ERRORS section to be more comprehensive.
> 
> These were determined both by code inspection and by writing a large
> number of test programs.
> 
> 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 42146a9..cd7f60d 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -2362,6 +2362,10 @@ returns the new file descriptor, or \-1 if an error occurred
>  .I errno
>  is set appropriately).
>  .SH ERRORS
> +The errors returned by
> +.BR perf_event_open ()
> +can be inconsistent, and may
> +vary across processor architectures and performance monitoring units.
>  .TP
>  .B E2BIG
>  Returned if the perf_event_attr
> @@ -2378,8 +2382,68 @@ is returned, the perf_event_attr
>  field is overwritten by the kernel to be the size of the structure
>  it was expecting.
>  .TP
> +.B EACCES
> +Returned when the requested event requires root permissions
> +(or a more permissive perf_event paranoid setting).
> +Some common causes are attaching to a process owned by a different user,
> +monitoring all processes on a given cpu,

I don't understand that line above. Could you clarify. How is
"monitoring all processes on a given given cpu" a cause of 
this error."

> +or not setting exclude_kernel and the paranoid setting requires it.
> +.TP
> +.B EBADF
> +Returned if the
> +.I group_fd
> +file descriptor is not valid, or, if PERF_FLAG_PID_CGROUP is set,
> +the cgroup file descriptor in
> +.I pid
> +is not valid.
> +.TP
> +.B EFAULT
> +Returned if the
> +.I attr
> +pointer points at an invalid memory address.
> +.TP
>  .B EINVAL
> -Returned if the specified event is not available.
> +Returned if the specified event is invalid.
> +There are many possible reasons for this.
> +A not-exhaustive list:
> +.I sample_freq
> +higher than the maximum setting,
> +the
> +.I cpu
> +to monitor does not exist,
> +.I read_format
> +is out of range,
> +.I sample_type
> +is out of range,
> +the
> +.I flags
> +value is out of range,
> +.I exclusive
> +or
> +.I pinned
> +set and the event is not a group leader,
> +the event
> +.I config
> +values are out of range or set reserved bits,
> +the generic event selected is not supported, or
> +there is not enough room to add the selected event.
> +.TP
> +.B EMFILE
> +Each opened event uses one file descriptor.
> +If a large number of events are opened the per-user file
> +descriptor limit (often 1024) will be hit and no more
> +events can be created.
> +.TP
> +.B ENODEV
> +Returned when the event involves a feature not supported
> +by the current cpu.
> +.TP
> +.B ENOENT
> +Returned if the
> +.I type
> +setting is not valid.
> +Also returned for
> +some unsupported generic events.
>  .TP
>  .B ENOSPC
>  Prior to Linux 3.3, if there was not enough room for the event,
> @@ -2388,8 +2452,30 @@ was returned.
>  Linus did not like this, and this was changed to
>  .BR EINVAL .
>  .B ENOSPC
> -is still returned if you try to read results into
> -too small of a buffer.
> +is still returned if you try to add more breakpoint events
> +than supported by hardware.
> +.TP
> +.B ENOSYS
> +Returned if
> +.B PERF_SAMPLE_STACK_USER
> +is set in
> +.I sample_type
> +and it is not supported by hardware.
> +.TP
> +.B EOPNOTSUPP
> +Returned if an event requiring a specific hardware feature is
> +requested but there is no hardware support.
> +This includes requesting low-skid events if not supported,
> +branch tracing if it is not available, sampling if no PMU
> +interrupt is available, and branch stacks for software events.
> +.TP
> +.B EPERM
> +Returned if sufficient permissions not available to create the event.
> +This includes attempting to set a breakpoint on a kernel address
> +and setting a ftrace function trace tracepoint.

I don't understand the previous line. Why is "setting a ftrace function 
trace tracepoint" a cause of EPERM?

> +.TP
> +.B ESRCH
> +Returned if attempting to attach to a process that does not exist.
>  .SH VERSION
>  .BR perf_event_open ()
>  was introduced in Linux 2.6.31 but was called

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] perf_event_open.2 -- expand ERRORS section

[Vince Weaver]

On Thu, 10 Apr 2014, Michael Kerrisk (man-pages) wrote:

> I've applied this, but have a question or two below.
> 
> On 04/07/2014 06:56 AM, Vince Weaver wrote:

> > +.B EACCES
> > +Returned when the requested event requires root permissions
> > +(or a more permissive perf_event paranoid setting).
> > +Some common causes are attaching to a process owned by a different user,
> > +monitoring all processes on a given cpu,
> 
> I don't understand that line above. Could you clarify. How is
> "monitoring all processes on a given given cpu" a cause of 
> this error."

If you configure to monitor all processes by setting cpu=-1 then you
are potentially measuring processes belonging to other users, which
would be a security leak.  So you get EACCES.

> > +.B EPERM
> > +Returned if sufficient permissions not available to create the event.
> > +This includes attempting to set a breakpoint on a kernel address
> > +and setting a ftrace function trace tracepoint.
> 
> I don't understand the previous line. Why is "setting a ftrace function 
> trace tracepoint" a cause of EPERM?

Would it be cleared if it were "ftrace function-trace tracepoint"?

This is a recent change.  It was a lockup bug we found, it turns out
that letting an average user set function-trace tracepoints can cause
problems, if for example they set a tracepoint in an interrupt handler
that causes an overflow that triggers an interrupt you get a recursive 
loop.  The easy solution was to just make function-trace tracepoints
root-only (meaning that yes, root can crash the kernel easily using 
perf_event_open() ).

Now why it returns EPERM not EACCES, I don't know.

I can try to update the text in these two cases to be a bit more clear.
I'm never sure how much extra details like this are suitable without
overwhelming the document with extraneous details.

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] perf_event_open.2 -- expand ERRORS section

[Michael Kerrisk (man-pages)]

Hello Vince,

On 04/10/2014 10:30 PM, Vince Weaver wrote:
> On Thu, 10 Apr 2014, Michael Kerrisk (man-pages) wrote:
> 
>> I've applied this, but have a question or two below.
>>
>> On 04/07/2014 06:56 AM, Vince Weaver wrote:
> 
>>> +.B EACCES
>>> +Returned when the requested event requires root permissions
>>> +(or a more permissive perf_event paranoid setting).
>>> +Some common causes are attaching to a process owned by a different user,
>>> +monitoring all processes on a given cpu,
>>
>> I don't understand that line above. Could you clarify. How is
>> "monitoring all processes on a given given cpu" a cause of 
>> this error."
> 
> If you configure to monitor all processes by setting cpu=-1 then you
> are potentially measuring processes belonging to other users, which
> would be a security leak.  So you get EACCES.

I was just thrown a bit by your wording. I revised this a little to 
the following. Does it look okay?

       EACCES Returned when the requested event requires root  permis‐
              sions  (or  a  more  permissive perf_event paranoid set‐
              ting).  Some common cases where an unprivileged  process
              may  encounter  this  error:  are attaching to a process
              owned by a different user; monitoring all processes on a
              given CPU; and not setting exclude_kernel when the para‐
              noid setting requires it.

But, now I have some more questions:

* What are "root permissions" here? It's these days usual to express
  things precisely in terms of the required capability.
* I am puzzled by "monitoring all processes on a CPU"? So, monitoring 
  _some_ (i.e., < all) processes on a CPU won't trigger this error?

>>> +.B EPERM
>>> +Returned if sufficient permissions not available to create the event.

Again, somewhere here, the text should mention the required capability.

>>> +This includes attempting to set a breakpoint on a kernel address
>>> +and setting a ftrace function trace tracepoint.
>>
>> I don't understand the previous line. Why is "setting a ftrace function 
>> trace tracepoint" a cause of EPERM?
> 
> Would it be cleared if it were "ftrace function-trace tracepoint"?

That would help.

> This is a recent change.  

So, the text should mention a kernel version number. Could you patch 
that please. I guess it should be something like:

    and (since Linux 3.??) setting an ftrace function-trace tracepoint

> It was a lockup bug we found, it turns out
> that letting an average user set function-trace tracepoints can cause
> problems, if for example they set a tracepoint in an interrupt handler
> that causes an overflow that triggers an interrupt you get a recursive 
> loop.  The easy solution was to just make function-trace tracepoints
> root-only (meaning that yes, root can crash the kernel easily using 
> perf_event_open() ).
> 
> Now why it returns EPERM not EACCES, I don't know.
> 
> I can try to update the text in these two cases to be a bit more clear.
> I'm never sure how much extra details like this are suitable without
> overwhelming the document with extraneous details.

If you could send some patch(es) to fix the above, that would be good.
As ever, thanks for your great work on this page.

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] perf_event_open.2 -- expand ERRORS section

[Vince Weaver]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1631 bytes --]

On Mon, 14 Apr 2014, Michael Kerrisk (man-pages) wrote:

> 
>        EACCES Returned when the requested event requires root  permis‐
>               sions  (or  a  more  permissive perf_event paranoid set‐
>               ting).  Some common cases where an unprivileged  process
>               may  encounter  this  error:  are attaching to a process
>               owned by a different user; monitoring all processes on a
>               given CPU; and not setting exclude_kernel when the para‐
>               noid setting requires it.
> 
> But, now I have some more questions:
> 
> * What are "root permissions" here? It's these days usual to express
>   things precisely in terms of the required capability.

Yes, I guess that should really be CAP_SYS_ADMIN

> * I am puzzled by "monitoring all processes on a CPU"? So, monitoring 
>   _some_ (i.e., < all) processes on a CPU won't trigger this error?

I was a bit confused here.

A regular user can monitor "the specified process on CPU X" or "the 
specified process on any CPU".

A user running as root can also monitor "all procceses belonging to anyone 
on CPU X"

Other combinations aren't possible.

> >>> +.B EPERM
> >>> +Returned if sufficient permissions not available to create the event.
> 
> Again, somewhere here, the text should mention the required capability.

Yes, it's CAP_SYS_ADMIN again.

> > This is a recent change.  
> 
> So, the text should mention a kernel version number. Could you patch 
> that please. I guess it should be something like:
> 
>     and (since Linux 3.??) setting an ftrace function-trace tracepoint

Yes, I'll do that.

Vince

Re: [patch] perf_event_open.2 -- expand ERRORS section

[walter harms]

Am 15.04.2014 20:25, schrieb Vince Weaver:
> On Mon, 14 Apr 2014, Michael Kerrisk (man-pages) wrote:
> 
>>
>>        EACCES Returned when the requested event requires root  permis‐
>>               sions  (or  a  more  permissive perf_event paranoid set‐
>>               ting).  Some common cases where an unprivileged  process
>>               may  encounter  this  error:  are attaching to a process
>>               owned by a different user; monitoring all processes on a
>>               given CPU; and not setting exclude_kernel when the para‐
>>               noid setting requires it.
>>
>> But, now I have some more questions:
>>
>> * What are "root permissions" here? It's these days usual to express
>>   things precisely in terms of the required capability.
> 
> Yes, I guess that should really be CAP_SYS_ADMIN
> 
>> * I am puzzled by "monitoring all processes on a CPU"? So, monitoring 
>>   _some_ (i.e., < all) processes on a CPU won't trigger this error?
> 
> I was a bit confused here.
> 
> A regular user can monitor "the specified process on CPU X" or "the 
> specified process on any CPU".
> 
> A user running as root can also monitor "all procceses belonging to anyone 
> on CPU X"
> 

why not "can monitor any process" ?

re,
 wh

> Other combinations aren't possible.
> 
>>>>> +.B EPERM
>>>>> +Returned if sufficient permissions not available to create the event.
>>
>> Again, somewhere here, the text should mention the required capability.
> 
> Yes, it's CAP_SYS_ADMIN again.
> 
>>> This is a recent change.  
>>
>> So, the text should mention a kernel version number. Could you patch 
>> that please. I guess it should be something like:
>>
>>     and (since Linux 3.??) setting an ftrace function-trace tracepoint
> 
> Yes, I'll do that.
> 
> 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] perf_event_open.2 -- expand ERRORS section

[Michael Kerrisk (man-pages)]

On Wed, Apr 16, 2014 at 9:18 AM, walter harms <wharms-fPG8STNUNVg@public.gmane.org> wrote:
>
>
> Am 15.04.2014 20:25, schrieb Vince Weaver:
>> On Mon, 14 Apr 2014, Michael Kerrisk (man-pages) wrote:
>>
>>>
>>>        EACCES Returned when the requested event requires root  permis‐
>>>               sions  (or  a  more  permissive perf_event paranoid set‐
>>>               ting).  Some common cases where an unprivileged  process
>>>               may  encounter  this  error:  are attaching to a process
>>>               owned by a different user; monitoring all processes on a
>>>               given CPU; and not setting exclude_kernel when the para‐
>>>               noid setting requires it.
>>>
>>> But, now I have some more questions:
>>>
>>> * What are "root permissions" here? It's these days usual to express
>>>   things precisely in terms of the required capability.
>>
>> Yes, I guess that should really be CAP_SYS_ADMIN
>>
>>> * I am puzzled by "monitoring all processes on a CPU"? So, monitoring
>>>   _some_ (i.e., < all) processes on a CPU won't trigger this error?
>>
>> I was a bit confused here.
>>
>> A regular user can monitor "the specified process on CPU X" or "the
>> specified process on any CPU".
>>
>> A user running as root can also monitor "all procceses belonging to anyone
>> on CPU X"
>>
>
> why not "can monitor any process" ?

Thanks for the heads-up, Walter. The wording *is* confusing, but I
believe the fix is different from what you suspect:

[[
@@ -2404,8 +2404,9 @@ permissions (or a more permissive perf_event
paranoid setting).
Some common cases where an unprivileged process
may encounter this error:
attaching to a process owned by a different user;
-monitoring all processes (including those not belonging to the user)
-on a given CPU;
+monitoring all processes on a given CPU (i.e., specifying the
+.I pid
+argument as \-1);
and not setting
.I exclude_kernel
when the paranoid setting requires it.
]]

Cheers

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