gtpc1m48 | Transmission Control Protocol/Internet Protocol |
The recvmsg function receives messages on a socket with
descriptor s and stores them in an array of message headers.
Format
#include <socket.h>
ssize_t recvmsg(int s,
struct msghdr *msg,
int flags);
- s
- The socket descriptor.
- msg
- A pointer to the message header that receives the messages.
- flags
- Must be set to 0 or one or more of the following flags. If you
specify more than one flag, use the logical OR operator (|) to separate
them:
- MSG_OOB
- Reads any out-of-band data on the socket.
- MSG_PEEK
- Peeks at the data that is present on the socket; the data is returned
but not changed so a later receive operation sees the same data.
- Note:
- Setting this parameter is supported for sockets in the AF_INET domain, but
not supported for sockets in the AF_IUCV domain.
Normal Return
If successful, the function returns the length of the data received or the
entire datagram (provided the datagram fits into the specified buffer).
Error Return
A return code equal to -1 indicates an error. You can get the
specific error code by calling sock_errno. See Appendix C, Socket Error Return Codes for more information about socket errors.
- Note:
- The following error codes can be returned for either TCP/IP offload support
or TCP/IP native stack support.
- Value
- Description
- EINVAL
- msg_namelen is not the size of a valid address for the
specified address family.
- EMSGSIZE
- Either the message is too big to be received as a single datagram or the
iovector count is greater than or equal to UIO_MAXIOV, as defined
in socket.h.
- ENOBUFFS
- Buffer space is not available to receive the message.
- ENOMEM
- There is no memory allocating buffer space to hold all messages in the
iovec array.
- EWOULDBLOCK
- The s parameter is in nonblocking mode and data is not
available to read.
- SOCBADF
- The s parameter is not a valid socket descriptor.
- SOCFAULT
- Using msg would result in an attempt to access memory outside
the address space of the caller..
- SOCNOTSOCK
- The s parameter is not a valid socket descriptor.
Programming Considerations
- The recvmsg function receives messages on a socket with
descriptor s and stores them in an array of message headers as
defined by the msghdr structure in the socket.h
header file.
- The recvmsg function applies to sockets whether they are in
connected or unconnected state.
- If the data is not available for socket s and s is
in blocking mode, the recvmsg function blocks the caller until data
arrives; if s is in nonblocking mode, -1 is returned and
sock_errno is set to EWOULDBLOCK.
- Applications using stream sockets must place the recvmsg
function in a loop until all data has been received.
- For sockets using TCP/IP native stack support, the receive timeout value
(the SO_RCVTIMEO setsockopt option) determines how long to wait for
data to be received before the recvmsg function times out.
- For TCP sockets using TCP/IP native stack support, the receive low-water
mark (the SO_RCVLOWAT setsockopt option) determines the minimum
amount of data that must be received before the recvmsg function
ends. If the recvmsg function times out, any data that was
received is returned to the application even if the amount of data received is
less than the receive low-water mark value.
- The recvmsg function cannot be issued if an
activate_on_receipt call is pending for the socket. These
operations are mutually exclusive.
Examples
In the following example, the application issues a recvmsg
function to receive messages on a socket.
#include <socket.h>
struct msghdr msg;
int sock; /* UNIX socket handle */
rpc_socket_iovec_p_t iovp; /* array of bufs for rec'd data */
int iovlen; /* number of bufs */
rpc_addr_p_t addrp; /* address of sender */
int *ccp; /* returned number of bytes actually rec'd */
·
·
·
msg.msg_iov = (struct iovec *) iovp;
msg.msg_iovlen = iovlen;
msg.msg_accrights = NULL;
msg.msg_name = (caddr_t) &(addrp)->sa:
msg.msg_namelen = (addrp)->len;
*(ccp) = recvmsg ((int) sock, (struct msghdr *) &msg, 0);
Related Information