oxmox
7063e2102e
git-subtree-dir: external/nng git-subtree-split: 29b73962b939a6fbbf6ea8d5d7680bb06d0eeb99
94 lines
3.5 KiB
Text
94 lines
3.5 KiB
Text
= nng_sendmsg(3)
|
|
//
|
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
|
//
|
|
// This document is supplied under the terms of the MIT License, a
|
|
// copy of which should be located in the distribution where this
|
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
|
// found online at https://opensource.org/licenses/MIT.
|
|
//
|
|
|
|
== NAME
|
|
|
|
nng_sendmsg - send message
|
|
|
|
== SYNOPSIS
|
|
|
|
[source, c]
|
|
----
|
|
#include <nng/nng.h>
|
|
|
|
int nng_sendmsg(nng_socket s, nng_msg *msg, int flags);
|
|
----
|
|
|
|
== DESCRIPTION
|
|
|
|
The `nng_sendmsg()` sends message _msg_ using the socket _s_.
|
|
|
|
If the function returns zero, indicating it has accepted the message for
|
|
delivery, then the _msg_ is owned by the socket _s_, and the caller
|
|
must not make any further use of it.
|
|
The socket will free the message when it is finished.
|
|
|
|
If the function returns non-zero, then it is the caller's responsibility
|
|
to dispose of the _msg_, which may include freeing it, sending it to
|
|
another socket, or simply trying again later.
|
|
|
|
TIP: Using this function gives access to the message structure, and may
|
|
offer more functionality than the simpler xref:nng_send.3.adoc[`nng_send()`] function.
|
|
|
|
NOTE: The semantics of what sending a message means vary from protocol to
|
|
protocol, so examination of the protocol documentation is encouraged.
|
|
(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
|
|
any peers who have a suitable subscription will be able to receive it using
|
|
xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
|
|
Furthermore, some protocols may not support sending (such as
|
|
xref:nng_sub.7.adoc[_sub_]) or may require other conditions.
|
|
(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which
|
|
are responses to requests, until they have first received a request.)
|
|
|
|
The _flags_ may contain the following value:
|
|
|
|
`NNG_FLAG_NONBLOCK`::
|
|
The function returns immediately, regardless of whether
|
|
the socket is able to accept the data or not.
|
|
If the socket is unable to accept the data (such as if backpressure exists
|
|
because the peers are consuming messages too slowly, or no peer is present),
|
|
then the function will return with `NNG_EAGAIN`.
|
|
If this flag is not specified, then the function will block if such a
|
|
condition exists.
|
|
|
|
|
|
NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may
|
|
be queues between the sender and the receiver.
|
|
Furthermore, there is no guarantee that the message has actually been delivered.
|
|
Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`,
|
|
such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only.
|
|
|
|
== RETURN VALUES
|
|
|
|
This function returns 0 on success, and non-zero otherwise.
|
|
|
|
== ERRORS
|
|
|
|
[horizontal]
|
|
`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_EMSGSIZE`:: The value of _size_ is too large.
|
|
`NNG_ENOMEM`:: Insufficient memory is available.
|
|
`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending.
|
|
`NNG_ESTATE`:: The socket _s_ cannot send data in this state.
|
|
`NNG_ETIMEDOUT`:: The operation timed out.
|
|
|
|
== SEE ALSO
|
|
|
|
[.text-left]
|
|
xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
|
|
xref:nng_recvmsg.3.adoc[nng_recvmsg(3)],
|
|
xref:nng_send.3.adoc[nng_send(3)],
|
|
xref:nng_strerror.3.adoc[nng_strerror(3)],
|
|
xref:nng_msg.5.adoc[nng_msg(5)],
|
|
xref:nng_socket.5.adoc[nng_socket(5)],
|
|
xref:nng.7.adoc[nng(7)]
|