From eb048645b6b0ec0debb7927ed00214d827b68613 Mon Sep 17 00:00:00 2001
From: Konstantin Shemyak <konstantin@shemyak.com>
Date: Thu, 26 Feb 2015 08:59:56 +0100
Subject: [PATCH] getsockopt.2: Note RETURN VALUE details when netfilter is
 involved

From email conversation with Konstantin:

> * Are you saying there are case where successful
>   setsockopt() via nf_register_sockopt() might return a
>   value other zero?

Yes - it happens when the option is served by a custom
netfilter hook (this is how I bumped into this). Example:

Userspace code:

===================  cut here ================================

int main(void) {
   int sock;

   if ((sock = socket(AF_INET, SOCK_RAW, IPPROTO_RAW)) < 0)
     return -1;

   return setsockopt(sock, IPPROTO_IP, TEST_SETSOCKOPT_RETURN, NULL, 0);
}
===================  cut here ================================

Kernel module, handling the option 400 "TEST_SETSOCKOPT_RETURN":

===================  cut here ================================

/* Random value - just should not be already used by the running
system: */

static int test_sock_set_so(struct sock *sk, int cmd, void *param,
unsigned len) {
         return 42;
}

static struct nf_sockopt_ops test_sock_ops = {
         list:       {NULL, NULL},
         pf:         PF_INET,
         set_optmin: TEST_SETSOCKOPT_RETURN,
         set_optmax: (TEST_SETSOCKOPT_RETURN + 1),
         set:        test_sock_set_so,
         get_optmin: 0,
         get_optmax: 0,
         get:        NULL
};

static int test_sock_init(void) {
         return nf_register_sockopt(&test_sock_ops);  /* sanity check
skipped */
}

static void test_sock_exit(void) {
         nf_unregister_sockopt(&test_sock_ops);
}

module_init(test_sock_init);
module_exit(test_sock_exit);
===================  cut here ================================

After successful loading of the module, the executable returns 42,
and as I understand, that is the intention of netfilter authors.
Netfilter code calls the registered handle and just returns back to
user what it receives from it.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/getsockopt.2 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man2/getsockopt.2 b/man2/getsockopt.2
index 1287efc96..d030cc4f6 100644
--- a/man2/getsockopt.2
+++ b/man2/getsockopt.2
@@ -129,7 +129,9 @@ For a description of the available socket options see
 .BR socket (7)
 and the appropriate protocol man pages.
 .SH RETURN VALUE
-On success, zero is returned.
+On success, zero is returned for the standard options. Netfilter allows
+to define custom socket options with associated handlers; for such
+options, the return value is the one returned from the handler.
 On error, \-1 is returned, and
 .I errno
 is set appropriately.