recvmsg()--Receive Data or Descriptors or Both

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

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

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

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 access rights list in which the received descriptors are stored

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 reception 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

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

MSG_PEEK

Obtain a copy of the message without removing the message from the socket.

Return Value

recvmsg() returns an integer. Possible values are:

• -1 (unsuccessful)

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

Error Conditions

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

[EACCES]

Permission denied.

The socket pointed to by the socket_descriptor parameter is using a connection-oriented transport service, and a connect() was previously completed. The process, however, does not have the appropriate privileges to the objects that were needed to establish a connection. For example, the connect() required the use of an APPC device that the process was not authorized to.

If the msg_accrights and msg_accrightslen fields were specified, this error indicates that this job does not have the appropriate privileges required to receive the descriptor. When this occurs, the descriptor is reclaimed by the system and the resource that it represented is closed.

[EBADF]

Descriptor not valid.

[ECONNABORTED]

Connection ended abnormally.

This error code indicates that the transport provider ended the connection abnormally because of one of the following:

• The retransmission limit has been reached for data that was being sent on the socket.

• A protocol error was detected.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[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.

[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 flags parameter specifies a value that includes the MSG_OOB flag, but no OOB data was available to be received.

• The flags parameter specifies a value that includes the MSG_OOB flag, and the socket option SO_OOBINLINE has been set.

• The socket_descriptor parameter points to a socket that is using a connectionless transport service, is not a socket of type SOCK_RAW, and is not bound to an address.

• The msg_accrightslen field in the msghdr structure specifies a negative value.

[EIO]

Input/output error.

[EMFILE]

Too many descriptions for this process.

[EMSGSIZE]

Message size out of range.

The msg_iovlen field specifies a value that is greater than [MSG_MAXIOVLEN] (defined in <sys/socket.h>).

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTCONN]

Requested operation requires a connection.

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

[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.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

A non-blocking connect() was previously issued that resulted in the connection establishment timing out. No connection is established. This error code is returned only on sockets that use a connection-oriented transport service.

[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 following applies to sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM),

   • The msg_name and msg_namelen fields in the structure pointed to by the message_structure parameter are ignored.

   • A returned value of zero indicates one of the following:

     • The partner program has issued a close() for the socket.

     • The partner program has issued a shutdown() to disable writing to the socket.

     • The connection is broken and the error was returned on a previously issued socket function.

     • A shutdown() to disable reading was previously done on the socket.

2. For sockets that have a type of SOCK_SEQPACKET, each output operation by the partner program constitutes one record. If the record length is larger than the value specified by the buffer_length parameter, the remaining data from the record is discarded.

3. The following applies to sockets that use a connectionless transport service (for example, a socket with a type of SOCK_DGRAM):

   • If a connect() has been issued previously, then data can be received only from the address specified in the previous connect().

   • If the msg_name field is set to NULL or msg_namelen field specifies a value of zero, the address from which data is received is discarded.

   • If the length of the address to be returned exceeds the length specified by the msg_namelen field, the returned address is truncated.

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

   • The entire message must be read in a single read operation. If the size of the message is too large to fit in the user supplied buffer, the remaining bytes of the message are discarded.

   • A returned value of zero indicates one of the following:

     • The partner program has sent a NULL message (a datagram with no user data).

     • A shutdown() to disable reading was previously done on the socket.

     • The buffer length specified was zero.

4. 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. The value of msg_accrightslen should be checked to determine if a descriptor has been returned. 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.

   Note: The recvmsg() API will not block unless a data buffer is specified.

5. recvmsg() accepts a pointer to an array of iovec structures in the msghdr structure. The msg_iovlen field is used to determine the number of elements in the array (the number of iovec structures specified). When recvmsg() is issued, the system processes the array elements one at a time, starting with the first structure. For each element of the array (for each structure), iov_len bytes of received data are placed in storage pointed to by iov_base. Data is placed in storage until all buffers are full, or until there is no more data to receive. Only the memory pointed to by iov_base is updated. No change is made to the iov_len fields. To determine the end of the data, the application program must use the following:

   • The function return value (the total number of bytes received).

   • The lengths of the buffers pointed to by iov_base.

Related Information

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

• fcntl()--Retrieve or Change Descriptor Attributes

• ioctl()--Change Descriptor Attributes

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

• recv()--Receive Data

• recvfrom()--Receive Data

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