Improve service docs, fd validation, and defensive guards

- local_datagram_service.hpp: platform-neutral docs with
  ownership semantics for assign_socket and bind_socket
- local_stream_service.hpp: document ownership transfer
  semantics for assign_socket (impl takes ownership on
  success, caller retains on failure)
- local_datagram.hpp: convert block comment to Doxygen with
  @see tag
- win_local_stream_acceptor_service.hpp: null-guard
  release_socket() against reset internal_
- epoll_local_datagram_service.hpp: validate fd >= 0 in
  assign_socket
- kqueue_local_stream_service.hpp: validate fd >= 0 in
  assign_socket
- kqueue_local_datagram_service.hpp: validate fd >= 0 in
  assign_socket
- local_stream_acceptor.cpp: add explicit #include <cstring>
  for std::memcpy

Author: mvandeberg

include/boost/corosio/detail/local_datagram_service.hpp

@@ -18,13 +18,15 @@
 
 namespace boost::corosio::detail {
 
-/* Abstract local datagram service base class.
+/** Abstract local datagram service base class.
 
-   Concrete implementations (epoll, select, kqueue) inherit from
-   this class and provide platform-specific datagram socket operations
-   for Unix domain sockets. The context constructor installs
-   whichever backend via make_service, and local_datagram_socket.cpp
-   retrieves it via use_service<local_datagram_service>().
+    Concrete implementations (epoll, select, kqueue, IOCP)
+    inherit from this class and provide platform-specific
+    datagram socket operations for local (Unix domain) sockets.
+
+    Instances are looked up via key_type in the
+    execution_context. All errors are reported via the returned
+    std::error_code; these methods do not throw.
 */
 class BOOST_COROSIO_DECL local_datagram_service
     : public capy::execution_context::service
@@ -34,14 +36,16 @@ class BOOST_COROSIO_DECL local_datagram_service
     /// Identifies this service for execution_context lookup.
     using key_type = local_datagram_service;
 
-    /** Open a Unix datagram socket.
+    /** Open a local (Unix domain) datagram socket.
 
-        Creates a socket and associates it with the platform reactor.
+        Creates a socket and associates it with the platform
+        I/O backend (reactor or IOCP).
 
         @param impl The socket implementation to open.
-        @param family Address family (AF_UNIX).
-        @param type Socket type (SOCK_DGRAM).
-        @param protocol Protocol number (0).
+            Must not already represent an open socket.
+        @param family Address family for local IPC.
+        @param type Socket type for datagram sockets.
+        @param protocol Protocol number (typically 0).
         @return Error code on failure, empty on success.
     */
     virtual std::error_code open_socket(
@@ -50,12 +54,16 @@ class BOOST_COROSIO_DECL local_datagram_service
         int type,
         int protocol) = 0;
 
-    /** Assign an existing file descriptor to a socket.
+    /** Assign an existing native socket handle to a socket.
 
-        Used by socketpair() to adopt pre-created fds.
+        Adopts a pre-created socket handle. On success the
+        impl takes ownership and will close the handle. On
+        failure the caller retains ownership and must close
+        it. On platforms that do not support handle adoption,
+        returns @c operation_not_supported.
 
         @param impl The socket implementation to assign to.
-        @param fd The file descriptor to adopt.
+        @param fd The native socket handle to adopt.
         @return Error code on failure, empty on success.
     */
     virtual std::error_code assign_socket(
@@ -64,8 +72,10 @@ class BOOST_COROSIO_DECL local_datagram_service
 
     /** Bind a datagram socket to a local endpoint.
 
+        @pre @p impl was opened via open_socket().
         @param impl The socket implementation to bind.
         @param ep The local endpoint to bind to.
+            Copied; need not remain valid after the call.
         @return Error code on failure, empty on success.
     */
     virtual std::error_code bind_socket(

include/boost/corosio/detail/local_stream_service.hpp

@@ -53,9 +53,11 @@ class BOOST_COROSIO_DECL local_stream_service
     /** Assign an existing native socket handle to a socket.
 
         Adopts a pre-created socket handle (e.g. from a
-        platform-specific pair creation API). On platforms
-        that do not support handle adoption, returns
-        @c operation_not_supported.
+        platform-specific pair creation API). On success the
+        impl takes ownership and will close the handle. On
+        failure the caller retains ownership and must close
+        it. On platforms that do not support handle adoption,
+        returns @c operation_not_supported.
 
         @param impl The socket implementation to assign to.
         @param fd The native socket handle to adopt.

include/boost/corosio/local_datagram.hpp

@@ -16,17 +16,16 @@ namespace boost::corosio {
 
 class local_datagram_socket;
 
-/* Encapsulate the Unix datagram protocol for socket creation.
+/** Protocol tag for local (Unix domain) datagram sockets.
 
-   This class identifies the Unix datagram protocol (AF_UNIX,
-   SOCK_DGRAM). It is used to parameterize socket open() calls
-   with a self-documenting type.
+    Identifies the local datagram protocol for parameterizing
+    socket open() calls with a self-documenting type.
 
-   The family(), type(), and protocol() members are implemented
-   in the compiled library to avoid exposing platform socket
-   headers.
+    The family(), type(), and protocol() members are implemented
+    in the compiled library to avoid exposing platform socket
+    headers.
 
-   See local_datagram_socket
+    @see local_datagram_socket
 */
 class BOOST_COROSIO_DECL local_datagram
 {

include/boost/corosio/native/detail/epoll/epoll_local_datagram_service.hpp

@@ -267,6 +267,9 @@ epoll_local_datagram_service::assign_socket(
     local_datagram_socket::implementation& impl,
     int fd)
 {
+    if (fd < 0)
+        return make_err(EBADF);
+
     auto* epoll_impl = static_cast<epoll_local_datagram_socket*>(&impl);
     epoll_impl->close_socket();
 

include/boost/corosio/native/detail/iocp/win_local_stream_acceptor_service.hpp

@@ -404,6 +404,8 @@ win_local_stream_acceptor::cancel() noexcept
 inline native_handle_type
 win_local_stream_acceptor::release_socket() noexcept
 {
+    if (!internal_)
+        return static_cast<native_handle_type>(INVALID_SOCKET);
     SOCKET s = internal_->socket_;
     if (s != INVALID_SOCKET)
     {

include/boost/corosio/native/detail/kqueue/kqueue_local_datagram_service.hpp

@@ -301,6 +301,9 @@ kqueue_local_datagram_service::assign_socket(
     local_datagram_socket::implementation& impl,
     int fd)
 {
+    if (fd < 0)
+        return make_err(EBADF);
+
     auto* kq_impl = static_cast<kqueue_local_datagram_socket*>(&impl);
     kq_impl->close_socket();
 

include/boost/corosio/native/detail/kqueue/kqueue_local_stream_service.hpp

@@ -229,6 +229,9 @@ kqueue_local_stream_service::assign_socket(
     local_stream_socket::implementation& impl,
     int fd)
 {
+    if (fd < 0)
+        return make_err(EBADF);
+
     auto* kq_impl = static_cast<kqueue_local_stream_socket*>(&impl);
     kq_impl->close_socket();
 

src/corosio/src/local_stream_acceptor.cpp

@@ -12,6 +12,8 @@
 #include <boost/corosio/detail/platform.hpp>
 #include <boost/corosio/detail/local_stream_acceptor_service.hpp>
 
+#include <cstring>
+
 #if BOOST_COROSIO_POSIX
 #include <unistd.h>
 #endif