NAME¶
iucv, AF_IUCV - Sockets for z/VM IUCV communication
SYNOPSIS¶
#include <sys/socket.h>
iucv_stream_socket = socket(AF_IUCV, SOCK_STREAM, 0);
iucv_packet_socket = socket(AF_IUCV, SOCK_SEQPACKET, 0);
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 supports stream-oriented sockets (SOCK_STREAM) and
connection-oriented datagram sockets (SOCK_SEQPACKET). 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.
Features¶
The AF_IUCV address family provides:
- •
- Multiple outgoing socket connections from a Linux guest
operating system.
- •
- Multiple incoming socket connections to a Linux guest
operating system.
- •
- Socket communication with applications utilizing CMS
AF_IUCV support.
#define AF_IUCV 32
struct sockaddr_iucv {
sa_family_t siucv_family; /* AF_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_name[8]; /* application name */
};
- siucv_family
- is set to AF_IUCV (= 32)
- siucv_port, siucv_addr, siucv_nodeid
- are reserved for future use. The siucv_port and
siucv_addr fields must be zero. The siucv_nodeid field must
be set to exactly eight blank characters.
- 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.
For 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.
- 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.
SOCKET OPTIONS¶
Socket options can be set with
setsockopt(2) and read with
getsockopt(2) by specifying SOL_IUCV as the socket level.
- 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.
To send data in the parameter list, specify a non-zero integer value.
- Note:
- Use this option with care, older AF_IUCV versions do not
support receiving socket data in the parameter list and shut down the
socket on which a parameter list message has been received.
- 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.
The message limit is an integer value in range 1 to 65535. The default value
is 65535.
The message limit must be set before connect(2) or listen(2)
is called for sockets.
For sockets that are already connected or listening for connections, the
message limit cannot be changed.
New sockets created by accept(2) inherit the message limit that has
been set for the listening socket.
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.
See the SECURITY section below for setting IUCV MSGLIMIT
authorizations.
ANCILLARY DATA¶
Ancillary data is sent and received using the
sendmsg(2) and
recvmsg(2). To send ancillary data, set the
cmsg_level field of
struct
cmsghdr to SOL_IUCV and the
cmsg_type field to the type.
For more information see
cmsg(3).
- 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.
The target class is a number of type uint32_t.
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
z/VM CP Programming Services and
z/VM CP Planning and Administration.
Granting IUCV authorizations¶
Use the
IUCV directory control statement to grant the necessary
authorizations.
- 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.
- IUCV ANY
- allows this z/VM guest virtual machine to establish a
communication path with any other z/VM guest virtual machine.
- IUCV user_ID
- allows this z/VM guest virtual machine to establish a
communication path to the z/VM guest virtual machine with the z/VM user ID
user_ID.
You can specify multiple IUCV statements. To any of these IUCV statements you
can append the
MSGLIMIT limit parameter.
limit specifies
the maximum number of outstanding messages that are allowed for each
connection authorized by this statement. If no value is specified for
MSGLIMIT, AF_IUCV requests 65535, which is the maximum supported by
IUCV.
Setting a connection limit¶
Use the
OPTION statement to limit the number of concurrent connections.
- OPTION MAXCONN maxno
- maxno specifies the maximum number of IUCV
connections allowed for this virtual machine. The default is 64. The
maximum is 65535.
Example¶
These sample statements allow any z/VM guest virtual machine to connect to your
z/VM guest virtual machine with a maximum of 10000 outstanding messages for
each incoming connection. Your z/VM guest virtual machine is permitted to
connect to all other z/VM guest virtual machines. The total number of
connections for your z/VM guest virtual machine cannot exceed 100.
IUCV ALLOW MSGLIMIT 10000
IUCV ANY
OPTION MAXCONN 100
ERRORS¶
Several socket operations return error conditions that have a special meaning in
the context of AF_IUCV. Those error conditions, and the respective
descriptions are listed below.
See the manual page of the respective socket operation for a complete list of
errors.
- ECONNREFUSED
- connect(2) called but the target z/VM guest virtual
machine is not listening on the application name.
- ENETUNREACH
- connect(2) called but the target z/VM guest virtual
machine is not logged on. Ensure that the z/VM guest virtual machine to
which your application wants to connect is logged on.
- EAGAIN
- 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 connections (for one or both z/VM guest virtual
machines). See the SECURITY section about the required authorization
statement.
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.
If necessary, change the IUCV message limit as explained in section
"IUCV AUTHORIZATIONS".
- EACCES
- connect(2) called but the calling z/VM guest virtual
machine is missing IUCV authorization. See the SECURITY section about
required IUCV authorizations.
- EINVAL
- connect(2) or bind(2) called but the AF_IUCV
setting in the siucv_family field of the passed address is missing.
listen(2) called but the AF_IUCV socket has not yet been bound to an
address. Always call bind(2) before listen(2).
setsockopt(2) called with option SO_MSGLIMIT for sockets that
are already connected.
- ENOPROTOOPT
- setsockopt(2), or getsockopt(2) called but
the socket level has not been set to SOL_IUCV, or the specified socket
option is not supported.
- EOPNOTSUPP
- sendmsg(2) or recvmsg(2) might be called with
the MSG_OOB flag set. AF_IUCV does not support sending or receiving
out-of-band data on its sockets.
For SOCK_SEQPACKET sockets, sendmsg(2) called without the
MSG_EOR flag set. AF_IUCV does not support segmentation, and thus,
the "end-of-record" ( MSG_EOR) flag must always be
set.
- EPROTONOSUPPORT
- socket(2) called with a protocol that is not
supported. The socket protocol parameter must be either zero or
PF_IUCV.
- EAFNOSUPPORT
- socket(2) called with AF_IUCV 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.
Other errors can be generated by the generic socket layer. See the respective
manual pages for more information.
SEE ALSO¶
connect(2),
recvmsg(2),
sendmsg(2),
socket(2),
setsockopt(2),
getsockopt(2),
cmsg(3),
socket(7)
Linux on System z - Device Drivers, Features, and Commands
z/VM CP Planning and Administration
z/VM CP Programming Services
HISTORY¶
- AF_IUCV, version 1.0
- Initial version.
- AF_IUCV, version 1.1
- •
- Support for sending socket data in the parameter list of an
IUCV message (SO_IPRMDATA_MSG).
- •
- Access the target class of an IUCV message as ancillary
data using sendmsg(2) and recvmsg(2).
- •
- Support for SOCK_SEQPACKET sockets to facilitate
development of native IUCV applications that interact with AF_IUCV.