[PATCH] perf_event_open.2: Add a note that dyn_size is omitted if size == 0

[PATCH] perf_event_open.2: Add a note that dyn_size is omitted if size == 0

[Keno Fischer]

The perf_output_sample_ustack in kernel/events/core.c only writes a
single 64 bit word
if it can't dump the user registers. From the current version of the
man page, I would
have expected two 64 bit words (one for size, one for dyn_size). Change the man
page to make this behavior explicit.

This is my first man-pages patch, please let me know if I should do
anything else.

---
 man2/perf_event_open.2 | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 0e42c50..6788154 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -1994,7 +1994,7 @@ struct {
                       /* if PERF_SAMPLE_REGS_USER */
     u64   size;       /* if PERF_SAMPLE_STACK_USER */
     char  data[size]; /* if PERF_SAMPLE_STACK_USER */
-    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */
+    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER && size != 0 */
     u64   weight;     /* if PERF_SAMPLE_WEIGHT */
     u64   data_src;   /* if PERF_SAMPLE_DATA_SRC */
     u64   transaction;/* if PERF_SAMPLE_TRANSACTION */
@@ -2185,6 +2185,11 @@ stack pointer at the time of sampling).
 .I dyn_size
 is the amount of data actually dumped (can be less than
 .IR size ).
+Note that
+.I dyn_size
+is omitted if
+.I size
+is 0.
 .TP
 .I weight
 If
--
2.6.4
--
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: Add a note that dyn_size is omitted if size == 0

[Vince Weaver]

On Sun, 3 Jul 2016, Keno Fischer wrote:

> The perf_output_sample_ustack in kernel/events/core.c only writes a
> single 64 bit word
> if it can't dump the user registers. From the current version of the
> man page, I would
> have expected two 64 bit words (one for size, one for dyn_size). Change the man
> page to make this behavior explicit.
> 
> This is my first man-pages patch, please let me know if I should do
> anything else.

Overall it looks fine, to me at least. 

It's sometimes also nice to have the commit where the behavior was first 
introuduced mentioned, but in this case since the behavior hasn't changed 
since introduction that's probably not necessary.

I'm fine with this being taken directly.  (not sure if I should kick in a 
reviewed-by or some such tag (?)).
 
I'm slowly catching up on the backlog of perf_event_open.2 updates, 
hopefully I'll start sending those in soon.

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: Add a note that dyn_size is omitted if size == 0

[Michael Kerrisk (man-pages)]

On 07/04/2016 01:08 AM, Keno Fischer wrote:
> The perf_output_sample_ustack in kernel/events/core.c only writes a
> single 64 bit word
> if it can't dump the user registers. From the current version of the
> man page, I would
> have expected two 64 bit words (one for size, one for dyn_size). Change the man
> page to make this behavior explicit.
>
> This is my first man-pages patch, please let me know if I should do
> anything else.

Looks good to me, Keno. Applied. Thanks for the patch!

Cheers,

Michael

> ---
>  man2/perf_event_open.2 | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
>
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index 0e42c50..6788154 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -1994,7 +1994,7 @@ struct {
>                        /* if PERF_SAMPLE_REGS_USER */
>      u64   size;       /* if PERF_SAMPLE_STACK_USER */
>      char  data[size]; /* if PERF_SAMPLE_STACK_USER */
> -    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */
> +    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER && size != 0 */
>      u64   weight;     /* if PERF_SAMPLE_WEIGHT */
>      u64   data_src;   /* if PERF_SAMPLE_DATA_SRC */
>      u64   transaction;/* if PERF_SAMPLE_TRANSACTION */
> @@ -2185,6 +2185,11 @@ stack pointer at the time of sampling).
>  .I dyn_size
>  is the amount of data actually dumped (can be less than
>  .IR size ).
> +Note that
> +.I dyn_size
> +is omitted if
> +.I size
> +is 0.
>  .TP
>  .I weight
>  If
> --
> 2.6.4
>


-- 
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: Add a note that dyn_size is omitted if size == 0

[Michael Kerrisk (man-pages)]

Hello Vince,

On 07/04/2016 07:11 PM, Vince Weaver wrote:
> On Sun, 3 Jul 2016, Keno Fischer wrote:
>
>> The perf_output_sample_ustack in kernel/events/core.c only writes a
>> single 64 bit word
>> if it can't dump the user registers. From the current version of the
>> man page, I would
>> have expected two 64 bit words (one for size, one for dyn_size). Change the man
>> page to make this behavior explicit.
>>
>> This is my first man-pages patch, please let me know if I should do
>> anything else.
>
> Overall it looks fine, to me at least.

It helps hugely when I get a review by someone! Thanks!
(And Keno, thanks also for thinking to CC Vince!)

> It's sometimes also nice to have the commit where the behavior was first
> introuduced mentioned, but in this case since the behavior hasn't changed
> since introduction that's probably not necessary.
>
> I'm fine with this being taken directly.  (not sure if I should kick in a
> reviewed-by or some such tag (?)).

I added one for you.

> I'm slowly catching up on the backlog of perf_event_open.2 updates,
> hopefully I'll start sending those in soon.

That would of course be wonderful!

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