Using ancillary data on sendmsg() and recvmsg()

The sendmsg() API is similar to other socket APIs, such as send() and write() that allow an application to send data, but also provides the capability of specifying ancillary data. Ancillary data allows applications to pass additional option data to the TCP/IP protocol stack along with the normal data that is sent to the IP network.

The recvmsg() API is similar to other socket APIs, such as recv() and read(), that allow an application to receive data, but also provides the capability of receiving ancillary data. Ancillary data allows the TCP/IP protocol stack to return additional option data to the application along with the normal data from the IP network.

These sendmsg() and recvmsg() API extensions are available only to applications using the following socket API libraries:

z/OS® IBM® C/C++ sockets with the z/OS Language Environment®. For more information about these APIs, see z/OS XL C/C++ Runtime Library Reference.
z/OS UNIX Assembler Callable services socket APIs. For more information about these APIs, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.

For the sendmsg() and recvmsg() APIs most parameters are passed in a message header input parameter. The mapping for the message header is defined in socket.h for C/C++ and in the BPXYMSGH macro for users of the z/OS UNIX Assembler Callable services. For simplicity, only the C/C++ version of the data structures is shown in the following code example:

struct msghdr {         
    void               *msg_name;              /* optional address           */   
    size_t             msg_namelen;            /* size of address            */  
    struct             iovec *msg_iov;         /* scatter/gather array       */  
    int                msg_iovlen;             /* # elements in msg_iov      */  
    void               *msg_control;           /* ancillary data             */  
    size_t             msg_controllen;         /* ancillary data length      */
    int                msg_flags;              /* flags on received msg      */  
 };

Notes:

The msg_name and msg_namelen parameters are used to specify the destination sockaddr on a sendmsg(). On a recvmsg() the msg_name and msg_namelen parameters are used to return the remote sockaddr to the application.
Data to be sent using sendmsg() needs to be described in the msg_iov structure. On recvmsg() the received data is described in the msg_iov structure.
The address of the ancillary data is passed in the msg_control field.
The length of the ancillary data is passed in msg_controllen. Note that if multiple ancillary data sections are being passed, this length should reflect the total length of ancillary data sections.
msg_flags is not applicable for sendmsg().

The msg_control parameter points to the ancillary data. This msg_control pointer points to the following structure (C/C++ example shown) that describes the ancillary data (also defined in socket.h and BPXYMSGH):

struct cmsghdr  {              
      size_t   cmsg_len;       /* data byte count includes hdr */ 
      int      cmsg_level;     /* originating protocol         */ 
      int      cmsg_type;      /* protocol-specific type       */ 
     /* followed by u_char    cmsg_data[]; */
   };

Guidelines:

The cmsg_len should be set to the length of the cmsghdr plus the length of all ancillary data that follows immediately after the cmsghdr. This is represented by the commented out cmsg_data field.
The cmsg_level should be set to the option level (for example, IPPROTO_IPV6).
The cmsg_type should be set to the option name (for example, IPV6_USE_MIN_MTU).