1= nng_recv(3) 2// 3// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> 4// Copyright 2018 Capitar IT Group BV <info@capitar.com> 5// 6// This document is supplied under the terms of the MIT License, a 7// copy of which should be located in the distribution where this 8// file was obtained (LICENSE.txt). A copy of the license may also be 9// found online at https://opensource.org/licenses/MIT. 10// 11 12== NAME 13 14nng_recv - recv data 15 16== SYNOPSIS 17 18[source, c] 19---- 20#include <nng/nng.h> 21 22int nng_recv(nng_socket s, void *data, size_t *sizep, int flags); 23---- 24 25== DESCRIPTION 26 27The `nng_recv()` receives a message. 28 29The _flags_ is a bit mask that may contain any of the following values: 30 31`NNG_FLAG_NONBLOCK`:: 32 The function returns immediately, even if no message is available. 33 Without this flag, the function will wait until a message is received 34 by the socket _s_, or any configured timer expires. 35 36`NNG_FLAG_ALLOC`:: 37 If this flag is present, then a ((zero-copy)) mode is used. 38 In this case the caller must set the value of _data_ to the location 39 of another pointer (of type `void *`), and the _sizep_ pointer must be set 40 to a location to receive the size of the message body. 41 The function will then allocate a message buffer 42 (as if by xref:nng_alloc.3.adoc[`nng_alloc()`]), fill it with 43 the message body, and store it at the address referenced by _data_, and update 44 the size referenced by _sizep_. 45 The caller is responsible for disposing of the received buffer either by 46 the xref:nng_free.3.adoc[`nng_free()`] function or passing the message (also 47 with the `NNG_FLAG_ALLOC` flag) in a call to xref:nng_send.3.adoc[`nng_send()`]. 48 49If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the 50caller must set _data_ to a buffer to receive the message body content, 51and must store the size of that buffer at the location pointed to by _sizep_. 52When the function returns, if it is successful, the size at _sizep_ will be 53updated with the actual message body length copied into _data_. 54 55NOTE: The semantics of what receiving a message means vary from protocol to 56protocol, so examination of the protocol documentation is encouraged. 57(For example, with a xref:nng_req.7.adoc[_req_] socket a message may only be received 58after a request has been sent, and a xref:nng_sub.7.adoc[_sub_] socket 59may only receive messages corresponding to topics to which it has subscribed.) 60Furthermore, some protocols may not support receiving data at all, such as 61xref:nng_pub.7.adoc[_pub_]. 62 63TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby 64increasing performance, particularly if the buffer is reused to send 65a response using the same flag. 66 67== RETURN VALUES 68 69This function returns 0 on success, and non-zero otherwise. 70 71== ERRORS 72 73[horizontal] 74`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. 75`NNG_ECLOSED`:: The socket _s_ is not open. 76`NNG_EINVAL`:: An invalid set of _flags_ was specified. 77`NNG_EMSGSIZE`:: The received message did not fit in the size provided. 78`NNG_ENOMEM`:: Insufficient memory is available. 79`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving. 80`NNG_ESTATE`:: The socket _s_ cannot receive data in this state. 81`NNG_ETIMEDOUT`:: The operation timed out. 82 83== SEE ALSO 84 85[.text-left] 86xref:nng_alloc.3.adoc[nng_alloc(3)], 87xref:nng_free.3.adoc[nng_free(3)], 88xref:nng_recvmsg.3.adoc[nng_recvmsg(3)], 89xref:nng_send.3.adoc[nng_send(3)], 90xref:nng_strerror.3.adoc[nng_strerror(3)], 91xref:nng.7.adoc[nng(7)] 92