This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v3] manual/probes.texi: Add documentation of setjmp/longjmp probes
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Will Newton <will dot newton at linaro dot org>, libc-alpha at sourceware dot org
- Cc: patches at linaro dot org
- Date: Thu, 06 Feb 2014 11:52:42 -0500
- Subject: Re: [PATCH v3] manual/probes.texi: Add documentation of setjmp/longjmp probes
- Authentication-results: sourceware.org; auth=none
- References: <1391594145-22218-1-git-send-email-will dot newton at linaro dot org>
On 02/05/2014 04:55 AM, Will Newton wrote:
> Add some documentation of the setjmp, longjmp and longjmp_target
> Systemtap probe points.
>
> ChangeLog:
>
> 2014-01-28 Will Newton <will.newton@linaro.org>
Wrong date.
>
> * manual/probes.texi (Internal Probes): Add documentation
> of setjmp, longjmp and longjmp_target probes.
s/of/for/g.
OK to checkin with all nits fixed.
> ---
> manual/probes.texi | 38 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 38 insertions(+)
>
> Changes in v3:
> - Use @code annotation more consistently
> - Drop duplicated paragraph from longjmp_target description
>
> diff --git a/manual/probes.texi b/manual/probes.texi
> index 25d06e5..3bf5421 100644
> --- a/manual/probes.texi
> +++ b/manual/probes.texi
> @@ -17,6 +17,7 @@ arguments.
> @menu
> * Memory Allocation Probes:: Probes in the memory allocation subsystem
> * Mathematical Function Probes:: Probes in mathematical functions
> +* setjmp and longjmp Probes:: Probes in setjmp and longjmp
I'd like a proper name for this section.
Suggest:
"Non-local Goto Probes"
As *jmp is considered the "non-local goto"-set of functions.
> @end menu
>
> @node Memory Allocation Probes
> @@ -368,3 +369,40 @@ results in multiple precision computation with precision 32. Argument
> @var{$arg1} is the input to the function, @var{$arg2} is the error bound of
> @var{$arg1} and @var{$arg3} is the computed result.
> @end deftp
> +
> +@node setjmp and longjmp Probes
> +@section setjmp and longjmp Probes
Rename per above.
> +
> +These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
> +@code{longjmp} or @code{siglongjmp}.
> +
> +@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
> +This probe is hit whenever @code{setjmp} or @code{sigsetjmp} is called.
s/hit/triggered/g.
> +Argument @var{$arg1} is a pointer to the @code{jmp_buf} passed as the first
> +argument of @code{setjmp} or @code{sigsetjmp}, @var{$arg2} is the second
> +argument of @code{sigsetjmp} or zero if this is a call to @code{setjmp}
> +and @var{$arg3} is a pointer to the return address that will be stored
> +in the @code{jmp_buf}.
> +@end deftp
OK.
> +
> +@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
> +This probe is hit whenever @code{longjmp} or @code{siglongjmp} is called.
s/hit/triggered/g.
> +Argument @var{$arg1} is a pointer to the @code{jmp_buf} passed as the first
> +argument of @code{longjmp} or @code{siglongjmp}, @var{$arg2} is the return
> +value passed as the second argument of @code{longjmp} or @code{siglongjmp}
> +and @var{$arg3} is a pointer to the return address @code{longjmp} or
> +@code{siglongjmp} will return to.
Suggest:
and @var{$arg3} is a pointer to the return address for @code{longjmp} or
@code{siglongjmp}.
> +
> +The @code{longjmp} probe is hit at a point where the registers have not yet
s/hit/triggered/g
> +been restored to the values in the @code{jmp_buf} and unwinding will show a
> +call stack including the caller of @code{longjmp} or @code{siglongjmp}.
> +@end deftp
OK.
> +
> +@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
> +This probe is hit under the same conditions and with the same arguments
s/hit/triggered/g
> +as the @code{longjmp} probe.
> +
> +The @code{longjmp_target} probe is hit at a point where the registers have
s/hit/triggered/g.
> +been restored to the values in the @code{jmp_buf} and unwinding will show a
> +call stack including the caller of @code{setjmp} or @code{sigsetjmp}.
> +@end deftp
OK.
Feel free to checkin a patch that does s/hit/triggered/g for all probe docs.
It is not correct in my opinion to use the colloquial "hit" to mean that the
probe was triggered.
Cheers,
Carlos.