lib/doc: clearify return value of send_simple() functions

The return value of the *nl_send_simple() functions is
inconsistent and not according to the documentation.

nl_send_simple() is document to return the number of bytes sent.
Other *nl_send_simple() functions are documented to return 0 on
success -- for the most part.
See also commit b70174668b9867de573cf51471bc98bfe7fd2bc3 which
changed behavior of nl_rtgen_request() to be according to documenation.

Don't change behavior again, only adjust the documentation.

http://lists.infradead.org/pipermail/libnl/2015-May/001872.html

Reported-by: Xiao Jia <stfairy@gmail.com>
Signed-off-by: Thomas Haller <thaller@redhat.com>

7 files changed, 26 insertions, 7 deletions

diff --git a/lib/cache.c b/lib/cache.c
index d68ee1f..9aba0c9 100644
--- a/lib/cache.c
+++ b/lib/cache.c
@@ -637,7 +637,9 @@ void nl_cache_set_flags(struct nl_cache *cache, unsigned int flags)
  *
  * @see nl_cache_pickup(), nl_cache_resync()
  *
- * @return 0 on success or a negative error code.
+ * @return 0 on success or a negative error code. Some implementations
+ * of co_request_update() return a positive number on success that is
+ * the number of bytes sent. Treat any non-negative number as success too.
  */
 static int nl_cache_request_full_dump(struct nl_sock *sk,
 				      struct nl_cache *cache)
diff --git a/lib/genl/genl.c b/lib/genl/genl.c
index 0c9b11e..a663ad8 100644
--- a/lib/genl/genl.c
+++ b/lib/genl/genl.c
@@ -79,7 +79,8 @@ int genl_connect(struct nl_sock *sk)
  *
  * @see nl_send_simple()
  *
- * @return 0 on success or a negative error code.
+ * @return 0 on success or a negative error code. Due to a bug, this function
+ * returns the number of bytes sent. Treat any non-negative number as success.
  */
 int genl_send_simple(struct nl_sock *sk, int family, int cmd,
 		     int version, int flags)
diff --git a/lib/idiag/idiag.c b/lib/idiag/idiag.c
index 34dc0d6..26681c7 100644
--- a/lib/idiag/idiag.c
+++ b/lib/idiag/idiag.c
@@ -57,7 +57,8 @@ int idiagnl_connect(struct nl_sock *sk)
  * @arg states	Socket states to query
  * @arg ext	Inet Diag attribute extensions to query
  *
- * @return Newly allocated netlink message or NULL.
+ * @return 0 on success or a negative error code. Due to a bug, this function
+ * returns the number of bytes sent. Treat any non-negative number as success.
  */
 int idiagnl_send_simple(struct nl_sock *sk, int flags, uint8_t family,
 		uint16_t states, uint16_t ext)
diff --git a/lib/netfilter/ct.c b/lib/netfilter/ct.c
index 903c584..d589790 100644
--- a/lib/netfilter/ct.c
+++ b/lib/netfilter/ct.c
@@ -413,6 +413,13 @@ static int ct_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who,
 	return err;
 }
 
+/**
+ * Send nfnl ct dump request
+ * @arg sk    Netlink socket.
+ *
+ * @return 0 on success or a negative error code. Due to a bug, this function
+ * returns the number of bytes sent. Treat any non-negative number as success.
+ */
 int nfnl_ct_dump_request(struct nl_sock *sk)
 {
 	return nfnl_send_simple(sk, NFNL_SUBSYS_CTNETLINK, IPCTNL_MSG_CT_GET,
diff --git a/lib/netfilter/exp.c b/lib/netfilter/exp.c
index 9cfdd2b..650127c 100644
--- a/lib/netfilter/exp.c
+++ b/lib/netfilter/exp.c
@@ -305,6 +305,13 @@ static int exp_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who,
 	return err;
 }
 
+/**
+ * Send nfnl exp dump request
+ * @arg sk    Netlink socket.
+ *
+ * @return 0 on success or a negative error code. Due to a bug, this function
+ * returns the number of bytes sent. Treat any non-negative number as success.
+ */
 int nfnl_exp_dump_request(struct nl_sock *sk)
 {
 	return nfnl_send_simple(sk, NFNL_SUBSYS_CTNETLINK_EXP, IPCTNL_MSG_EXP_GET,
diff --git a/lib/netfilter/nfnl.c b/lib/netfilter/nfnl.c
index f028a85..9b52447 100644
--- a/lib/netfilter/nfnl.c
+++ b/lib/netfilter/nfnl.c
@@ -102,7 +102,8 @@ int nfnl_connect(struct nl_sock *sk)
  * @arg family		nfnetlink address family
  * @arg res_id		nfnetlink resource id
  *
- * @return Newly allocated netlink message or NULL.
+ * @return 0 on success or a negative error code. Due to a bug, this function
+ * returns the number of bytes sent. Treat any non-negative number as success.
  */
 int nfnl_send_simple(struct nl_sock *sk, uint8_t subsys_id, uint8_t type,
 		     int flags, uint8_t family, uint16_t res_id)
diff --git a/lib/route/rtnl.c b/lib/route/rtnl.c
index 242e2a8..e0a7f2a 100644
--- a/lib/route/rtnl.c
+++ b/lib/route/rtnl.c
@@ -34,9 +34,9 @@
  * Fills out a routing netlink request message and sends it out
  * using nl_send_simple().
  *
- * @return 0 on success or a negative error code. Due to a bug in
- * older versions, this returned the number of bytes sent. So for
- * compatibility, treat positive return values as success too.
+ * @return 0 on success or a negative error code. Due to a bug in older
+ * version of the library, this function returned the number of bytes sent.
+ * Treat any non-negative number as success.
  */
 int nl_rtgen_request(struct nl_sock *sk, int type, int family, int flags)
 {