[DOC] Document ASAN_OPTIONS="halt_on_error" env variable.

Hello.

It's bit confusing for a use that -fsanitize-recover=address does not recover
an instrumented binary. As a default value of halt_on_error is set to 0 for address sanitizer,
the binary fails on a first error.

Following patch attempts to explain the ENV variable.

Ready for trunk?
Thanks,
Martin

On Wed, May 11, 2016 at 04:13:27PM +0200, Martin Liška wrote:
> It's bit confusing for a use that -fsanitize-recover=address does not recover
> an instrumented binary. As a default value of halt_on_error is set to 0 for address sanitizer,
> the binary fails on a first error.
> 
> Following patch attempts to explain the ENV variable.
> 
> Ready for trunk?
> Thanks,
> Martin

> >From 95f694a92428759773e5259323e82cbf49eade34 Mon Sep 17 00:00:00 2001
> From: marxin <mliska@suse.cz>
> Date: Wed, 11 May 2016 16:05:49 +0200
> Subject: [PATCH] Document ASAN_OPTIONS="halt_on_error" env variable.
> 
> gcc/ChangeLog:
> 
> 2016-05-11  Martin Liska  <mliska@suse.cz>
> 
> 	* doc/invoke.texi: Explain connection between -fsanitize-recover=address
> 	and ASAN_OPTIONS="halt_on_error=1".
> ---
>  gcc/doc/invoke.texi | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index a54a0af..722647a 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -9998,6 +9998,12 @@ for which this feature is experimental.
>  accepted, the former enables recovery for all sanitizers that support it,
>  the latter disables recovery for all sanitizers that support it.
>  
> +The error recovery mode can be overwritten by @code{halt_on_error=1} provided
> +to one of the following environment variables: @env{ASAN_OPTIONS}, @env{TSAN_OPTIONS}
> +or @env{UBSAN_OPTIONS}. The default value is set to @code{halt_on_error=1},
> +only the address sanitizer by default does not recover and @code{halt_on_error=0}
> +must be provided.

It can be overridden (not overwritten?) only in one way I believe, i.e. the
code must be built with -fsanitize-recover=<whatever> (whether by default or
not) and the recovery must be enabled in the library (by default or using
env var) for successful recovery.  If you compile without recovery, then no
matter what you do on the env var side it still will be fatal.
So the docs need to make that clear.

	Jakub

On 05/11/2016 05:13 PM, Martin Liška wrote:
> Hello.
>
> It's bit confusing for a use that -fsanitize-recover=address does not recover
> an instrumented binary. As a default value of halt_on_error is set to 0 for address sanitizer,
> the binary fails on a first error.

I'm the guy behind -fsanitize-recover=address so let me explain.

Error recovery requires changes both to compiler (insert calls to 
recovering __asan_report_error_X_noabort rather than noreturning 
__asan_report_error_X) and runtime (do not abort when detecting overflow 
inside intercepted API like memcpy). -fsanitize-recover controls the 
compiler side, whereas halt_on_error=0 controls the runtime side.

Unfortunately currently there is no way to inform runtime library that 
compiled code would like it to continue execution after detecting error. 
Actually it's not clear how to do that properly because different parts 
of application could be compiled with different recovery settings (e.g. 
a.c with recovery and b.c without) making it hard to understand what 
behavior user would expect from runtime library interceptors.

> Following patch attempts to explain the ENV variable.
>
> Ready for trunk?

LGTM (but I'm not a maintainer and do not have approve right).

> Thanks,
> Martin
>