Re: [PATCH 1/1] s390_sthyi.2: New page for s390-specific s390_sthyi(2)

[Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org>]

Hello Michael

> On 21 November 2017 at 11:23, Heiko Carstens <heiko.carstens-tA70FqPdS9bQT0dZR+AlfA@public.gmane.org> wrote:
> > On Tue, Nov 21, 2017 at 09:48:02AM +0100, Michael Kerrisk (man-pages) wrote:
> >> >> What does "On other cases" mean? When do those cases happen?
> >> >> Could you reword please.
> >> >
> >> > The case is:
> >> > If the STHYI facility is enabled and the system call fails to execute the
> >> > underlying
> >> > STHYI instruction, the value of condition code is returned, which currently
> >> > is only
> >> > 3 indicating "unsupported function code".
> >> > Is this OK to put it here?
> >>
> >> Let me see if I understand correctly. There are three possible return
> >> values for this system call:
> >>
> >> 0 ==> success
> >> -1 ==> failure (and errno is set)
> >> [condition code value is returned -- e,g,, 3]
> >>
> >> This last case is a kind of failure in the system call, right?
> >>
> >> If this is correct, this is a highly unusual--possibly even
> >> unique--model for the system call return value. Most (in fact, I think
> >> all) system calls indicate errors by returning -1. Values >= 0 always
> >> mean success. I think it may be worth revisiting this design, to make
> >> it more consistent with the usual conventions. For example, why not
> >> handle the last case by returning -1, setting errno to some value
> >> (maybe ENOTSUP), and return the condition code in *buffer?.
> >
> > Well, I would have written this differently: on success the return value
> > matches the condition code of the STHYI instructions, which is a value
> > between 0-3 (that is: emulation succeeded). If a condition code, which is
> > not 0, is an error or not, may not be the same in the future, if the
> > instruction gets extended.
> >
> > That being said, if you think this still doesn't make much sense, we might
> > have to reconsider the interface.
> 
> When you put it as above, the interface feels less odd. But, in that
> case, I think the return value should be documented more as you word
> it above. Something like:
> 
> "On success the return value matches the condition code of the STHYI
> instructions, which is a value between 0-3 (that is: emulation
> succeeded)."
> 
> Followed by an explanation of the meaning of 0 and any of the values >
> 0 that may be returned.

Yes, I agree with you.

--
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