NAME¶
AF_IUCV - Sockets for z/VM IUCV and HiperSockets communication
SYNOPSIS¶
#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);
DESCRIPTION¶
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:
- •
- Itself
- •
- Other applications running on the same Linux instance
- •
- An application on an instance of Linux on System z in another LPAR
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:
- •
- Itself
- •
- Other applications running on the same Linux instance
- •
- Applications running on other instances of Linux on z/VM within the same
z/VM system
- •
- Applications running on a z/VM guest other than Linux within the same z/VM
system
- •
- The z/VM control program (CP)
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.
Features¶
For all instances of Linux on System z, the AF_IUCV address family provides:
- •
- Multiple outgoing socket connections for real HiperSockets
- •
- Multiple incoming socket connections for real HiperSockets
For instances of Linux on z/VM, the AF_IUCV address family also provides:
- •
- Multiple outgoing socket connections for IUCV
- •
- Multiple incoming socket connections for IUCV
- •
- Socket communication with applications utilizing CMS AF_IUCV support
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 */
};
- 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 blanks.
- siucv_user_id
- 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 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.
- Tip:
- For 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.
- 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, 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
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¶
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 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.
- 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 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 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.
- SO_MSGSIZE
- getsockopt(2) returns the maximum message size a bound AF_IUCV
socket can handle. The maximum message size for connections through
HiperSockets depends on the MTU size of the underlying HiperSockets
connection.
For sockets that are not yet bound the maximum message size cannot be
determined.
ANCILLARY DATA¶
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:
- 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 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 uint32_t.
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.
To run an AF_IUCV socket application using HiperSockets connections, the socket
must be bound to a particular HiperSockets device. 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:
- •
- It must be 1 to 8 characters.
- •
- It must be unique across your environment.
- •
- It must not match any z/VM user ID in your environment.
To set an identifier, issue a command like this:
echo identifier >
/sys/devices/qeth/<bus-ID>/hsuid
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
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
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 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.
- 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, the maximum, 65535, is used.
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 system 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 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
"SETUP FOR IUCV CONNECTIONS" section about the required
authorization statement.
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".
- EACCES
- connect(2) called but the calling z/VM guest virtual machine is
missing IUCV authorization. See the "SETUP FOR IUCV CONNECTIONS"
section about required IUCV authorizations.
- ENODEV
- connect(2) or sendmsg(2) called but the HiperSockets device
bound to the AF_IUCV socket does not exist.
- ENETDOWN
- connect(2) or sendmsg(2) called but the HiperSockets device
bound to the AF_IUCV socket is not activated.
- EBADFD
- 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.
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.
- EINVAL
- connect(2) or bind(2) called but the siucv_family
field of the specified sockaddr_iucv structure is not set to
AF_IUCV.
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 have been 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 latest version of the AF_IUCV address
family.
- EADDRINUSE
- bind(2) called with an siucv_name already used for another
AF_IUCV socket.
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
- 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.
- AF_IUCV, version 1.2
- •
- Support for HiperSockets connections.