Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
openSUSE:12.2
s390-tools
s390-tools-sles11sp2-afiucv-manpage-1-2.patch
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
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor