[nanomsg] Re: nn_sendmsg man page vs. source code
- From: Boszormenyi Zoltan <zboszor@xxxxx>
- To: Martin Sustrik <sustrik@xxxxxxxxxx>, nanomsg@xxxxxxxxxxxxx
- Date: Tue, 24 Sep 2013 12:16:53 +0200
2013-09-24 10:55 keltezéssel, Martin Sustrik írta:
Hi Zoltan,
I am reading the source of nanomsg and found some a little inconsistency.
in nn_sendmsg()
from the man page.
1. Return value.
"Otherwise, negative number is returned and errno is set..."
The negative number is -1 in every case. It would be nice to says that
explicitly.
That's also true for other functions. It's always -1 rather than random
negative number.
2. Behaviour regarding the pre-allocated message buffer:
"Alternatively, to send a buffer allocated by nn_allocmsg(3) function
set iov_base to point to the pointer to the buffer and iov_len to
NN_MSG constant.
The buffer will be deallocated by nn_send function. Trying to
deallocate it afterwards
will result in undefined behaviour. Also, scatter array in nn_msghdr
structure
can contain only one element in this case."
The message buffer is *not* deallocated in case an error is returned early.
The values of errno where it's not deallocated are: EINVAL, EMSGSIZE,
EFAULT.
Yes, true.
These error values are not even documented in the man page.
Would you like to patch it? The documentation source is in /doc subdirectory in asciidoc
(text-based) format.
How about the attached?
Best regards,
Zoltán Böszörményi
Martin
diff --git a/doc/nn_bind.txt b/doc/nn_bind.txt
index c2785b8..210e9e3 100644
--- a/doc/nn_bind.txt
+++ b/doc/nn_bind.txt
@@ -38,7 +38,7 @@ If the function succeeds positive endpoint ID is returned.
Endpoint ID can be
later used to remove the endpoint from the socket via
linknanomsg:nn_shutdown[3]
function.
-If the function fails negative value is returned and 'errno' is set to to one
of
+If the function fails, then -1 is returned and 'errno' is set to to one of
the values defined below.
diff --git a/doc/nn_close.txt b/doc/nn_close.txt
index 193fadb..9370186 100644
--- a/doc/nn_close.txt
+++ b/doc/nn_close.txt
@@ -23,7 +23,7 @@ option. The call will block in the meantime.
RETURN VALUE
------------
-If the function succeeds zero is returned. Otherwise, negative number is
+If the function succeeds zero is returned. Otherwise, -1 is
returned and 'errno' is set to to one of the values defined below.
diff --git a/doc/nn_device.txt b/doc/nn_device.txt
index 7fc1922..890dd01 100644
--- a/doc/nn_device.txt
+++ b/doc/nn_device.txt
@@ -26,8 +26,8 @@ linknanomsg:nn_term[3] function.
RETURN VALUE
------------
-The function loops until it hits an error. In such case it returns a negative
-value and sets 'errno' to one of the values defined below.
+The function loops until it hits an error. In such case it returns -1
+and sets 'errno' to one of the values defined below.
ERRORS
------
diff --git a/doc/nn_freemsg.txt b/doc/nn_freemsg.txt
index 4d9058f..7ece29b 100644
--- a/doc/nn_freemsg.txt
+++ b/doc/nn_freemsg.txt
@@ -24,7 +24,7 @@ efficient for large messages as it allows for using zero-copy
techniques.
RETURN VALUE
------------
-If the function succeeds zero is returned. Otherwise, negative number is
+If the function succeeds zero is returned. Otherwise, -1 is
returned and 'errno' is set to to one of the values defined below.
diff --git a/doc/nn_getsockopt.txt b/doc/nn_getsockopt.txt
index c876157..6134fc3 100644
--- a/doc/nn_getsockopt.txt
+++ b/doc/nn_getsockopt.txt
@@ -101,7 +101,7 @@ _<nanomsg/nn.h>_ header defines generic socket-level options
RETURN VALUE
------------
-If the function succeeds zero is returned. Otherwise, negative number is
+If the function succeeds zero is returned. Otherwise, -1 is
returned and 'errno' is set to to one of the values defined below.
diff --git a/doc/nn_recv.txt b/doc/nn_recv.txt
index b60b694..4657e2d 100644
--- a/doc/nn_recv.txt
+++ b/doc/nn_recv.txt
@@ -36,7 +36,7 @@ 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
+-1 is returned and 'errno' is set to to one of the values defined
below.
diff --git a/doc/nn_recvmsg.txt b/doc/nn_recvmsg.txt
index c222b32..ea7a900 100644
--- a/doc/nn_recvmsg.txt
+++ b/doc/nn_recvmsg.txt
@@ -58,7 +58,7 @@ 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
+-1 is returned and 'errno' is set to to one of the values defined
below.
diff --git a/doc/nn_send.txt b/doc/nn_send.txt
index 37e5125..d5b3f06 100644
--- a/doc/nn_send.txt
+++ b/doc/nn_send.txt
@@ -37,12 +37,15 @@ to EAGAIN.
RETURN VALUE
------------
If the function succeeds, the number of bytes in the message is returned.
-Otherwise, a negative number is returned and 'errno' is set to to one of the
+Otherwise, -1 is returned and 'errno' is set to to one of the
values defined below.
ERRORS
------
+*EFAULT*::
+'buf' is NULL or 'len' is NN_MSG and the message pointer (pointed to by
+'buf') is NULL.
*EBADF*::
The provided socket is invalid.
*ENOTSUP*::
@@ -65,11 +68,22 @@ The library is terminating.
EXAMPLE
-------
+Using data directly:
+
----
nbytes = nn_send (s, "ABC", 3, 0);
assert (nbytes == 3);
----
+Using a pre-allocated message buffer:
+
+----
+void *msg = nn_allocmsg(3, 0);
+strncpy(msg, "ABC", 3);
+nbytes = nn_send (s, &msg, NN_MSG, 0);
+assert (nbytes == 3);
+----
+
SEE ALSO
--------
diff --git a/doc/nn_sendmsg.txt b/doc/nn_sendmsg.txt
index ac3dd08..0fff7bc 100644
--- a/doc/nn_sendmsg.txt
+++ b/doc/nn_sendmsg.txt
@@ -62,12 +62,22 @@ 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.
+-1 is returned and 'errno' is set to to one of the values defined below.
ERRORS
------
+*EINVAL*::
+Either 'msghdr' is NULL, there are multiple scatter buffers but length is
+set to 'NN_MSG' for one of them, or the sum of 'iov_len' values for the
+scatter buffers overflows 'size_t'. These are early checks and no
+pre-allocated message is freed in this case.
+*EMSGSIZE*::
+msghdr->msg_iovlen is negative. This is an early check and no pre-allocated
+message is freed in this case.
+*EFAULT*::
+The supplied pointer for the pre-allocated message buffer or the scatter
+buffer is NULL, or the length for the scatter buffer is 0.
*EBADF*::
The provided socket is invalid.
*ENOTSUP*::
@@ -91,9 +101,12 @@ The library is terminating.
EXAMPLE
-------
+Usage of multiple scatter buffers:
+
----
struct nn_msghdr hdr;
struct nn_iovec iov [2];
+
iov [0].iov_base = "Hello";
iov [0].iov_len = 5;
iov [1].iov_base = "World";
@@ -104,6 +117,23 @@ hdr.msg_iovlen = 2;
nn_sendmsg (s, &hdr, 0);
----
+Usage of a single message:
+
+----
+void *msg;
+struct nn_msghdr hdr;
+struct nn_iovec iov;
+
+msg = nn_allocmsg(12, 0);
+strcpy(msg, "Hello World");
+iov.iov_base = &msg;
+iov.iov_len = NN_MSG;
+memset (&hdr, 0, sizeof (hdr));
+hdr.msg_iov = &iov;
+hdr.msg_iovlen = 1;
+nn_sendmsg (s, &hdr, 0);
+----
+
SEE ALSO
--------
diff --git a/doc/nn_setsockopt.txt b/doc/nn_setsockopt.txt
index fbd9b94..c56f981 100644
--- a/doc/nn_setsockopt.txt
+++ b/doc/nn_setsockopt.txt
@@ -79,7 +79,7 @@ _<nanomsg/nn.h>_ header defines generic socket-level options
RETURN VALUE
------------
-If the function succeeds zero is returned. Otherwise, negative number is
+If the function succeeds zero is returned. Otherwise, -1 is
returned and 'errno' is set to to one of the values defined below.
diff --git a/doc/nn_shutdown.txt b/doc/nn_shutdown.txt
index 95dade4..724cfee 100644
--- a/doc/nn_shutdown.txt
+++ b/doc/nn_shutdown.txt
@@ -24,7 +24,7 @@ the endpoint for the time specified by _NN_LINGER_ socket
option.
RETURN VALUE
------------
-If the function succeeds zero is returned. Otherwise, negative number is
+If the function succeeds zero is returned. Otherwise, -1 is
returned and 'errno' is set to to one of the values defined below.
diff --git a/doc/nn_socket.txt b/doc/nn_socket.txt
index 2de13e1..0169bd0 100644
--- a/doc/nn_socket.txt
+++ b/doc/nn_socket.txt
@@ -44,7 +44,7 @@ _SOCK_SEQPACKET_ type.
RETURN VALUE
------------
If the function succeeds file descriptor of the new socket is returned.
-Otherwise, negative number is returned and 'errno' is set to to one of
+Otherwise, -1 is returned and 'errno' is set to to one of
the values defined below.
Note that file descriptors returned by _nn_socket_ function are not standard
Other related posts:
