[PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Uwe Kleine-König]

I have no idea about the rationale, but that's what LDD3 recommends.

Signed-off-by: Uwe Kleine-König <uwe@kleine-koenig.org>
---
Hello,

during a review I claimed that PTR_ERR should only be used if IS_ERR was
already checked. The rationale isn't obvious though and Thierry
suggested to keep the code as is and not introduce an IS_ERR check.

I found in Linux Device Drivers 3[1]:

	You should use PTR_ERR only on a value for which IS_ERR returns
	a true value; any other value is a valid pointer

I wonder if there is a relevant reason that LDD3 suggests to check
IS_ERR first, maybe something like "On an Alpha it is important because
not doing it results in a bus error there." There are no details
mentioned there however. If there is a reason, this patch should be
adapted such that the comment includes it.

Any ideas?

Best regards
Uwe

[1] https://static.lwn.net/images/pdf/LDD3/ch11.pdf, on page 295

 include/linux/err.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/linux/err.h b/include/linux/err.h
index 87be24350e91..8f052983108e 100644
--- a/include/linux/err.h
+++ b/include/linux/err.h
@@ -26,6 +26,9 @@ static inline void * __must_check ERR_PTR(long error)
 	return (void *) error;
 }
 
+/*
+ * You should use PTR_ERR only on a value for which IS_ERR returns a true value.
+ */
 static inline long __must_check PTR_ERR(__force const void *ptr)
 {
 	return (long) ptr;
-- 
2.19.1

Re: [PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Alessandro Rubini]

Hello.

> during a review I claimed that PTR_ERR should only be used if IS_ERR was
> already checked. The rationale isn't obvious though and Thierry
> suggested to keep the code as is and not introduce an IS_ERR check.

The rationale is the same ch11 you linked to: "any other value
is a valid pointer".  It isn't usefult to convert to long sth that
your are not using as a long.  You should not pass it to strerror(-err)
for example.

OTOH I admit you can compare any value with -EINVAL, after PTR_ERR.
But in general you first detect the error condition and then split
among error (or print a message according to the exact value.

> maybe something like "On an Alpha it is important because
> not doing it results in a bus error there."

No, nothing that exotic.

You said:

> Thierry suggested to keep the code as is and not introduce an IS_ERR check.

I wonder where. Sure no extra check in the header, that would be
extra wasted time in every caller. If it's a specific caller place,
it may make sense to avoid the check, I don't know the details.

As for the specific patch you propose, I'm unsure it's useful.  Maybe
we should remember that "this returns the equivalent of "-errno" if
IS_ERR() is true", but I'm personally not much for overcommenting:
It's a simple cast and there are a zillion users to see how exactly
this works if anyone is uncertain.

Regards
/alessandro

Re: [PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Uwe Kleine-König]

[-- Attachment #1.1: Type: text/plain, Size: 1954 bytes --]

Hello,

On 10/15/2018 11:37 AM, Alessandro Rubini wrote:
>> during a review I claimed that PTR_ERR should only be used if IS_ERR was
>> already checked. The rationale isn't obvious though and Thierry
>> suggested to keep the code as is and not introduce an IS_ERR check.
> 
> The rationale is the same ch11 you linked to: "any other value
> is a valid pointer".  It isn't usefult to convert to long sth that
> your are not using as a long.  You should not pass it to strerror(-err)
> for example.

ok, that's obvious that this should be forbidden.

> OTOH I admit you can compare any value with -EINVAL, after PTR_ERR.
> But in general you first detect the error condition and then split
> among error (or print a message according to the exact value.
> 
>> maybe something like "On an Alpha it is important because
>> not doing it results in a bus error there."
> 
> No, nothing that exotic.

OK, if there is nothing that exotic, the patch is probably of little use.

> You said:
> 
>> Thierry suggested to keep the code as is and not introduce an IS_ERR check.
> 
> I wonder where. Sure no extra check in the header, that would be
> extra wasted time in every caller. If it's a specific caller place,
> it may make sense to avoid the check, I don't know the details.

http://patchwork.ozlabs.org/patch/981774/#2009383

The obvious alternatives would be:

	if (PTR_ERR_OR_ZERO(imx_chip->pwm_gpiod) == -EPROBE_DEFER)

	if (imx_chip->pwm_gpiod == ERR_PTR(-EPROBE_DEFER))

but if no kittens die anywhere it's probably of little value to argue here.

> As for the specific patch you propose, I'm unsure it's useful.  Maybe
> we should remember that "this returns the equivalent of "-errno" if
> IS_ERR() is true", but I'm personally not much for overcommenting:
> It's a simple cast and there are a zillion users to see how exactly
> this works if anyone is uncertain.

ack.

Thanks for your input
Uwe


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Al Viro]

On Mon, Oct 15, 2018 at 11:37:08AM +0200, Alessandro Rubini wrote:

> OTOH I admit you can compare any value with -EINVAL, after PTR_ERR.
> But in general you first detect the error condition and then split
> among error (or print a message according to the exact value.

	if (IS_ERR(p) && PTR_ERR(p) == -ENOENT)
instead of
	if (p == ERR_PTR(-ENOENT))

is ugly, obfuscating what's going on for no good reason and I'm going
to keep killing those every time I run into one...

Re: [PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Uwe Kleine-König]

On Tue, Oct 16, 2018 at 07:06:51PM +0100, Al Viro wrote:
> On Mon, Oct 15, 2018 at 11:37:08AM +0200, Alessandro Rubini wrote:
> 
> > OTOH I admit you can compare any value with -EINVAL, after PTR_ERR.
> > But in general you first detect the error condition and then split
> > among error (or print a message according to the exact value.
> 
> 	if (IS_ERR(p) && PTR_ERR(p) == -ENOENT)
> instead of
> 	if (p == ERR_PTR(-ENOENT))
> 
> is ugly, obfuscating what's going on for no good reason and I'm going
> to keep killing those every time I run into one...

And what do you do if you see a

	p = somefunc(...);
	if (PTR_ERR(p) == -ENOENT)

without first checking for IS_ERR(p)? Another alternative is

	if (PTR_ERR_OR_ZERO(p) == -ENOENT)

? In your eyes, should they all be converted to

	if (p == ERR_PTR(-ENOENT))

?

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH RFC] err.h: document that PTR_ERR should only be used if IS_ERR returns true

[Alessandro Rubini]

Me:
>> > OTOH I admit you can compare any value with -EINVAL, after PTR_ERR.
>> > But in general you first detect the error condition and then split
>> > among error (or print a message according to the exact value.

Al Viro:
>> 
>> 	if (IS_ERR(p) && PTR_ERR(p) == -ENOENT)
>> instead of
>> 	if (p == ERR_PTR(-ENOENT))
>> 
>> is ugly, obfuscating what's going on for no good reason and I'm going
>> to keep killing those every time I run into one...

Sure. I was talking about selecting among errors in the error path,
after you left the fast path jumping away with IS_ERR().

(in short, I agree).

Uwe kleine-koenig

> And what do you do if you see a
> 
> 	p = somefunc(...);
> 	if (PTR_ERR(p) == -ENOENT)
> 
> without first checking for IS_ERR(p)?

I see no problem. The original suggestion (only use if IS_ERR), which
was mine, refers to doing error management in error cases. Sure
if you know the return value is valid or -ENOENT you don't need to verify
it is negative before comparing with -2.

Both PTR_ERR and ERR_PTR are just a cast to prevent a warning
(and tell the reader that you convert from err to ptr or vv), so
I think the two are equivalent. Al's version above is maybe cleaner,
but we are bikeshedding, IMHO.

best
/alessandro