Addressing AF_IUCV sockets in applications

SUSE Linux Enterprise Server 15 SP5 LPAR mode z/VM guest

To use AF_IUCV sockets in applications, you must code a special AF_IUCV sockaddr structure.

Application programmers: This information is intended for programmers who want to use connections that are based on AF_IUCV addressing in their applications.

The primary difference between AF_IUCV sockets and TCP/IP sockets is how communication partners are identified (for example, how they are named). To use the AF_IUCV support in an application, code a sockaddr structure with AF_IUCV as the socket address family and with AF_IUCV address information.

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 */
};

Where:

siucv_family

is set to AF_IUCV (= 32).

siucv_port, siucv_addr, and 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_userid

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 8 characters long and, if necessary, padded at the end with blanks.

For HiperSockets connections, the siucv_userid field specifies the identifier that is set with the hsuid sysfs attribute of the HiperSockets device. For bind this is the identifier of a local device, and for connect this is the identifier of the HiperSockets device of the communication peer.

For IUCV connections, the siucv_userid field specifies a z/VM user ID. For bind this is the identifier of the local z/VM guest virtual machine, and for connect this is the identifier of the z/VM guest virtual machine for the communication peer.

Tip: For bind, you can also specify 8 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 8 characters long and, if necessary, padded with blanks at the end.

Similar to TCP or UDP ports, application names distinguish distinct applications on the same operating system instance. Do not call bind for names that begin with lnxhvc. These names are reserved for the z/VM IUCV HVC device driver.

For details, see the af_iucv man page.