nn_recvmsg(3)
=============

NAME
----
nn_recvmsg - fine-grained alternative to nn_recv


SYNOPSIS
--------
*#include <nanomsg/nn.h>*

*NN_EXPORT int nn_recvmsg (int 's', struct nn_msghdr '*msghdr', int 'flags');*


DESCRIPTION
-----------
Receives a message from socket 's' into buffers specified by 'msghdr' paramter
along with any additional control data. 'msghdr' parameter should be nullified
before beign used.

Structure 'nn_msghdr' contains at least following members:

    struct nn_iovec *msg_iov;
    int msg_iovlen;
    void *msg_control;
    size_t msg_controllen;

'msg_iov' points to a gather array of buffers to fill in. 'msg_iovlen' specifies
the size of the array.

'msg_control' points to the buffer to hold control information  associated with
the received message. 'msg_controllen' specifies the length of the buffer.
If the control information should not be retrieved, set 'msg_control' parameter
to NULL. For detailed discussion of how to parse the control information check
linknanomsg:nn_cmsg[3] man page.

Structure 'nn_iovec' defines one element in the gather array (a buffer to be
filled in by message data) and contains following members:

    void *iov_base;
    size_t iov_len;

Alternatively, _nanomsg_ library can allocate the buffer for you. To do so,
let the 'iov_base' point to void* variable to receive the buffer and set
'iov_len' to _NN_MSG_. After successful completion user is responsible
for deallocating the message using linknanomsg:nn_freemsg[3] function. Gather
array in _nn_msghdr_ structure can contain only one element in this case.

The 'flags' argument is a combination of the flags defined below:

*NN_DONTWAIT*::
Specifies that the operation should be performed in non-blocking mode. If the
message cannot be received straight away, the function will fail with 'errno'
set to EAGAIN.


RETURN VALUE
------------
If the function succeeds number of bytes in the message is returned. Otherwise,
negative number is returned and 'errno' is set to to one of the values defined
below.


ERRORS
------
*EBADF*::
The provided socket is invalid.
*ENOTSUP*::
The operation is not supported by this socket type.
*EFSM*::
The operation cannot be performed on this socket at the moment because socket is
not in the appropriate state.  This error may occur with socket types that
switch between several states.
*EAGAIN*::
Non-blocking mode was requested and there's no message to receive at the moment.
*EINTR*::
The operation was interrupted by delivery of a signal before the message was
received.
*ETIMEDOUT*::
Individual socket types may define their own specific timeouts. If such timeout
is hit this error will be returned.
*ETERM*::
The library is terminating.

EXAMPLE
-------

----
struct nn_msghdr hdr;
struct nn_iovec iov [2];
char buf0 [4];
char buf1 [2];
iov [0].iov_base = buf0;
iov [0].iov_len = sizeof (buf0);
iov [1].iov_base = buf1;
iov [1].iov_len = sizeof (buf1);
memset (&hdr, 0, sizeof (hdr));
hdr.msg_iov = iov;
hdr.msg_iovlen = 2;
nn_recvmsg (s, &hdr, 0);
----


SEE ALSO
--------
linknanomsg:nn_recv[3]
linknanomsg:nn_sendmsg[3]
linknanomsg:nn_allocmsg[3]
linknanomsg:nn_freemsg[3]
linknanomsg:nn_cmsg[3]
linknanomsg:nanomsg[7]


AUTHORS
-------
Martin Sustrik <sustrik@250bpm.com>