1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
# nng_recvmsg
## NAME
nng_recvmsg --- receive a message
## SYNOPSIS
```c
#include <nng/nng.h>
int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags);
```
## DESCRIPTION
The `nng_recvmsg()` receives a [message][msg] on [socket][socket] _s_, storing the
received message at the location pointed to by _msgp_.
This function gives access to the message structure, and thus may
offer more functionality than the simpler [`nng_recv()`][nng_recv] function.[^1] [^2]
[^1]: It is also more efficient.
[^2]: An asynchronous form of this function is available as [`nng_recv_aio()`][nng_recv_aio].
The _flags_ may contain the following value:
- {{i:`NNG_FLAG_NONBLOCK`}}: \
The function returns immediately, even if no message is available.
Without this flag, the function will wait until a message is received
by the socket _s_, or any configured timer expires.
After successfully receiving a message, the caller is responsible for
disposing of it when it is no longer needed.
> [!IMPORTANT]
> Failing to dispose of the message will leak the memory associated with it.
> [!NOTE]
> The semantics of what receiving a message means vary from protocol to
> protocol, so examination of the protocol documentation is encouraged.
> Furthermore, some protocols do not support receiving data at all, or
> may require other conditions be met before receiving messages.
## RETURN VALUES
This function returns 0 on success, and non-zero otherwise.
## ERRORS
- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
- `NNG_ECLOSED`: The socket _s_ is not open.
- `NNG_EINVAL`: An invalid set of _flags_ was specified.
- `NNG_ENOMEM`: Insufficient memory is available.
- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
- `NNG_ETIMEDOUT`: The operation timed out.
## SEE ALSO
[Messages][msg],
[Sockets][socket],
[nng_msg_free][nng_msg_free],
[nng_recv][nng_recv],
[nng_sendmsg][nng_sendmsg]
{{#include ../refs.md}}
|
