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>

2 files changed, 94 insertions, 0 deletions

diff --git a/doc/socket_wrapper.1 b/doc/socket_wrapper.1
index b6363cd..c988227 100644
--- a/doc/socket_wrapper.1
+++ b/doc/socket_wrapper.1
@@ -281,6 +281,75 @@ bool socket_wrapper_enabled(void);
 .\}
 This returns true when socket wrapper is actively in use.
 .RE
+.sp
+void socket_wrapper_indicate_no_inet_fd(int fd);
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+This allows socket_wrapper aware applications to
+indicate that the given fd does not belong to
+an inet socket.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+socket_wrapper may not be able to intercept the __close_nocancel()
+syscall made from within libc.so. As result it\(cqs 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, ...
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+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.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+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.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+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.
+.RE
 .SH "RESOURCES"
 .sp
 \fBProject web site:\fP \c
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
 ---------