From 9de9ae0839fd5c5f286a837f02fff4825cce12a2 Mon Sep 17 00:00:00 2001 From: Michael Graff Date: Tue, 1 Dec 1998 17:58:34 +0000 Subject: [PATCH] cleanup header file to list actual return codes, new entry conditions, etc --- lib/isc/include/isc/socket.h | 106 +++++++++++++++++++---------------- lib/isc/unix/socket.c | 7 ++- 2 files changed, 63 insertions(+), 50 deletions(-) diff --git a/lib/isc/include/isc/socket.h b/lib/isc/include/isc/socket.h index 2f612a6fde..143e7c9dd5 100644 --- a/lib/isc/include/isc/socket.h +++ b/lib/isc/include/isc/socket.h @@ -1,4 +1,4 @@ -/* $Id: socket.h,v 1.7 1998/11/26 00:10:33 explorer Exp $ */ +/* $Id: socket.h,v 1.8 1998/12/01 17:58:34 explorer Exp $ */ #ifndef ISC_SOCKET_H #define ISC_SOCKET_H 1 @@ -147,9 +147,10 @@ isc_socket_create(isc_socketmgr_t manager, * * Returns: * - * Success - * No memory - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_NOMEMORY + * ISC_R_NORESOURCES + * ISC_R_UNEXPECTED */ @@ -253,43 +254,44 @@ isc_socket_bind(isc_socket_t socket, struct isc_sockaddr *addressp, * * Returns: * - * Success - * Address not available - * Address in use - * Permission denied - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_NOPERM + * ISC_R_ADDRNOTAVAIL + * ISC_R_ADDRINUSE + * ISC_R_BOUND + * ISC_R_UNEXPECTED */ isc_result_t isc_socket_listen(isc_socket_t socket, int backlog); /* - * Listen on 'socket'. Every time a new connection request arrives, - * a NEWCONN event with action 'action' and arg 'arg' will be posted - * to the event queue for 'task'. + * Set listen mode on the socket. After this call, the only function that + * can be used (other than attach and detach) is isc_socket_accept(). * * Notes: * - * 'backlog' is as in the UNIX system call listen(). + * 'backlog' is as in the UNIX system call listen() and may be + * ignored by non-UNIX implementations. * * Requires: * * 'socket' is a valid TCP socket. - * - * 'task' is a valid task - * - * 'action' is a valid action + * 'backlog' be >= 0. * * Returns: * - * Success - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_UNEXPECTED */ isc_result_t isc_socket_accept(isc_socket_t socket, isc_task_t task, isc_taskaction_t action, void *arg); /* - * Queue accept event. + * Queue accept event. When a new connection is received, the task will + * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen + * socket. The new socket structure is sent inside the isc_socket_newconnev_t + * event type, and is attached to the task 'task'. * * REQUIRES: * 'socket' is a valid TCP socket that isc_socket_listen() has been @@ -328,14 +330,17 @@ isc_socket_connect(isc_socket_t socket, struct isc_sockaddr *addressp, * * Returns: * - * Success - * No memory - * Address not available - * Address in use - * Host unreachable - * Network unreachable - * Connection refused - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_NOMEMORY + * ISC_R_UNEXPECTED + * + * Posted event's result code: + * + * ISC_R_SUCCESS + * ISC_R_TIMEDOUT + * ISC_R_CONNREFUSED + * ISC_R_NETUNREACH + * ISC_R_UNEXPECTED */ isc_result_t @@ -409,9 +414,15 @@ isc_socket_recv(isc_socket_t socket, isc_region_t region, * * Returns: * - * Success - * No memory - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_NOMEMORY + * ISC_R_UNEXPECTED + * + * Event results: + * + * ISC_R_SUCCESS + * ISC_R_UNEXPECTED + * XXX needs other net-type errors */ isc_result_t @@ -447,18 +458,17 @@ isc_socket_sendto(isc_socket_t socket, isc_region_t region, * * Returns: * - * Success - * No memory - * Unexpected error - */ - -/* XXX this is some of how to do a read - * generate new net_request - * generate new read-result net_event - * attach to requestor - * lock socket - * queue request - * unlock socket + * Returns: + * + * ISC_R_SUCCESS + * ISC_R_NOMEMORY + * ISC_R_UNEXPECTED + * + * Event results: + * + * ISC_R_SUCCESS + * ISC_R_UNEXPECTED + * XXX needs other net-type errors */ isc_result_t @@ -482,13 +492,13 @@ isc_socketmgr_create(isc_memctx_t mctx, isc_socketmgr_t *managerp); * * Returns: * - * Success - * No memory - * Unexpected error + * ISC_R_SUCCESS + * ISC_R_NOMEMORY + * ISC_R_UNEXPECTED */ void -isc_socketmgr_destroy(isc_socketmgr_t *); +isc_socketmgr_destroy(isc_socketmgr_t *managerp); /* * Destroy a socket manager. * @@ -503,6 +513,8 @@ isc_socketmgr_destroy(isc_socketmgr_t *); * * '*managerp' is a valid isc_socketmgr_t. * + * All sockets managed by this manager are fully detached. + * * Ensures: * * *managerp == NULL diff --git a/lib/isc/unix/socket.c b/lib/isc/unix/socket.c index 84fe7acc0b..e4f402ecd5 100644 --- a/lib/isc/unix/socket.c +++ b/lib/isc/unix/socket.c @@ -1,4 +1,4 @@ -/* $Id: socket.c,v 1.11 1998/11/26 00:29:12 explorer Exp $ */ +/* $Id: socket.c,v 1.12 1998/12/01 17:58:34 explorer Exp $ */ #include "attribute.h" @@ -286,7 +286,7 @@ allocate_socket(isc_socketmgr_t manager, isc_sockettype_t type, sock = isc_mem_get(manager->mctx, sizeof *sock); if (sock == NULL) - return (NULL); + return (ISC_R_NOMEMORY); sock->magic = SOCKET_MAGIC; sock->references = 0; @@ -373,7 +373,6 @@ isc_socket_create(isc_socketmgr_t manager, isc_sockettype_t type, REQUIRE(socketp != NULL && *socketp == NULL); XENTER(TRACE_MANAGER, "isc_socket_create"); - ret = allocate_socket(manager, type, &sock); if (ret != ISC_R_SUCCESS) @@ -1704,6 +1703,7 @@ isc_socket_accept(isc_socket_t sock, isc_result_t ret; XENTER(TRACE_LISTEN, "isc_socket_accept"); + REQUIRE(VALID_SOCKET(sock)); manager = sock->manager; REQUIRE(VALID_MANAGER(manager)); @@ -1789,6 +1789,7 @@ isc_socket_connect(isc_socket_t sock, struct isc_sockaddr *addr, int addrlen, REQUIRE(VALID_SOCKET(sock)); manager = sock->manager; REQUIRE(VALID_MANAGER(manager)); + REQUIRE(addr != NULL); LOCK(&sock->lock);