File s390-tools-sles11sp2-afiucv-manpage-1-2.patch of Package s390-tools

Overview Repositories Revisions Requests Users Attributes Meta

File s390-tools-sles11sp2-afiucv-manpage-1-2.patch of Package s390-tools

Description: af_iucv manpage: add HiperSockets transport
Symptom:     just IUCV transport is described in the manpage
Problem:     HiperSockets transport has been added to af_iucv.
             The af_iucv manpage does not cover HiperSockets
             transport.
Solution:    Add HiperSockets transport information to af_iucv
             manpage.
Problem-ID:  75150
---
 man/af_iucv.7 |  333 ++++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 243 insertions(+), 90 deletions(-)

--- a/man/af_iucv.7
+++ b/man/af_iucv.7
@@ -1,18 +1,18 @@
 .\" af_iucv.7
 .\"
 .\"
-.\" Copyright IBM Corp. 2008, 2009.
+.\" Copyright IBM Corp. 2008, 2011.
 .\" Author(s): Hendrik Brueckner <brueckner@linux.vnet.ibm.com>
 .\" ----------------------------------------------------------------------
-.TH AF_IUCV 7 "September 2009"  "s390-tools" "Linux Programmer's Manual"
+.TH AF_IUCV 7 "August 2011"  "s390-tools" "Linux Programmer's Manual"
 .SH NAME
-iucv, AF_IUCV \- Sockets for z/VM IUCV communication
+AF_IUCV \- Sockets for z/VM IUCV and HiperSockets communication
 .
 .
 .
 .SH SYNOPSIS
 .B #include <sys/socket.h>
-
+.PP
 .IB iucv_stream_socket " = socket(AF_IUCV, SOCK_STREAM, 0);"
 .br
 .IB iucv_packet_socket " = socket(AF_IUCV, SOCK_SEQPACKET, 0);"
@@ -20,42 +20,73 @@ iucv, AF_IUCV \- Sockets for z/VM IUCV c
 .
 .
 .SH DESCRIPTION
