2419. [cleanup] Document that isc_socket_create() and isc_socket_open()

should not be used for isc_sockettype_fdwatch sockets.
                        [RT #18521]

CHANGES

@@ -1,3 +1,7 @@
+2419.	[cleanup]	Document that isc_socket_create() and isc_socket_open()
+			should not be used for isc_sockettype_fdwatch sockets.
+			[RT #18521]
+
 2418.	[bug]		AXFR request on a DLZ could trigger a REQUIRE failure
 			[RT #18430]
 
@@ -37,6 +41,10 @@
 2406.	[bug]		Sockets could be closed too early, leading to
 			inconsistent states in the socket module. [RT #18298]
 
+xxxx.	[bug]		Connecting UDP sockets for outgoing queries could
+			unexpectedly fail with an 'address already in use'
+			error.
+
 2405.   [cleanup]       The default value for dnssec-validation was changed to
                         "yes" in 9.5.0-P1 and all subsequent releases; this
                         was inadvertently omitted from CHANGES at the time.

lib/isc/include/isc/socket.h

@@ -15,7 +15,7 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: socket.h,v 1.81 2008/07/23 23:47:07 tbox Exp $ */
+/* $Id: socket.h,v 1.82 2008/08/20 06:16:05 marka Exp $ */
 
 #ifndef ISC_SOCKET_H
 #define ISC_SOCKET_H 1
@@ -245,6 +245,9 @@ isc_socket_create(isc_socketmgr_t *manager,
 /*%<
  * Create a new 'type' socket managed by 'manager'.
  *
+ * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate()
+ * rather than isc_socket_create().
+ *
  * Note:
  *
  *\li	'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
@@ -255,6 +258,8 @@ isc_socket_create(isc_socketmgr_t *manager,
  *
  *\li	'socketp' is a valid pointer, and *socketp == NULL
  *
+ *\li	'type' is not isc_sockettype_fdwatch
+ *
  * Ensures:
  *
  *	'*socketp' is attached to the newly created socket
@@ -378,12 +383,17 @@ isc_socket_open(isc_socket_t *sock);
  * one.  This optimization may not be available for some systems, in which
  * case this function will return ISC_R_NOTIMPLEMENTED and must not be used.
  *
+ * isc_socket_open() should not be called on sockets created by
+ * isc_socket_fdwatchcreate().
+ *
  * Requires:
  *
  * \li	there must be no other reference to this socket.
  *
  * \li	'socket' is a valid and previously closed by isc_socket_close()
  *
+ * \li  'sock->type' is not isc_sockettype_fdwatch
+ *
  * Returns:
  *	Same as isc_socket_create().
  * \li	ISC_R_NOTIMPLEMENTED
@@ -399,6 +409,9 @@ isc_socket_close(isc_socket_t *sock);
  * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and
  * must not be used.
  *
+ * isc_socket_close() should not be called on sockets created by
+ * isc_socket_fdwatchcreate().
+ *
  * Requires:
  *
  * \li	The socket must have a valid descriptor.
@@ -407,6 +420,8 @@ isc_socket_close(isc_socket_t *sock);
  *
  * \li	There must be no pending I/O requests.
  *
+ * \li  'sock->type' is not isc_sockettype_fdwatch
+ *
  * Returns:
  * \li	#ISC_R_NOTIMPLEMENTED
  */

lib/isc/unix/socket.c

@@ -15,7 +15,7 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: socket.c,v 1.299 2008/08/13 23:44:18 jinmei Exp $ */
+/* $Id: socket.c,v 1.300 2008/08/20 06:16:05 marka Exp $ */
 
 /*! \file */
 
@@ -1847,7 +1847,10 @@ opensocket(isc_socketmgr_t *manager, isc_socket_t *sock) {
 		sock->fd = socket(sock->pf, SOCK_STREAM, 0);
 		break;
 	case isc_sockettype_fdwatch:
-		INSIST(sock->type != isc_sockettype_fdwatch);
+		/*
+		 * We should not be called for isc_sockettype_fdwatch sockets.
+		 */
+		INSIST(0);
 		break;
 	}
 	if (sock->fd == -1 && errno == EINTR && tries++ < 42)
@@ -2062,6 +2065,7 @@ isc_socket_create(isc_socketmgr_t *manager, int pf, isc_sockettype_t type,
 
 	REQUIRE(VALID_MANAGER(manager));
 	REQUIRE(socketp != NULL && *socketp == NULL);
+	REQUIRE(type != isc_sockettype_fdwatch);
 
 	result = allocate_socket(manager, type, &sock);
 	if (result != ISC_R_SUCCESS)
@@ -2117,6 +2121,7 @@ isc_socket_open(isc_socket_t *sock) {
 
 	LOCK(&sock->lock);
 	REQUIRE(sock->references == 1);
+	REQUIRE(sock->type != isc_sockettype_fdwatch);
 	UNLOCK(&sock->lock);
 	/*
 	 * We don't need to retain the lock hereafter, since no one else has
@@ -2261,6 +2266,7 @@ isc_socket_close(isc_socket_t *sock) {
 
 	LOCK(&sock->lock);
 	REQUIRE(sock->references == 1);
+	REQUIRE(sock->type != isc_sockettype_fdwatch);
 	UNLOCK(&sock->lock);
 	/*
 	 * We don't need to retain the lock hereafter, since no one else has

lib/isc/win32/socket.c

@@ -15,7 +15,7 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: socket.c,v 1.64 2008/08/08 06:28:59 tbox Exp $ */
+/* $Id: socket.c,v 1.65 2008/08/20 06:16:05 marka Exp $ */
 
 /* This code has been rewritten to take advantage of Windows Sockets
  * I/O Completion Ports and Events. I/O Completion Ports is ONLY
@@ -1949,6 +1949,7 @@ isc_socket_create(isc_socketmgr_t *manager, int pf, isc_sockettype_t type,
 
 	REQUIRE(VALID_MANAGER(manager));
 	REQUIRE(socketp != NULL && *socketp == NULL);
+	REQUIRE(type != isc_sockettype_fdwatch);
 
 	result = allocate_socket(manager, type, &sock);
 	if (result != ISC_R_SUCCESS)
@@ -2090,6 +2091,7 @@ isc_socket_create(isc_socketmgr_t *manager, int pf, isc_sockettype_t type,
 isc_result_t
 isc_socket_open(isc_socket_t *sock) {
 	REQUIRE(VALID_SOCKET(sock));
+	REQUIRE(sock->type != isc_sockettype_fdwatch);
 
 	return (ISC_R_NOTIMPLEMENTED);
 }
@@ -2135,6 +2137,7 @@ isc_socket_detach(isc_socket_t **socketp) {
 isc_result_t
 isc_socket_close(isc_socket_t *sock) {
 	REQUIRE(VALID_SOCKET(sock));
+	REQUIRE(sock->type != isc_sockettype_fdwatch);
 
 	return (ISC_R_NOTIMPLEMENTED);
 }