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@xxxxxxxxx> > > 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
