.TH recvmsg 3 "MiNT-Net"

.SH NAME

recvmsg \- receive a message on a socket

.SH SYNOPSIS

.B #include <sys/socket.h>

.PP

.B "int recvmsg(int s, struct msghdr *msg, int flags);"

.PP

.SH DESCRIPTION

.I recvmsg

is used to receive a message from another socket.

.I s

is a socket descriptor that specifies the socket

on which the message will be received.

.I msg

points to an object of type

.B struct\ msghdr

into which the received message will be placed.

.B struct\ msghdr

is explained below.

.PP

.I recvmsg

operates the same way as

.IR recvfrom ,

except that it is able to scatter the data into

the

.B msg_iov

member of

.BR "struct\ msghdr" .

Note that receiving of access rights is not implemented.

Do not rely on this behavior,

because it might change in the future.

.PP

.B struct\ msghdr

is defined in

.RB < sys/socket.h >,

and has the following form :

.IP

.nf

struct msghdr {

void *msg_name; /* optional address */

size_t msg_namelen; /* size of address */

struct iovec *msg_iov; /* scatter array for data */

size_t msg_iovlen; /* # of elements in msg_iov */

void *msg_accrights; /* access rights */

size_t msg_accrightslen; /* size of msg_accrights */

}

.fi

.PP

.I msg_name

contains the source address of the message;

.I msg_name

may be a null pointer if you are not interested in this information.

.I msg_iov

is the location of the scatter data.

.I msg_accrights

specifies a buffer to receive any access rights along

with the message.

Transfer of access rights is not implemented,

so you should

set the msg_acccrights field to

.SM NULL

indicating that access rights are not being transferred.

.PP

See

.I recvfrom(3)

to learn more about the behavior of

.IR recvmsg .

.SH RETURN VALUE

If the

.I recvmsg

call is successful, it returns the number of bytes received.

If the call fails, \-1 is returned and an error code is stored in

.BR errno .

.SH DIAGNOSTICS

The call to

.I recvmsg

fail if:

.RS

.TP 20

.SM [EBADF]

The argument

.I s

is an invalid descriptor.

.TP

.SM [EINVAL]

The argument

.I s

is not a socket.

The

.I msg

parameter contains invalid members.

.TP

.SM [ENOMEM]

There is insufficient buffer space to send the message.

.TP

.SM [EINTR]

The receive was interrupted by delivery of a signal

before any data was available for the receive.

.TP

.SM [ENOTCONN]

Receive on a

.SM SOCK_STREAM

socket that is not yet connected.

.TP

.SM [EOPNOTSUPP]

The

.SM MSG_OOB

or

.SM MSG_PEEK

flag was set for any

.SM AF_UNIX

socket.

Neither

.SM MSG_PEEK

nor

.SM MSG_OOB

is supported

for

.SM AF_UNIX

sockets.

.SH SEE ALSO

getsockopt(3),

select(3),

recv(3),

recvfrom(3),

socket(3).