-The Inter-User Communication Vehicle (IUCV) is a z/VM communication facility
-that enables a program running in one z/VM guest virtual machine to communicate
-with another z/VM guest virtual machine, or with the control program (CP), or
-even with itself.
-
-The AF_IUCV address family provides communication and addressing in the IUCV
-domain.  In the IUCV domain, address spaces or virtual machines can use the
-socket interface to communicate with other virtual machines or address spaces
-within the same z/VM guest operating system.
-
-AF_IUCV connects socket applications running on different Linux guest operating
-systems, or it connects a Linux application to another socket application
-running in another z/VM guest operating system (like z/VM CMS).
-
+The AF_IUCV address family provides an addressing mode for communications
+between applications that run on System z mainframes.  This addressing mode can be
+used for connections through real HiperSockets and through the z/VM Inter-User
+Communication Vehicle (IUCV).
+.PP
+HiperSockets facilitate connections between applications across LPARs within a
+System z mainframe.  In particular, an application running on an instance of Linux
+on System z can communicate with:
+.RS 2
+.IP "\(bu" 2
+Itself
+.IP "\(bu" 2
+Other applications running on the same Linux instance
+.IP "\(bu" 2
+An application on an instance of Linux on System z in another LPAR
+.RE
+.PP
+IUCV facilitates connections between applications across z/VM guest virtual
+machines within a z/VM system.  In particular, an application running on Linux on
+z/VM can communicate with:
+.RS 2
+.IP "\(bu" 2
+Itself
+.IP "\(bu" 2
+Other applications running on the same Linux instance
+.IP "\(bu" 2
+Applications running on other instances of Linux on z/VM within the same z/VM system
+.IP "\(bu" 2
+Applications running on a z/VM guest other than Linux within the same z/VM system
+.IP "\(bu" 2
+The z/VM control program (CP)
+.RE
+.PP
 The AF_IUCV address family supports stream-oriented sockets
 (\f(CWSOCK_STREAM\fP) and connection-oriented datagram sockets
-(\f(CWSOCK_SEQPACKET\fP). Stream-oriented sockets fragment data over several
-native IUCV messages, whereas sockets of type SOCK_SEQPACKET map a particular
-socket write or read operation to a single native IUCV message.
-
+(\f(CWSOCK_SEQPACKET\fP).  Stream-oriented sockets can fragment data over
+several packets.  Sockets of type SOCK_SEQPACKET always map a particular
+socket write or read operation to a single packet.
+.
+.
 .SS Features
-The AF_IUCV address family provides:
+For all instances of Linux on System z, the AF_IUCV address family provides:
+.RS 2
+.IP "\(bu" 2
+Multiple outgoing socket connections for real HiperSockets
+.IP "\(bu" 2
+Multiple incoming socket connections for real HiperSockets
+.RE
 .PP
+For instances of Linux on z/VM, the AF_IUCV address family also provides:
+.RS 2
 .IP "\(bu" 2
-Multiple outgoing socket connections from a Linux guest operating system.
+Multiple outgoing socket connections for IUCV
 .IP "\(bu" 2
-Multiple incoming socket connections to a Linux guest operating system.
+Multiple incoming socket connections for IUCV
 .IP "\(bu" 2
-Socket communication with applications utilizing CMS AF_IUCV support.
+Socket communication with applications utilizing CMS AF_IUCV support
+.RE
 .
 .
 .
 .
 .SH "ADDRESS FORMAT"
+An AF_IUCV socket is represented by the following format:
+.PP
+.RS 8
 .ft CW
-.in +0.25i
 .nf
 #define AF_IUCV    32
 
@@ -64,14 +95,13 @@ struct sockaddr_iucv {
     unsigned short siucv_port;       /* reserved */
     unsigned int   siucv_addr;       /* reserved */
     char           siucv_nodeid[8];  /* reserved */
-    char           siucv_userid[8];  /* guest user id */
+    char           siucv_userid[8];  /* user id */
     char           siucv_name[8];    /* application name */
 };
-
 .fi
-.in -0.25i
-.ft R
-
+.ft
+.RE
+.PP
 .TP
 .B siucv_family
 is set to
@@ -86,24 +116,59 @@ and
 .B siucv_addr
 fields must be zero. The
 .B siucv_nodeid
-field must be set to exactly eight blank characters.
+field must be set to exactly eight blanks.
 .
 .TP
 .B siucv_userid
-is set to the z/VM user ID of the Linux guest virtual machine running the
-application that owns the address. The field must be eight characters long,
-padded with blanks on the right.
+specifies a HiperSockets device or a z/VM guest virtual machine.
+This specification implicitly sets the connection type for the socket to a
+HiperSockets connection or to a z/VM IUCV connection.
+
+This field must be eight characters long and, if necessary, padded with
+blanks on the right.
 
+For HiperSockets connections, the
+.B siucv_userid
+field specifies the identifier that is set with the \fBhsuid\fP sysfs
+attribute of the HiperSockets device.  For
+.BR bind (2)
+this is the identifier of a local device, and for
+.BR connect (2)
+this is the identifier of the HiperSockets device of the communication
+peer.
+
+For IUCV connections, the
+.B siucv_userid
+field specifies a z/VM user ID.  For
+.BR bind (2)
+this is the identifier of the local z/VM guest virtual machine, and
+for
+.BR connect (2)
+this is the identifier of the z/VM guest virtual machine for the
+communication peer.
+
+.RS
+.TP
+.B Tip:
 For
-.BR bind "(2), " siucv_userid
-must contain blanks only to allow AF_IUCV to set the z/VM user ID of the Linux
-guest operating system.
+.BR bind (2)
+you can also specify eight blanks.  The AF_IUCV address family support
+then automatically substitutes the local z/VM user ID for you.
+.RE
 .
 .TP
 .B siucv_name
 is set to the application name by which the socket is known. Servers advertise
 application names and clients use these application names to connect to servers.
-This field must be eight characters long, padded with blanks on the right.
+This field must be eight characters long, and if necessary, padded with blanks on
+the right.
+
+Similar to TCP or UDP ports, application names distinguish distinct
+applications on the same operating system instance.  Do not call
+.BR bind (2)
+for names beginning with \fBlnxhvc\fP.  These names are reserved for the
+z/VM IUCV HVC device driver (see also
+.BR hvc_iucv (9)).
 .
 .
 .
@@ -117,8 +182,9 @@ by specifying \f(CWSOL_IUCV\fP as the so
 .TP
 .B SO_IPRMDATA_MSG
 Enables the application to send up to seven bytes of socket data in the
-parameter list of an IUCV message. Use this option to increase performance
-when transferring small amounts of data.
+parameter list of an IUCV message.  Use this option for IUCV connections
+to increase performance when transferring small amounts of data.
+For HiperSockets connections, this option has no effect.
 
 To send data in the parameter list, specify a non-zero integer value.
 
@@ -132,13 +198,14 @@ a parameter list message has been receiv
 .
 .TP
 .B SO_MSGLIMIT
-Modifies the message limit for new IUCV communication paths. The message
-limit specifies the maximum number of outstanding messages that are allowed
-for established connections. This setting can be lowered by z/VM when an IUCV
-connection is established.
+Modifies the message limit for communication paths. The message limit
+specifies the maximum number of outstanding messages that are allowed
+for established connections.  For IUCV connections this setting can be
+lowered by z/VM when a connection is established.
 
 The message limit is an integer value in range 1 to 65535.
-The default value is 65535.
+The default value is 65535 for IUCV connections and 128 for HiperSockets
+connections.
 
 The message limit must be set before
 .BR connect "(2) or " listen (2)
@@ -153,45 +220,92 @@ inherit the message limit that has been 
 
 .BR getsockopt (2)
 returns the default message limit or the limit that has been set.
-For connected sockets, the current message limit is returned. The current
-message limit is assigned by z/VM for each connection and it depends
-on the IUCV MSGLIMIT statement specified for the z/VM guest virtual machine.
-The current message limit is the lower value of the socket option and the
-value specified for the IUCV MSGLIMIT statement.
+For connected sockets, the current message limit is returned.
+For IUCV connections, there are two parameters that specify the message limit:
+.BR getsockopt (2)
+and the z/VM IUCV MSGLIMIT parameter.  If the two parameters specify different
+values for the message limit, the lower value is used.
 
-See the SECURITY section below for setting IUCV MSGLIMIT authorizations.
+See the "SETUP FOR IUCV CONNECTIONS" section for setting IUCV MSGLIMIT
+authorizations.
 .
 .
 .
 .SH "ANCILLARY DATA"
-Ancillary data is sent and received using the
+Ancillary data is sent and received using
 .BR sendmsg (2)
 and
 .BR recvmsg (2)\fR.\fP
 To send ancillary data, set the \fBcmsg_level\fP field of struct \fBcmsghdr\fP
-to \f(CWSOL_IUCV\fP and the \fBcmsg_type\fP field to the type.
+to \f(CWSOL_IUCV\fP and the \fBcmsg_type\fP field to a type of ancillary data
+that is supported by the AF_IUCV address family.
 .br
 For more information see
 .BR cmsg (3).
 
+Currently, the only supported type is:
 .TP
 .B SCM_IUCV_TRGCLS
 Send or receive IUCV target class information. The IUCV target class can be used
-to classify and identify an IUCV message at IUCV protocol level. If the target
-class is not specified as ancillary data, it is set to zero.
+to classify and identify an IUCV message at the IUCV protocol level.
+If the target class is not specified as ancillary data, it is set to zero.
 
 The target class is a number of type \fBuint32_t\fP.
 .
 .
 .
+.SH "SETUP FOR HIPERSOCKETS CONNECTIONS"
+This section applies to HiperSockets connections and explains the
+configuration of a HiperSockets device used for AF_IUCV address family
+support.
+.PP
+To run an AF_IUCV socket application using HiperSockets connections, the
+socket must be bound to a particular HiperSockets device.
+Use the \f(CWhsuid\fP attribute of a HiperSockets device to identify it
+to the AF_IUCV address family support.
+.PP
+The identifier must adhere to these rules:
+.RS 2
+.IP \(bu 2
+It must be 1 to 8 characters.
+.IP \(bu 2
+It must be unique across your environment.
+.IP \(bu 2
+It must not match any z/VM user ID in your environment.
+.RE
+.PP
+To set an identifier, issue a command like this:
+.PP
+.RS 8
+.ft CW
+echo \fIidentifier\fP > /sys/devices/qeth/\fI<bus-ID>\fP/hsuid
+.ft
+.RE
+.PP
+You can then address this device by specifying the hsuid as the
+value for the \fBsiucv_userid\fP field in the \fBsockaddr_iucv\fP
+addressing structure.
+.PP
+For example, to use "MYHOST01" to bind AF_IUCV sockets to the
+HiperSockets device with bus-ID 0.0.8000, run:
+.PP
+.RS 8
+.ft CW
+.nf
+echo "MYHOST01" > /sys/devices/qeth/0.0.8000/hsuid
+.fi
+.ft
+.RE
+.
+.
 .
-.SH SECURITY
-This section provides an overview of the required IUCV statements for your z/VM
-guest virtual machine. For details and for general IUCV setup information for
-z/VM guests virtual machines see
+.SH "SETUP FOR IUCV CONNECTIONS"
+This section applies to z/VM IUCV connections and provides an overview of the
+required IUCV statements for your z/VM guest virtual machines.  For details
+and for general IUCV setup information for z/VM guest virtual machines see
 .I z/VM CP Programming Services
 and
-.I z/VM CP Planning and Administration\fR.\fP
+.IR "z/VM CP Planning and Administration" .
 .
 .
 .SS "Granting IUCV authorizations"
@@ -201,9 +315,10 @@ directory control statement to grant the
 .
 .TP
 .B IUCV ALLOW
-allows any other z/VM virtual machine to establish a communication path with
-this z/VM virtual machine. With this statement, no further authorization is
-required in the z/VM virtual machine that initiates the communication.
+allows any other z/VM guest virtual machine to establish a communication path
+with this z/VM guest virtual machine.  With this statement, no further
+authorization is required for the z/VM guest virtual machine that initiates
+the communication.
 .
 .TP
 .B IUCV ANY
@@ -221,8 +336,7 @@ can append the
 parameter.
 \fIlimit\fP specifies the maximum number of outstanding messages that are
 allowed for each connection authorized by this statement.
-If no value is specified for \fBMSGLIMIT\fP, AF_IUCV requests 65535,
-which is the maximum supported by IUCV.
+If no value is specified for \fBMSGLIMIT\fP, the maximum, 65535, is used.
 .
 .
 .SS "Setting a connection limit"
@@ -265,7 +379,7 @@ of errors.
 .TP
 .B ECONNREFUSED
 .BR connect (2)
-called but the target z/VM guest virtual machine is not listening on the
+called but the target system is not listening on the
 application name.
 .
 .TP
@@ -278,35 +392,64 @@ connect is logged on.
 .TP
 .B EAGAIN
 .BR connect (2)
-called but the maximum number of connections is exceeded for the calling or for
-the target z/VM guest virtual machine.
-This error can be temporary and the application may try again after some time.
-If the error occurs repeatedly, try to increase the maximum number of
+called but the maximum number of IUCV connections is exceeded for the calling
+or for the target z/VM guest virtual machine.
+This error can be temporary and the application might try again after some
+time.  If the error occurs repeatedly, increase the maximum number of
 connections (for one or both z/VM guest virtual machines).
-See the SECURITY section about the required authorization statement.
+See the "SETUP FOR IUCV CONNECTIONS" section about the required authorization
+statement.
 
 .B sendmsg (2)
-called but the maximum number of outstanding IUCV messages for the socket
-connection is reached; i.e. there are data available that has not yet been
-received by the communication partner.
-.br
-If necessary, change the IUCV message limit as explained in section
-"IUCV AUTHORIZATIONS".
+called but the maximum number of outstanding messages for the socket
+connection is reached, for example, if data is available that has not
+yet been received by the communication peer.
+
+If necessary, increase the message limit using the
+.BR setsockopt (2)
+function for HiperSockets and IUCV connections.  In addition, increase the
+IUCV message limit as as explained in section "Granting IUCV authorizations".
 .
 .TP
 .B EACCES
 .BR connect (2)
 called but the calling z/VM guest virtual machine is missing IUCV authorization.
-See the SECURITY section about required IUCV authorizations.
+See the "SETUP FOR IUCV CONNECTIONS" section about required IUCV authorizations.
+.
+.TP
+.B ENODEV
+.BR connect (2)
+or
+.BR sendmsg (2)
+called but the HiperSockets device bound to the AF_IUCV socket does not exist.
+.
+.TP
+.B ENETDOWN
+.BR connect (2)
+or
+.BR sendmsg (2)
+called but the HiperSockets device bound to the AF_IUCV socket is not activated.
+.
+.TP
+.B EBADFD
+.BR connect (2)
+called but for HiperSockets connections the AF_IUCV socket is not
+bound or, for IUCV connections, the socket is neither in open nor in bound
+state.
+
+.BR bind (2)
+called but the AF_IUCV socket is no longer in open state.
+
+.BR accept (2)
+called but the AF_IUCV socket is not listening.
 .
 .TP
 .B EINVAL
 .BR connect (2)
 or
 .BR bind (2)
-called but the AF_IUCV setting in the
-.I siucv_family
-field of the passed address is missing.
+called but the \fBsiucv_family\fP field of the specified \fBsockaddr_iucv\fP
+structure is not set to \fBAF_IUCV\fP.
 
 .BR listen (2)
 called but the AF_IUCV socket has not yet been bound to an address.
@@ -320,7 +463,7 @@ called with option \fBSO_MSGLIMIT\fP for
 .
 .TP
 .B ENOPROTOOPT
-.BR setsockopt (2),
+.BR setsockopt (2)
 or
 .BR getsockopt (2)
 called but the socket level has not been set to \f(CWSOL_IUCV\fP, or the
@@ -331,7 +474,7 @@ specified socket option is not supported
 .BR sendmsg (2)
 or
 .BR recvmsg (2)
-might be called with the
+might have been called with the
 .I MSG_OOB
 flag set.
 AF_IUCV does not support sending or receiving \fIout-of-band\fP data on its
@@ -356,7 +499,7 @@ must be either zero or \f(CWPF_IUCV\fP.
 .BR socket (2)
 called with \f(CWAF_IUCV\fP but the AF_IUCV address family is not
 supported by the current Linux kernel.  Ensure that your Linux kernel has been
-compiled with support for the AF_IUCV address family.
+compiled with support for the latest version of the AF_IUCV address family.
 .
 .PP
 Other errors can be generated by the generic socket layer. See the respective
@@ -385,18 +528,28 @@ manual pages for more information.
 .SH "HISTORY"
 .TP
 .B AF_IUCV, version 1.0
+.RS 4
+.IP "\(bu" 2
 Initial version.
+.RE
+.
 .TP
 .B AF_IUCV, version 1.1
 .RS 4
-.IP "\(bu" 4
+.IP "\(bu" 2
 Support for sending socket data in the parameter list of an IUCV message
 (\f(CWSO_IPRMDATA_MSG\fP).
-.IP "\(bu" 4
+.IP "\(bu" 2
 Access the target class of an IUCV message as ancillary data using
 .BR sendmsg "(2) and " recvmsg (2).
-.IP "\(bu" 4
+.IP "\(bu" 2
 Support for \f(CWSOCK_SEQPACKET\fP sockets to facilitate development of native
 IUCV applications that interact with AF_IUCV.
 .RE
-
+.
+.TP
+.B AF_IUCV, version 1.2
+.RS 4
+.IP "\(bu" 2
+Support for HiperSockets connections.
+.RE

Places

File s390-tools-sles11sp2-afiucv-manpage-1-2.patch of Package s390-tools

Places