[PATCH] manual: Document __wur usage under _FORTIFY_SOURCE

[PATCH] manual: Document __wur usage under _FORTIFY_SOURCE

[Siddhesh Poyarekar]

The __warn_unused_result__ attribute is only enabled when fortification
is enabled.  Mention that in the document.  The rationale for this is
essentially to mitigate against CWE-252:

[1] https://cwe.mitre.org/data/definitions/252.html

Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
---
 manual/maint.texi | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/manual/maint.texi b/manual/maint.texi
index 76d4a1a147..ae651c2a4a 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -206,7 +206,10 @@ to the function call are safe, the call may be replaced by a call to its
 hardened variant that does additional safety checks at runtime.  Some
 hardened variants need the size of the buffer to perform access
 validation and this is provided by the @code{__builtin_object_size} or
-the @code{__builtin_dynamic_object_size} builtin functions.
+the @code{__builtin_dynamic_object_size} builtin functions.  The macro
+also enables additional compile time diagnostics, such as unchecked
+return values from some functions, to encourage developers to add error
+checking for those functions.
 
 At runtime, if any of those safety checks fail, the program will
 terminate with a @code{SIGABRT} signal.  @code{_FORTIFY_SOURCE} may be
-- 
2.39.2

Re: [PATCH] manual: Document __wur usage under _FORTIFY_SOURCE

[Florian Weimer]

* Siddhesh Poyarekar via Libc-alpha:

> The __warn_unused_result__ attribute is only enabled when fortification
> is enabled.  Mention that in the document.  The rationale for this is
> essentially to mitigate against CWE-252:
>
> [1] https://cwe.mitre.org/data/definitions/252.html
>
> Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
> ---
>  manual/maint.texi | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/manual/maint.texi b/manual/maint.texi
> index 76d4a1a147..ae651c2a4a 100644
> --- a/manual/maint.texi
> +++ b/manual/maint.texi
> @@ -206,7 +206,10 @@ to the function call are safe, the call may be replaced by a call to its
>  hardened variant that does additional safety checks at runtime.  Some
>  hardened variants need the size of the buffer to perform access
>  validation and this is provided by the @code{__builtin_object_size} or
> -the @code{__builtin_dynamic_object_size} builtin functions.
> +the @code{__builtin_dynamic_object_size} builtin functions.  The macro
> +also enables additional compile time diagnostics, such as unchecked
> +return values from some functions, to encourage developers to add error
> +checking for those functions.

Maybe repeat _FORTIFY_SOURCE it's been a while since it's been
mentioned?

Note that now that GCC supports [[nodiscard]] (with the standard way
to suppress it), we could apply that to functions even outside
_FORTIFY_SOURCE, I think.  That's a separate matter, of course.

Re: [PATCH] manual: Document __wur usage under _FORTIFY_SOURCE

[Siddhesh Poyarekar]

On 2023-03-24 11:15, Florian Weimer wrote:
>> diff --git a/manual/maint.texi b/manual/maint.texi
>> index 76d4a1a147..ae651c2a4a 100644
>> --- a/manual/maint.texi
>> +++ b/manual/maint.texi
>> @@ -206,7 +206,10 @@ to the function call are safe, the call may be replaced by a call to its
>>   hardened variant that does additional safety checks at runtime.  Some
>>   hardened variants need the size of the buffer to perform access
>>   validation and this is provided by the @code{__builtin_object_size} or
>> -the @code{__builtin_dynamic_object_size} builtin functions.
>> +the @code{__builtin_dynamic_object_size} builtin functions.  The macro
>> +also enables additional compile time diagnostics, such as unchecked
>> +return values from some functions, to encourage developers to add error
>> +checking for those functions.
> 
> Maybe repeat _FORTIFY_SOURCE it's been a while since it's been
> mentioned?

Ack, will do.

> Note that now that GCC supports [[nodiscard]] (with the standard way
> to suppress it), we could apply that to functions even outside
> _FORTIFY_SOURCE, I think.  That's a separate matter, of course.

Yes, I've wondered that too.  I'll start a separate thread about that later.

Thanks,
Sid

[PATCH v2] manual: Document __wur usage under _FORTIFY_SOURCE

[Siddhesh Poyarekar]

The __warn_unused_result__ attribute is only enabled when fortification
is enabled.  Mention that in the document.  The rationale for this is
essentially to mitigate against CWE-252:

[1] https://cwe.mitre.org/data/definitions/252.html

Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
---
 manual/maint.texi | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/manual/maint.texi b/manual/maint.texi
index 76d4a1a147..a8441e20b6 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -207,6 +207,9 @@ hardened variant that does additional safety checks at runtime.  Some
 hardened variants need the size of the buffer to perform access
 validation and this is provided by the @code{__builtin_object_size} or
 the @code{__builtin_dynamic_object_size} builtin functions.
+@code{_FORTIFY_SOURCE} also enables additional compile time diagnostics,
+such as unchecked return values from some functions, to encourage
+developers to add error checking for those functions.
 
 At runtime, if any of those safety checks fail, the program will
 terminate with a @code{SIGABRT} signal.  @code{_FORTIFY_SOURCE} may be
-- 
2.39.2

Re: [PATCH v2] manual: Document __wur usage under _FORTIFY_SOURCE

[Florian Weimer]

* Siddhesh Poyarekar:

> The __warn_unused_result__ attribute is only enabled when fortification
> is enabled.  Mention that in the document.  The rationale for this is
> essentially to mitigate against CWE-252:
>
> [1] https://cwe.mitre.org/data/definitions/252.html
>
> Signed-off-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
> ---
>  manual/maint.texi | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/manual/maint.texi b/manual/maint.texi
> index 76d4a1a147..a8441e20b6 100644
> --- a/manual/maint.texi
> +++ b/manual/maint.texi
> @@ -207,6 +207,9 @@ hardened variant that does additional safety checks at runtime.  Some
>  hardened variants need the size of the buffer to perform access
>  validation and this is provided by the @code{__builtin_object_size} or
>  the @code{__builtin_dynamic_object_size} builtin functions.
> +@code{_FORTIFY_SOURCE} also enables additional compile time diagnostics,
> +such as unchecked return values from some functions, to encourage
> +developers to add error checking for those functions.
>  
>  At runtime, if any of those safety checks fail, the program will
>  terminate with a @code{SIGABRT} signal.  @code{_FORTIFY_SOURCE} may be

Looks good.

Reviewed-by: Florian Weimer <fweimer@redhat.com>

Thanks,
Florian