recvmsg()--Receive a Message Over a Socket

BSD 4.3 Syntax

  #include <sys/types.h>
  #include <sys/socket.h>

 int recvmsg(int socket_descriptor,
             struct msghdr *message_structure,
             int flags)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

UNIX^® 98 Compatible Syntax

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 ssize_t recvmsg(int socket_descriptor,
                 struct msghdr *message_structure,
                 int flags)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The recvmsg() function is used to receive data or descriptors or both through a connected or unconnected socket.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

socket_descriptor

(Input) The socket descriptor that is to be read from.

message_structure

(I/O) The pointer to the message structure that contains the following:

The address from which the message was received
The vector array in which the data received is stored
The ancillary data(BSD 4.4/UNIX98); or an access rights list in which the descriptors received are stored.

The structure pointed to by the message_structure parameter is defined in <sys/socket.h>.

The BSD 4.3 structure is:

      struct msghdr {
        caddr_t       msg_name;
        int           msg_namelen;
        struct iovec *msg_iov;
        int           msg_iovlen;
        caddr_t       msg_accrights;
        int           msg_accrightslen;
      };

The BSD 4.4/UNIX 98 compatible structure is:

      struct msghdr {
        void         *msg_name;
        socklen_t     msg_namelen;
        struct iovec *msg_iov;
        int           msg_iovlen;
        void         *msg_control;      /* Set to NULL if not needed  */
        socklen_t     msg_controllen;   /* Set to 0 if not needed     */
        int           msg_flags;
      };

The msg_name and msg_namelen fields contain the address and address length from which the message was received. For further information about the structure of socket addresses, see the Socket programming topic collection. If the msg_name field is set to a NULL pointer, the address information is not returned.

The msg_iov and msg_iovlen fields are for scatter/gather I/O.

The BSD 4.3 structure uses the msg_accrights and msg_accrightslen fields to pass descriptors. The msg_accrights field is a list of zero or more descriptors, and msg_accrightslen is the total length (in bytes) of the descriptor list.

The BSD 4.4/UNIX 98 compatible structure uses the msg_control and msg_controllen fields to pass ancillary data. The msg_control field is a pointer to ancillary data (of length msg_controllen) with the form:

     struct cmsghdr {
           socklen_t cmsg_len;    /* # bytes, including this header */
           int       cmsg_level;  /* originating protocol           */
           int       cmsg_type;   /* protocol-specific type         */
                         /* followed by unsigned char cmsg_data[];  */
     };

The cmsg_len field is the total length including this header. cmsg_level is the originating protocol. cmsg_type is the protocol-specific type. If ancillary data and descriptors are not being passed, the msg_control field must be initialized to NULL and the msg_controllen field must be initialized to 0. The following tables list the supported ancillary data types when using the BSD 4.4/UNIX 98 compatible structures.

Ancillary Data Types That Apply to the Socket Layer (where cmsg_level is SOL_SOCKET ):

cmsg_type

cmsg_data

SCM_RIGHTS

The rest of the buffer is a list of zero or more descriptors received.

This ancillary data type is only supported for sockets with an address family of AF_UNIX or AF_UNIX_CCSID.

Ancillary Data Types That Apply to the IP Layer (where cmsg_level is IPPROTO_IP):

cmsg_type

cmsg_data

IP_PKTINFO

The rest of the buffer is an in_pktinfo structure. This structure is defined in <netinet/in.h> as:

  struct in_pktinfo {
    struct in_addr ipi_addr;       /* IPv4 destination address     */
    struct in_addr ipi_interface;  /* Interface which pkt was rcvd */
  };

The ipi_addr field specifies the IPv4 destination address.
The ipi_interface field specifies the interface on which the packet was received.

This ancillary data type is only supported for sockets with an address family of AF_INET and a type of SOCK_DGRAM or SOCK_RAW.

Ancillary Data Types That Apply to the IPv6 Layer (where cmsg_level is IPPROTO_IPV6):

cmsg_type

cmsg_data

IPV6_DSTOPTS

The rest of the buffer is an ip6_dest structure. This structure is defined in <netinet/ip6.h> as:

   struct ip6_dest {
      uint8_t  ip6d_nxt;        /* next header */
      uint8_t  ip6d_len;        /* length in units of 8 octets */
      /* followed by options */
   };

    The ip6d_nxt field specifies the option type of the next header in the chain of headers.
    The ip6d_len field specifies the length of the destination header in units of 8 octets, not including the first 8 octets.
    For further information about how to parse this structure, see inet6_opt_next().