sendmsg()--Send Data or Descriptors or Both

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

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

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

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 access rights list to be sent

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

      struct msghdr [
        caddr_t       msg_name;
        int           msg_namelen;
        struct iovec  *msg_iov;
        int           msg_iovlen;
        caddr_t       msg_accrights;
        int           msg_accrightslen;
      ];

The msg_name and msg_namelen fields contain the address and address length to which the message is sent. For further information on the structure of socket addresses, see the Sockets Programming book. 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 msg_accrights and msg_accrightslen fields are used 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.

flags

(Input) A flag value that controls the transmission of the data. The flags value is either zero, or is obtained by performing an OR operation on one or more of the following constants:

MSG_OOB

Send data as out-of-band data. Valid only for sockets with an address family of AF_INET and type SOCK_STREAM.

MSG_DONTROUTE

Bypass routing. Valid only for sockets with address family of AF_NS or AF_INET. It is ignored for other address families.

Return Value

sendmsg() returns an integer. Possible values are:

• -1 (unsuccessful)

• n (successful), where n is the number of bytes sent.

Error Conditions

When sendmsg() fails, errno can be set to one of the following:

[EACCES]

Permission denied.

The process does not have the appropriate privileges to the destination address.

[EADDRNOTAVAIL]

Address not available.

A socket with an address family of AF_INET is using a connectionless transport service, the socket was not bound. The system tried to bind the socket but could not because a port was not available.

[EBADF]

Descriptor not valid.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

This error code can only be returned on sockets that use a connectionless transport service.

[EDESTADDRREQ]

Operation requires destination address.

A destination address has not been associated with the socket pointed to by the socket_descriptor parameter and a destination address was not set in the msghdr structure (pointed to by the message_structure parameter). This error code can only be returned on sockets that use a connectionless transport service.

[EFAULT]

Bad address.

The system detected an address which was not valid while attempting to access the message_structure parameter or a field within the structure pointed to by the message_structure parameter.

[EHOSTDOWN]

A remote host is not available.

This error code can only be returned on sockets that use a connectionless transport service.

[EHOSTUNREACH]

A route to the remote host is not available.

This error code can only be returned on sockets that use a connectionless transport service.

[EINTR]

Interrupted function call.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The msg_iovlen field or the iov_len field in a iovec structure specifies a negative value. The fields are contained in the msghdr structure (pointed to by the message_structure parameter).

• The msg_namelen field in the msghdr structure (pointed to by the message_structure parameter) specifies a length that is not valid for the address family.

• The msg_accrightslen field in the msghdr structure (pointed to by the message_structure parameter) specifies a negative value.

[EIO]

Input/output error.

[EISCONN]

A connection has already been established.

A destination address was set, but the socket pointed to by the socket_descriptor parameter already has a destination address associated with it.

[ELOOP]

A loop exists in symbolic links encountered during pathname resolution.

This error code refers to the destination address, and can only be returned by sockets that use the AF_UNIX address family.

[EMSGSIZE]

Message size out of range.

This error code indicates one of the following:

• The data to be sent could not be sent atomically because the total size of the data to be sent is too large.

• The msg_iovlen field in the msghdr structure (pointed to by the message_structure parameter) specifies a value that is greater than [MSG_MAXIOVLEN] (defined in <sys/socket.h>).

[ENAMETOOLONG]

File name too long.

This error code refers to the destination address, and can only be returned by sockets that use the AF_UNIX address family.

[ENETDOWN]

The network is not currently available.

This error code can only be returned on sockets that use a connectionless transport service.

[ENETUNREACH]

Cannot reach the destination network.

This error code can only be returned on sockets that use a connectionless transport service.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOENT]

No such file or directory.

This error code refers to the destination address, and can only be returned by sockets that use the AF_UNIX address family.

[ENOSYS]

Function not implemented.

This error code refers to the destination address, and can only be returned by sockets that use the AF_UNIX address family.

[ENOTCONN]

Requested operation requires a connection.

This error code can only be returned on sockets that use a connection-oriented transport service.

[ENOTDIR]

Not a directory.

This error code refers to the destination address, and can only be returned by sockets that use the AF_UNIX address family.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EOPNOTSUPP]

Operation not supported.

This error code indicates one of the following:

• The flags parameter specifies a value that includes the MSG_OOB flag, but the socket_descriptor parameter points to a connectionless socket.

• The flags parameter specifies a value that includes the MSG_OOB flag, but the socket_descriptor parameter points to a socket that does not have an address family of AF_INET.

• The msg_accrights and msg_accrightslen were specified and the underlying instance represented by the descriptor does not support the passing of access rights.

[EPIPE]

Broken pipe.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EUNKNOWN]

Unknown system state.

[EWOULDBLOCK]

Operation would have caused the thread to be suspended.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

Usage Notes

1. The passing of descriptors is only supported over sockets that have an address family of AF_UNIX. The msg_accrightslen and the msg_accrights fields are ignored if the socket has any other address family. When you use sendmsg() and recvmsg() to pass descriptors, the target job must be running with either of the following:
   • The same user profile as the source job (in essence, passing the descriptor to yourself)
   • *ALLOBJ special authority
   If the target job closes the receiving end of the UNIX domain socket while a descriptor is in transit, the descriptor is reclaimed by the system, and the resource that it represented is closed. For files and directories, the ability to pass descriptors using sendmsg() and recvmsg() is only supported for objects in the root and QOpenSys file systems.

2. sendmsg() is an atomic operation in that it produces one packet of data each time the call is issued on a connectionless socket. For example, a sendmsg() to a datagram socket will result in a single datagram.

3. A destination address cannot be specified if the socket pointed to by the socket_descriptor parameter already has a destination address associated with it. To not specify an address, users must set the msg_name field to NULL or set the msg_namelen field to zero. (Not specifying an address by setting the msg_namelen field to zero is an IBM extension.)

   Note: The msg_name and msg_namelen fields are ignored if the socket is using a connection-oriented transport service.

4. If the socket is using a connectionless transport device, the socket is not bound to an address, and the socket type is SOCK_DGRAM, the system automatically selects an address (INADDR_ANY and an available port number) and binds it to the socket before sending the data.

5. To broadcast on an AF_INET socket, the socket option SO_BROADCAST must be set (with a setsockopt()).

6. When using a connection-oriented transport service, all errors except [EUNATCH] and [EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following occurs:

   • A connection that is in progress is unsuccessful.

   • An established connection is broken.
   To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation (for example, read()).

7. If the socket is using an address family of AF_UNIX, the destination address (which is a path name) is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job.

8. For AF_INET sockets over SNA, type SOCK_DGRAM, if a datagram can not be delivered, no errors are returned. (As an example, a datagram might not be delivered if there is no datagram application at the remote host listening at the requested port.)

Related Information

• For additional information and sample programs on how to use sendmsg() and recvmsg() to pass descriptors between AS/400 jobs, see the Sockets Programming book.

• fcntl()--Retrieve or Change Descriptor Attributes

• ioctl()--Change Descriptor Attributes

• givedescriptor()--Pass Descriptor Access to Another Job

• send()--Send Data

• sendto()--Send Data

• takedescriptor()--Receive Socket Access from Another Job