From ba970e5d32cceb0750eaa71fb83da3e2eef881d5 Mon Sep 17 00:00:00 2001
From: Stefan Metzmacher <metze@samba.org>
Date: Wed, 17 Feb 2021 12:29:27 +0100
Subject: swrap: export a public socket_wrapper_indicate_no_inet_fd() helper
 function

BUG: https://bugzilla.samba.org/show_bug.cgi?id=14640

Signed-off-by: Stefan Metzmacher <metze@samba.org>
Reviewed-by: Andreas Schneider <asn@samba.org>
---
 doc/socket_wrapper.1.adoc | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(limited to 'doc/socket_wrapper.1.adoc')

diff --git a/doc/socket_wrapper.1.adoc b/doc/socket_wrapper.1.adoc
index fd0b745..39c46ee 100644
--- a/doc/socket_wrapper.1.adoc
+++ b/doc/socket_wrapper.1.adoc
@@ -156,6 +156,31 @@ bool socket_wrapper_enabled(void);
 - This returns true when socket wrapper is actively in use.
 
 
+void socket_wrapper_indicate_no_inet_fd(int fd);
+
+- This allows socket_wrapper aware applications to
+  indicate that the given fd does not belong to
+  an inet socket.
+
+- socket_wrapper may not be able to intercept the __close_nocancel()
+  syscall made from within libc.so. As result it's possible
+  that the in memory meta date of socket_wrapper references
+  stale file descriptors, which are already reused for unrelated
+  kernel objects, e.g. files, directories, ...
+
+- Socket wrapper already intercepts a lot of unrelated
+  functions like eventfd(), timerfd_create(), ... in order
+  to remove stale meta data for the returned fd, but
+  it will never be able to handle all possible syscalls.
+
+- socket_wrapper_indicate_no_inet_fd() gives applications a way
+  to do the same, explicitly without waiting for new syscalls to
+  be added to libsocket_wrapper.so.
+
+- This is a no-op if socket_wrapper is not in use or
+  if the there is no in memory meta data for the given fd.
+
+
 RESOURCES
 ---------
 
-- 
cgit 

