From mboxrd@z Thu Jan 1 00:00:00 1970 From: Heiko Carstens Subject: Re: [PATCH 1/1] s390_sthyi.2: New page for s390-specific s390_sthyi(2) Date: Tue, 21 Nov 2017 12:51:03 +0100 Message-ID: <20171121115102.GC4046@osiris> References: <20171120133420.4700-1-haoqf@linux.vnet.ibm.com> <8b4188fa-bdda-c3eb-5184-cecf78267f0f@gmail.com> <10afe17f-9874-06c6-acd3-7da8fe14af55@linux.vnet.ibm.com> <20171121102314.GB4046@osiris> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Content-Disposition: inline In-Reply-To: Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: "Michael Kerrisk (man-pages)" Cc: QingFeng Hao , linux-man , Christian Borntraeger , Stefan Raspl List-Id: linux-man@vger.kernel.org Hello Michael > On 21 November 2017 at 11:23, Heiko Carstens 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