| AF_IUCV(7) | Linux Programmer's Manual | AF_IUCV(7) |
AF_IUCV - Sockets for z/VM IUCV and HiperSockets communication
#include <sys/socket.h>
#include <netiucv/iucv.h>
iucv_stream_socket = socket(AF_IUCV, SOCK_STREAM,
0);
iucv_packet_socket = socket(AF_IUCV, SOCK_SEQPACKET, 0);
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).
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:
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:
The AF_IUCV address family supports stream-oriented sockets (SOCK_STREAM) and connection-oriented datagram sockets (SOCK_SEQPACKET). 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.
For all instances of Linux on System z, the AF_IUCV address family provides:
For instances of Linux on z/VM, the AF_IUCV address family also provides:
An AF_IUCV socket is represented by the following format:
#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_user_id[8]; /* user id */
char siucv_name[8]; /* application name */
};
This field must be eight characters long and, if necessary, padded with blanks on the right.
For HiperSockets connections, the siucv_user_id field specifies the identifier that is set with the hsuid sysfs attribute of the HiperSockets device. For bind(2) this is the identifier of a local device, and for connect(2) this is the identifier of the HiperSockets device of the communication peer.
For IUCV connections, the siucv_user_id field specifies a z/VM user ID. For bind(2) this is the identifier of the local z/VM guest virtual machine, and for connect(2) this is the identifier of the z/VM guest virtual machine for the communication peer.
Similar to TCP or UDP ports, application names distinguish distinct applications on the same operating system instance. Do not call bind(2) for names beginning with lnxhvc. These names are reserved for the z/VM IUCV HVC device driver (see also hvc_iucv(9)).
Socket options can be set with setsockopt(2) and read with getsockopt(2) by specifying SOL_IUCV as the socket level.
To send data in the parameter list, specify a non-zero integer value.
The message limit is an integer value in range 1 to 65535. The default value is 65535 for IUCV connections and 128 for HiperSockets connections.
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. For IUCV connections, there are two parameters that specify the message limit: 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 "SETUP FOR IUCV CONNECTIONS" section for setting IUCV MSGLIMIT authorizations.
Ancillary data is sent and received using 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 a type of ancillary data that is supported by the
AF_IUCV address family.
For more information see cmsg(3).
Currently, the only supported type is:
The target class is a number of type uint32_t.
This section applies to HiperSockets connections and explains the configuration of a HiperSockets device used for AF_IUCV address family support.
To run an AF_IUCV socket application using HiperSockets connections, the socket must be bound to a particular HiperSockets device configured with layer3 mode. Use the hsuid attribute of a HiperSockets device to identify it to the AF_IUCV address family support.
The identifier must adhere to these rules:
To set an identifier, issue a command like this:
You can then address this device by specifying the hsuid as the value for the siucv_user_id field in the sockaddr_iucv addressing structure.
For example, to use "MYHOST01" to bind AF_IUCV sockets to the HiperSockets device with bus-ID 0.0.8000, run:
echo "MYHOST01" > /sys/devices/qeth/0.0.8000/hsuid
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 z/VM CP Programming Services and z/VM CP Planning and Administration.
Use the IUCV directory control statement to grant the necessary authorizations.
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, the maximum, 65535, is used.
Use the OPTION statement to limit the number of concurrent connections.
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
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.
sendmsg (2) 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 setsockopt(2) function for HiperSockets and IUCV connections. In addition, increase the IUCV message limit as as explained in section "Granting IUCV authorizations".
bind(2) called but the AF_IUCV socket is no longer in open state.
accept(2) called but the AF_IUCV socket is not listening.
getsockopt(2) called but the AF_IUCV socket is not bound.
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.
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.
Other errors can be generated by the generic socket layer. See the respective manual pages for more information.
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
| August 2011 | s390-tools |