user_namespaces.7: Minor wording fix to recently added text

[thirdparty/man-pages.git] / man2 / s390_sthyi.2

diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2
index 6597bfdccef8f992ea79859def307fadcfdbf795..3b4226f7c8e082a40eeaca4614bbb6ec5cb9a535 100644 (file)
--- a/man2/s390_sthyi.2
+++ b/man2/s390_sthyi.2
@@ -22,22 +22,23 @@
 .\" <http://www.gnu.org/licenses/>.
 .\" %%%LICENSE_END
 .\"
-.TH S390_STHYI 2 2017-09-21 "Linux Programmer's Manual"
+.TH S390_STHYI 2 2019-03-06 "Linux Programmer's Manual"
 .SH NAME
 s390_sthyi \- emulate STHYI instruction
 .SH SYNOPSIS
 .nf
 .B #include <asm/unistd.h>
 .PP
-.BI "int s390_sthyi(unsigned long " function_code ", void *" buffer ",
+.BI "int s390_sthyi(unsigned long " function_code ", void *" resp_buffer ",
 .BI "               uint64_t *" return_code ", unsigned long " flags ");
 .fi
 .SH DESCRIPTION
 The
 .BR s390_sthyi ()
 system call emulates the STHYI (Store Hypervisor Information) instruction.
-It provides hardware resource information for the machine and its virtualization
-levels. This includes CPU type and capacity, as well as the machine model and
+It provides hardware resource information for the machine and its
+virtualization levels.
+This includes CPU type and capacity, as well as the machine model and
 other metrics.
 .PP
 The
@@ -50,16 +51,19 @@ Return CP (Central Processor) and IFL (Integrated Facility for Linux)
 capacity information.
 .PP
 The
-.I buffer 
-argument specifies the address of a response buffer. If the system
-call returns 0, the response buffer will be filled with CPU capacity
-information. Otherwise, the response buffer's content is unchanged.
+.I resp_buffer
+argument specifies the address of a response buffer.
+When the
+.I function_code
+is 0, the buffer must be one page (4K) in size.
+If the system call returns 0,
+the response buffer will be filled with CPU capacity information.
+Otherwise, the response buffer's content is unchanged.
 .PP
 The
 .I return_code
-argument stores the return code of the STHYI instruction, using one
-of the
-following values:
+argument stores the return code of the STHYI instruction,
+using one of the following values:
 .TP 8
 0
 Success.
@@ -71,59 +75,68 @@ For further details about
 .IR return_code ,
 .IR function_code ,
 and
-.IR buffer ,
-please see section
-CONFORMING TO
-below.
+.IR resp_buffer ,
+see the reference given in NOTES.
 .PP
 The
 .I flags
 argument is provided to allow for future extensions and currently
 must be set to 0.
 .SH RETURN VALUE
-On success, the return value of
+On success (that is: emulation succeeded), the return value of
 .BR s390_sthyi ()
 matches the condition code of the STHYI instructions, which is a value
-between 0-3 (that is: emulation succeeded).
-Return value of 0 indicates that CPU capacity information is stored to
-.IR buffer .
-Return value of 3 indicates "unsupported function code" and buffer's
-content is unchanged.
-Return value of 1 and 2 are reserved.
+in the range [0..3].
+A return value of 0 indicates that CPU capacity information is stored in
+.IR *resp_buffer .
+A return value of 3 indicates "unsupported function code" and the content of
+.IR *resp_buffer
+is unchanged.
+The return values 1 and 2 are reserved.
 .PP
 On error, \-1 is returned, and
 .IR errno
 is set appropriately.
 .SH ERRORS
 .TP
-.B EINVAL
-The value specified in
-.I flags
-is non-zero.
-.TP
-.B EOPNOTSUPP
-The value specified in
-.I function_code 
-is not a valid value.
-.TP
 .B EFAULT
 The value specified in
-.I buffer 
+.I resp_buffer
 or
 .I return_code
 is not a valid address.
 .TP
+.B EINVAL
+The value specified in
+.I flags
+is nonzero.
+.TP
 .B ENOMEM
 Allocating memory for handling the CPU capacity information failed.
+.TP
+.B EOPNOTSUPP
+The value specified in
+.I function_code
+is not valid.
 .SH VERSIONS
 This system call is available since Linux 4.15.
 .SH CONFORMING TO
 This Linux-specific system call is available only on the s390 architecture.
-For details about the STHYI instruction, see
-https://www.ibm.com/support/knowledgecenter/SSB27U_6.3.0/com.ibm.zvm.v630.hcpb4/hcpb4sth.htm
 .SH NOTES
 Glibc does not provide a wrapper for this system call, use
 .BR syscall (2)
 to call it.
+.PP
+For details of the STHYI instruction, see
+.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
+the documentation page
+.UE .
+.PP
+When the system call interface is used, the response buffer doesn't
+have to fulfill alignment requirements described in the STHYI
+instruction definition.
+.PP
+The kernel caches the response (for up to one second, as of Linux 4.16).
+Subsequent system call invocations may return the cached response.
 .SH SEE ALSO
 .BR syscall (2)