sendmsg()--Send a Message Over a Socket

BSD 4.3 Syntax

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

 int sendmsg(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 sendmsg(int socket_descriptor,
                 const struct msghdr *message_structure,
                 int flags)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The sendmsg() function is used to send data or descriptors or ancillary data or a combination of these 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 written to.

message_structure

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

The address to which the message is to be sent
The vector array in which the data to be sent is stored
The ancillary data(BSD 4.4/UNIX98); or an access rights list in which the descriptors to be sent 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 to which the message is sent. For further information about the structure of socket addresses, see the Sockets 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 to be sent.

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_QOS_CLASSIFICATION_DATA

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

  struct ip_qos_classification_data {
    int    ip_qos_version;               /* Version of struct    */
    int    ip_qos_classification_scope;  /* Classification scope */
    int    ip_qos_classification_type;   /* Classification type  */
    u_char ip_qos_reserved[12];          /* Reserved             */
    int    ip_qos_appl_token_len;        /* Length of appl data  */
    /* followed by application classification data               */
};

For further information about how this structure should be initialized, see the Quality of Service topic collection.

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

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

cmsg_type

cmsg_data

IPV6_ADDR_PREFERENCES

The rest of the buffer is an integer specifying the source address selection preferences that should be used.

The valid source address selection preference flags are defined in <in.h> as:

      #define IPV6_PREFER_SRC_HOME   0x00000001 /* Prefer Home addr    */
      #define IPV6_PREFER_SRC_COA    0x00000002 /* Prefer Care-of addr */
      #define IPV6_PREFER_SRC_TMP    0x00000004 /* Prefer Temp addr    */
      #define IPV6_PREFER_SRC_PUBLIC 0x00000008 /* Prefer Public addr  */
      #define IPV6_PREFER_SRC_CGA    0x00000010 /* Prefer CGA addr     */
      #define IPV6_PREFER_SRC_NONCGA 0x00000020 /* Prefer non-CGA addr */