diff options
Diffstat (limited to 'lib/isc/include/isc/socket.h')
| -rw-r--r-- | lib/isc/include/isc/socket.h | 1272 |
1 files changed, 1272 insertions, 0 deletions
diff --git a/lib/isc/include/isc/socket.h b/lib/isc/include/isc/socket.h new file mode 100644 index 0000000..574de2a --- /dev/null +++ b/lib/isc/include/isc/socket.h @@ -0,0 +1,1272 @@ +/* + * Copyright (C) Internet Systems Consortium, Inc. ("ISC") + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * See the COPYRIGHT file distributed with this work for additional + * information regarding copyright ownership. + */ + +#ifndef ISC_SOCKET_H +#define ISC_SOCKET_H 1 + +/***** + ***** Module Info + *****/ + +/*! \file isc/socket.h + * \brief Provides TCP and UDP sockets for network I/O. The sockets are event + * sources in the task system. + * + * When I/O completes, a completion event for the socket is posted to the + * event queue of the task which requested the I/O. + * + * \li MP: + * The module ensures appropriate synchronization of data structures it + * creates and manipulates. + * Clients of this module must not be holding a socket's task's lock when + * making a call that affects that socket. Failure to follow this rule + * can result in deadlock. + * The caller must ensure that isc_socketmgr_destroy() is called only + * once for a given manager. + * + * \li Reliability: + * No anticipated impact. + * + * \li Resources: + * TBS + * + * \li Security: + * No anticipated impact. + * + * \li Standards: + * None. + */ + +/*** + *** Imports + ***/ + +#include <inttypes.h> +#include <stdbool.h> + +#include <isc/event.h> +#include <isc/eventclass.h> +#include <isc/lang.h> +#include <isc/json.h> +#include <isc/region.h> +#include <isc/sockaddr.h> +#include <isc/time.h> +#include <isc/types.h> +#include <isc/xml.h> + +#ifdef WIN32 + +/* from the old namespace.h */ + +#define isc_socket_create isc__socket_create +#define isc_socket_dup isc__socket_dup +#define isc_socket_attach isc__socket_attach +#define isc_socket_detach isc__socket_detach +#define isc_socketmgr_create isc__socketmgr_create +#define isc_socketmgr_create2 isc__socketmgr_create2 +#define isc_socketmgr_destroy isc__socketmgr_destroy +#define isc_socket_open isc__socket_open +#define isc_socket_close isc__socket_close +#define isc_socket_recvv isc__socket_recvv +#define isc_socket_recv isc__socket_recv +#define isc_socket_recv2 isc__socket_recv2 +#define isc_socket_send isc__socket_send +#define isc_socket_sendto isc__socket_sendto +#define isc_socket_sendv isc__socket_sendv +#define isc_socket_sendtov isc__socket_sendtov +#define isc_socket_sendtov2 isc__socket_sendtov2 +#define isc_socket_sendto2 isc__socket_sendto2 +#define isc_socket_cleanunix isc__socket_cleanunix +#define isc_socket_permunix isc__socket_permunix +#define isc_socket_bind isc__socket_bind +#define isc_socket_filter isc__socket_filter +#define isc_socket_listen isc__socket_listen +#define isc_socket_accept isc__socket_accept +#define isc_socket_connect isc__socket_connect +#define isc_socket_getfd isc__socket_getfd +#define isc_socket_getname isc__socket_getname +#define isc_socket_gettag isc__socket_gettag +#define isc_socket_getpeername isc__socket_getpeername +#define isc_socket_getsockname isc__socket_getsockname +#define isc_socket_cancel isc__socket_cancel +#define isc_socket_gettype isc__socket_gettype +#define isc_socket_isbound isc__socket_isbound +#define isc_socket_ipv6only isc__socket_ipv6only +#define isc_socket_setname isc__socket_setname +#define isc_socketmgr_getmaxsockets isc__socketmgr_getmaxsockets +#define isc_socketmgr_setstats isc__socketmgr_setstats +#define isc_socketmgr_setreserved isc__socketmgr_setreserved +#define isc__socketmgr_maxudp isc___socketmgr_maxudp +#define isc_socket_fdwatchcreate isc__socket_fdwatchcreate +#define isc_socket_fdwatchpoke isc__socket_fdwatchpoke +#define isc_socket_dscp isc__socket_dscp + +#endif + +ISC_LANG_BEGINDECLS + +/*** + *** Constants + ***/ + +/*% + * Maximum number of buffers in a scatter/gather read/write. The operating + * system in use must support at least this number (plus one on some.) + */ +#define ISC_SOCKET_MAXSCATTERGATHER 8 + +/*% + * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling + * bind() if a non zero port is specified (AF_INET and AF_INET6). + */ +#define ISC_SOCKET_REUSEADDRESS 0x01U + +/*% + * Statistics counters. Used as isc_statscounter_t values. + */ +enum { + isc_sockstatscounter_udp4open = 0, + isc_sockstatscounter_udp6open = 1, + isc_sockstatscounter_tcp4open = 2, + isc_sockstatscounter_tcp6open = 3, + isc_sockstatscounter_unixopen = 4, + + isc_sockstatscounter_udp4openfail = 5, + isc_sockstatscounter_udp6openfail = 6, + isc_sockstatscounter_tcp4openfail = 7, + isc_sockstatscounter_tcp6openfail = 8, + isc_sockstatscounter_unixopenfail = 9, + + isc_sockstatscounter_udp4close = 10, + isc_sockstatscounter_udp6close = 11, + isc_sockstatscounter_tcp4close = 12, + isc_sockstatscounter_tcp6close = 13, + isc_sockstatscounter_unixclose = 14, + isc_sockstatscounter_fdwatchclose = 15, + + isc_sockstatscounter_udp4bindfail = 16, + isc_sockstatscounter_udp6bindfail = 17, + isc_sockstatscounter_tcp4bindfail = 18, + isc_sockstatscounter_tcp6bindfail = 19, + isc_sockstatscounter_unixbindfail = 20, + isc_sockstatscounter_fdwatchbindfail = 21, + + isc_sockstatscounter_udp4connect = 22, + isc_sockstatscounter_udp6connect = 23, + isc_sockstatscounter_tcp4connect = 24, + isc_sockstatscounter_tcp6connect = 25, + isc_sockstatscounter_unixconnect = 26, + isc_sockstatscounter_fdwatchconnect = 27, + + isc_sockstatscounter_udp4connectfail = 28, + isc_sockstatscounter_udp6connectfail = 29, + isc_sockstatscounter_tcp4connectfail = 30, + isc_sockstatscounter_tcp6connectfail = 31, + isc_sockstatscounter_unixconnectfail = 32, + isc_sockstatscounter_fdwatchconnectfail = 33, + + isc_sockstatscounter_tcp4accept = 34, + isc_sockstatscounter_tcp6accept = 35, + isc_sockstatscounter_unixaccept = 36, + + isc_sockstatscounter_tcp4acceptfail = 37, + isc_sockstatscounter_tcp6acceptfail = 38, + isc_sockstatscounter_unixacceptfail = 39, + + isc_sockstatscounter_udp4sendfail = 40, + isc_sockstatscounter_udp6sendfail = 41, + isc_sockstatscounter_tcp4sendfail = 42, + isc_sockstatscounter_tcp6sendfail = 43, + isc_sockstatscounter_unixsendfail = 44, + isc_sockstatscounter_fdwatchsendfail = 45, + + isc_sockstatscounter_udp4recvfail = 46, + isc_sockstatscounter_udp6recvfail = 47, + isc_sockstatscounter_tcp4recvfail = 48, + isc_sockstatscounter_tcp6recvfail = 49, + isc_sockstatscounter_unixrecvfail = 50, + isc_sockstatscounter_fdwatchrecvfail = 51, + + isc_sockstatscounter_udp4active = 52, + isc_sockstatscounter_udp6active = 53, + isc_sockstatscounter_tcp4active = 54, + isc_sockstatscounter_tcp6active = 55, + isc_sockstatscounter_unixactive = 56, + + isc_sockstatscounter_rawopen = 57, + isc_sockstatscounter_rawopenfail = 58, + isc_sockstatscounter_rawclose = 59, + isc_sockstatscounter_rawrecvfail = 60, + isc_sockstatscounter_rawactive = 61, + + isc_sockstatscounter_max = 62 +}; + +/*** + *** Types + ***/ + +struct isc_socketevent { + ISC_EVENT_COMMON(isc_socketevent_t); + isc_result_t result; /*%< OK, EOF, whatever else */ + unsigned int minimum; /*%< minimum i/o for event */ + unsigned int n; /*%< bytes read or written */ + unsigned int offset; /*%< offset into buffer list */ + isc_region_t region; /*%< for single-buffer i/o */ + isc_bufferlist_t bufferlist; /*%< list of buffers */ + isc_sockaddr_t address; /*%< source address */ + isc_time_t timestamp; /*%< timestamp of packet recv */ + struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ + uint32_t attributes; /*%< see below */ + isc_eventdestructor_t destroy; /*%< original destructor */ + unsigned int dscp; /*%< UDP dscp value */ +}; + +typedef struct isc_socket_newconnev isc_socket_newconnev_t; +struct isc_socket_newconnev { + ISC_EVENT_COMMON(isc_socket_newconnev_t); + isc_socket_t * newsocket; + isc_result_t result; /*%< OK, EOF, whatever else */ + isc_sockaddr_t address; /*%< source address */ +}; + +typedef struct isc_socket_connev isc_socket_connev_t; +struct isc_socket_connev { + ISC_EVENT_COMMON(isc_socket_connev_t); + isc_result_t result; /*%< OK, EOF, whatever else */ +}; + +/*@{*/ +/*! + * _ATTACHED: Internal use only. + * _TRUNC: Packet was truncated on receive. + * _CTRUNC: Packet control information was truncated. This can + * indicate that the packet is not complete, even though + * all the data is valid. + * _TIMESTAMP: The timestamp member is valid. + * _PKTINFO: The pktinfo member is valid. + * _MULTICAST: The UDP packet was received via a multicast transmission. + * _DSCP: The UDP DSCP value is valid. + * _USEMINMTU: Set the per packet IPV6_USE_MIN_MTU flag. + */ +#define ISC_SOCKEVENTATTR_ATTACHED 0x10000000U /* internal */ +#define ISC_SOCKEVENTATTR_TRUNC 0x00800000U /* public */ +#define ISC_SOCKEVENTATTR_CTRUNC 0x00400000U /* public */ +#define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */ +#define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */ +#define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */ +#define ISC_SOCKEVENTATTR_DSCP 0x00040000U /* public */ +#define ISC_SOCKEVENTATTR_USEMINMTU 0x00020000U /* public */ +/*@}*/ + +#define ISC_SOCKEVENT_ANYEVENT (0) +#define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) +#define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2) +#define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3) +#define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4) + +/* + * Internal events. + */ +#define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256) +#define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257) + +typedef enum { + isc_sockettype_udp = 1, + isc_sockettype_tcp = 2, + isc_sockettype_unix = 3, + isc_sockettype_fdwatch = 4, + isc_sockettype_raw = 5 +} isc_sockettype_t; + +/*@{*/ +/*! + * How a socket should be shutdown in isc_socket_shutdown() calls. + */ +#define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ +#define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ +#define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ +/*@}*/ + +/*@{*/ +/*! + * What I/O events to cancel in isc_socket_cancel() calls. + */ +#define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ +#define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ +#define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ +#define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ +#define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ +/*@}*/ + +/*@{*/ +/*! + * Flags for isc_socket_send() and isc_socket_recv() calls. + */ +#define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ +#define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ +/*@}*/ + +/*@{*/ +/*! + * Flags for fdwatchcreate. + */ +#define ISC_SOCKFDWATCH_READ 0x00000001 /*%< watch for readable */ +#define ISC_SOCKFDWATCH_WRITE 0x00000002 /*%< watch for writable */ +/*@}*/ + +/*% Socket and socket manager methods */ +typedef struct isc_socketmgrmethods { + void (*destroy)(isc_socketmgr_t **managerp); + isc_result_t (*socketcreate)(isc_socketmgr_t *manager, int pf, + isc_sockettype_t type, + isc_socket_t **socketp); + isc_result_t (*fdwatchcreate)(isc_socketmgr_t *manager, int fd, + int flags, + isc_sockfdwatch_t callback, + void *cbarg, isc_task_t *task, + isc_socket_t **socketp); +} isc_socketmgrmethods_t; + +typedef struct isc_socketmethods { + void (*attach)(isc_socket_t *socket, + isc_socket_t **socketp); + void (*detach)(isc_socket_t **socketp); + isc_result_t (*bind)(isc_socket_t *sock, isc_sockaddr_t *sockaddr, + unsigned int options); + isc_result_t (*sendto)(isc_socket_t *sock, isc_region_t *region, + isc_task_t *task, isc_taskaction_t action, + void *arg, isc_sockaddr_t *address, + struct in6_pktinfo *pktinfo); + isc_result_t (*sendto2)(isc_socket_t *sock, isc_region_t *region, + isc_task_t *task, isc_sockaddr_t *address, + struct in6_pktinfo *pktinfo, + isc_socketevent_t *event, + unsigned int flags); + isc_result_t (*connect)(isc_socket_t *sock, isc_sockaddr_t *addr, + isc_task_t *task, isc_taskaction_t action, + void *arg); + isc_result_t (*recv)(isc_socket_t *sock, isc_region_t *region, + unsigned int minimum, isc_task_t *task, + isc_taskaction_t action, void *arg); + isc_result_t (*recv2)(isc_socket_t *sock, isc_region_t *region, + unsigned int minimum, isc_task_t *task, + isc_socketevent_t *event, unsigned int flags); + void (*cancel)(isc_socket_t *sock, isc_task_t *task, + unsigned int how); + isc_result_t (*getsockname)(isc_socket_t *sock, + isc_sockaddr_t *addressp); + isc_sockettype_t (*gettype)(isc_socket_t *sock); + void (*ipv6only)(isc_socket_t *sock, bool yes); + isc_result_t (*fdwatchpoke)(isc_socket_t *sock, int flags); + isc_result_t (*dup)(isc_socket_t *socket, + isc_socket_t **socketp); + int (*getfd)(isc_socket_t *socket); + void (*dscp)(isc_socket_t *socket, isc_dscp_t dscp); +} isc_socketmethods_t; + +/*% + * This structure is actually just the common prefix of a socket manager + * object implementation's version of an isc_socketmgr_t. + * \brief + * Direct use of this structure by clients is forbidden. socket implementations + * may change the structure. 'magic' must be ISCAPI_SOCKETMGR_MAGIC for any + * of the isc_socket_ routines to work. socket implementations must maintain + * all socket invariants. + * In effect, this definition is used only for non-BIND9 version ("export") + * of the library, and the export version does not work for win32. So, to avoid + * the definition conflict with win32/socket.c, we enable this definition only + * for non-Win32 (i.e. Unix) platforms. + */ +#ifndef WIN32 +struct isc_socketmgr { + unsigned int impmagic; + unsigned int magic; + isc_socketmgrmethods_t *methods; +}; +#endif + +#define ISCAPI_SOCKETMGR_MAGIC ISC_MAGIC('A','s','m','g') +#define ISCAPI_SOCKETMGR_VALID(m) ((m) != NULL && \ + (m)->magic == ISCAPI_SOCKETMGR_MAGIC) + +/*% + * This is the common prefix of a socket object. The same note as + * that for the socketmgr structure applies. + */ +#ifndef WIN32 +struct isc_socket { + unsigned int impmagic; + unsigned int magic; + isc_socketmethods_t *methods; +}; +#endif + +#define ISCAPI_SOCKET_MAGIC ISC_MAGIC('A','s','c','t') +#define ISCAPI_SOCKET_VALID(s) ((s) != NULL && \ + (s)->magic == ISCAPI_SOCKET_MAGIC) + +/*** + *** Socket and Socket Manager Functions + *** + *** Note: all Ensures conditions apply only if the result is success for + *** those functions which return an isc_result. + ***/ + +isc_result_t +isc_socket_fdwatchcreate(isc_socketmgr_t *manager, + int fd, + int flags, + isc_sockfdwatch_t callback, + void *cbarg, + isc_task_t *task, + isc_socket_t **socketp); +/*%< + * Create a new file descriptor watch socket managed by 'manager'. + * + * Note: + * + *\li 'fd' is the already-opened file descriptor (must be less + * than maxsockets). + *\li This function is not available on Windows. + *\li The callback function is called "in-line" - this means the function + * needs to return as fast as possible, as all other I/O will be suspended + * until the callback completes. + * + * Requires: + * + *\li 'manager' is a valid manager + * + *\li 'socketp' is a valid pointer, and *socketp == NULL + * + *\li 'fd' be opened. + * + * Ensures: + * + * '*socketp' is attached to the newly created fdwatch socket + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NORESOURCES + *\li #ISC_R_UNEXPECTED + *\li #ISC_R_RANGE + */ + +isc_result_t +isc_socket_fdwatchpoke(isc_socket_t *sock, + int flags); +/*%< + * Poke a file descriptor watch socket informing the manager that it + * should restart watching the socket + * + * Note: + * + *\li 'sock' is the socket returned by isc_socket_fdwatchcreate + * + *\li 'flags' indicates what the manager should watch for on the socket + * in addition to what it may already be watching. It can be one or + * both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE. To + * temporarily disable watching on a socket the value indicating + * no more data should be returned from the call back routine. + * + *\li This function is not available on Windows. + * + * Requires: + * + *\li 'sock' is a valid isc socket + * + * + * Returns: + * + *\li #ISC_R_SUCCESS + */ + +isc_result_t +isc_socket_create(isc_socketmgr_t *manager, + int pf, + isc_sockettype_t type, + isc_socket_t **socketp); +/*%< + * 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. + * + * Requires: + * + *\li 'manager' is a valid 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 + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NORESOURCES + *\li #ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp); +/*%< + * Duplicate an existing socket, reusing its file descriptor. + */ + +void +isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, + unsigned int how); +/*%< + * Cancel pending I/O of the type specified by "how". + * + * Note: if "task" is NULL, then the cancel applies to all tasks using the + * socket. + * + * Requires: + * + * \li "socket" is a valid socket + * + * \li "task" is NULL or a valid task + * + * "how" is a bitmask describing the type of cancelation to perform. + * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this + * socket. + * + * \li ISC_SOCKCANCEL_RECV: + * Cancel pending isc_socket_recv() calls. + * + * \li ISC_SOCKCANCEL_SEND: + * Cancel pending isc_socket_send() and isc_socket_sendto() calls. + * + * \li ISC_SOCKCANCEL_ACCEPT: + * Cancel pending isc_socket_accept() calls. + * + * \li ISC_SOCKCANCEL_CONNECT: + * Cancel pending isc_socket_connect() call. + */ + +void +isc_socket_shutdown(isc_socket_t *sock, unsigned int how); +/*%< + * Shutdown 'socket' according to 'how'. + * + * Requires: + * + * \li 'socket' is a valid socket. + * + * \li 'task' is NULL or is a valid task. + * + * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then + * + * The read queue must be empty. + * + * No further read requests may be made. + * + * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then + * + * The write queue must be empty. + * + * No further write requests may be made. + */ + +void +isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); +/*%< + * Attach *socketp to socket. + * + * Requires: + * + * \li 'socket' is a valid socket. + * + * \li 'socketp' points to a NULL socket. + * + * Ensures: + * + * \li *socketp is attached to socket. + */ + +void +isc_socket_detach(isc_socket_t **socketp); +/*%< + * Detach *socketp from its socket. + * + * Requires: + * + * \li 'socketp' points to a valid socket. + * + * \li If '*socketp' is the last reference to the socket, + * then: + * + * There must be no pending I/O requests. + * + * Ensures: + * + * \li *socketp is NULL. + * + * \li If '*socketp' is the last reference to the socket, + * then: + * + * The socket will be shutdown (both reading and writing) + * for all tasks. + * + * All resources used by the socket have been freed + */ + +isc_result_t +isc_socket_open(isc_socket_t *sock); +/*%< + * Open a new socket file descriptor of the given socket structure. It simply + * opens a new descriptor; all of the other parameters including the socket + * type are inherited from the existing socket. This function is provided to + * avoid overhead of destroying and creating sockets when many short-lived + * sockets are frequently opened and closed. When the efficiency is not an + * issue, it should be safer to detach the unused socket and re-create a new + * 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 + */ + +isc_result_t +isc_socket_close(isc_socket_t *sock); +/*%< + * Close a socket file descriptor of the given socket structure. This function + * is provided as an alternative to destroying an unused socket when overhead + * destroying/re-creating sockets can be significant, and is expected to be + * used with isc_socket_open(). 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_close() should not be called on sockets created by + * isc_socket_fdwatchcreate(). + * + * Requires: + * + * \li The socket must have a valid descriptor. + * + * \li There must be no other reference to this socket. + * + * \li There must be no pending I/O requests. + * + * \li 'sock->type' is not isc_sockettype_fdwatch + * + * Returns: + * \li #ISC_R_NOTIMPLEMENTED + */ + +isc_result_t +isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp, + unsigned int options); +/*%< + * Bind 'socket' to '*addressp'. + * + * Requires: + * + * \li 'socket' is a valid socket + * + * \li 'addressp' points to a valid isc_sockaddr. + * + * Returns: + * + * \li ISC_R_SUCCESS + * \li ISC_R_NOPERM + * \li ISC_R_ADDRNOTAVAIL + * \li ISC_R_ADDRINUSE + * \li ISC_R_BOUND + * \li ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_filter(isc_socket_t *sock, const char *filter); +/*%< + * Inform the kernel that it should perform accept filtering. + * If filter is NULL the current filter will be removed.:w + */ + +isc_result_t +isc_socket_listen(isc_socket_t *sock, unsigned int backlog); +/*%< + * 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: + * + * \li 'backlog' is as in the UNIX system call listen() and may be + * ignored by non-UNIX implementations. + * + * \li If 'backlog' is zero, a reasonable system default is used, usually + * SOMAXCONN. + * + * Requires: + * + * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. + * + * Returns: + * + * \li ISC_R_SUCCESS + * \li ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_accept(isc_socket_t *sock, + isc_task_t *task, isc_taskaction_t action, void *arg); +/*%< + * 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: + * \li 'socket' is a valid TCP socket that isc_socket_listen() was called + * on. + * + * \li 'task' is a valid task + * + * \li 'action' is a valid action + * + * RETURNS: + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY + * \li ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp, + isc_task_t *task, isc_taskaction_t action, + void *arg); +/*%< + * Connect 'socket' to peer with address *saddr. When the connection + * succeeds, or when an error occurs, a CONNECT event with action 'action' + * and arg 'arg' will be posted to the event queue for 'task'. + * + * Requires: + * + * \li 'socket' is a valid TCP socket + * + * \li 'addressp' points to a valid isc_sockaddr + * + * \li 'task' is a valid task + * + * \li 'action' is a valid action + * + * Returns: + * + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY + * \li ISC_R_UNEXPECTED + * + * Posted event's result code: + * + * \li ISC_R_SUCCESS + * \li ISC_R_TIMEDOUT + * \li ISC_R_CONNREFUSED + * \li ISC_R_NETUNREACH + * \li ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); +/*%< + * Get the name of the peer connected to 'socket'. + * + * Requires: + * + * \li 'socket' is a valid TCP socket. + * + * Returns: + * + * \li ISC_R_SUCCESS + * \li ISC_R_TOOSMALL + * \li ISC_R_UNEXPECTED + */ + +isc_result_t +isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); +/*%< + * Get the name of 'socket'. + * + * Requires: + * + * \li 'socket' is a valid socket. + * + * Returns: + * + * \li ISC_R_SUCCESS + * \li ISC_R_TOOSMALL + * \li ISC_R_UNEXPECTED + */ + +/*@{*/ +isc_result_t +isc_socket_recv(isc_socket_t *sock, isc_region_t *region, + unsigned int minimum, + isc_task_t *task, isc_taskaction_t action, void *arg); +isc_result_t +isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist, + unsigned int minimum, + isc_task_t *task, isc_taskaction_t action, void *arg); + +isc_result_t +isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, + unsigned int minimum, isc_task_t *task, + isc_socketevent_t *event, unsigned int flags); + +/*! + * Receive from 'socket', storing the results in region. + * + * Notes: + * + *\li Let 'length' refer to the length of 'region' or to the sum of all + * available regions in the list of buffers '*buflist'. + * + *\li If 'minimum' is non-zero and at least that many bytes are read, + * the completion event will be posted to the task 'task.' If minimum + * is zero, the exact number of bytes requested in the region must + * be read for an event to be posted. This only makes sense for TCP + * connections, and is always set to 1 byte for UDP. + * + *\li The read will complete when the desired number of bytes have been + * read, if end-of-input occurs, or if an error occurs. A read done + * event with the given 'action' and 'arg' will be posted to the + * event queue of 'task'. + * + *\li The caller may not modify 'region', the buffers which are passed + * into this function, or any data they refer to until the completion + * event is received. + * + *\li For isc_socket_recvv(): + * On successful completion, '*buflist' will be empty, and the list of + * all buffers will be returned in the done event's 'bufferlist' + * member. On error return, '*buflist' will be unchanged. + * + *\li For isc_socket_recv2(): + * 'event' is not NULL, and the non-socket specific fields are + * expected to be initialized. + * + *\li For isc_socket_recv2(): + * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If + * set and the operation completes, the return value will be + * ISC_R_SUCCESS and the event will be filled in and not sent. If the + * operation does not complete, the return value will be + * ISC_R_INPROGRESS and the event will be sent when the operation + * completes. + * + * Requires: + * + *\li 'socket' is a valid, bound socket. + * + *\li For isc_socket_recv(): + * 'region' is a valid region + * + *\li For isc_socket_recvv(): + * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. + * + *\li 'task' is a valid task + * + *\li For isc_socket_recv() and isc_socket_recvv(): + * action != NULL and is a valid action + * + *\li For isc_socket_recv2(): + * event != NULL + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_INPROGRESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED + * + * Event results: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_UNEXPECTED + *\li XXX needs other net-type errors + */ +/*@}*/ + +/*@{*/ +isc_result_t +isc_socket_send(isc_socket_t *sock, isc_region_t *region, + isc_task_t *task, isc_taskaction_t action, void *arg); +isc_result_t +isc_socket_sendto(isc_socket_t *sock, isc_region_t *region, + isc_task_t *task, isc_taskaction_t action, void *arg, + isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); +isc_result_t +isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist, + isc_task_t *task, isc_taskaction_t action, void *arg); +isc_result_t +isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist, + isc_task_t *task, isc_taskaction_t action, void *arg, + isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); +isc_result_t +isc_socket_sendtov2(isc_socket_t *sock, isc_bufferlist_t *buflist, + isc_task_t *task, isc_taskaction_t action, void *arg, + isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, + unsigned int flags); +isc_result_t +isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, + isc_task_t *task, + isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, + isc_socketevent_t *event, unsigned int flags); + +/*! + * Send the contents of 'region' to the socket's peer. + * + * Notes: + * + *\li Shutting down the requestor's task *may* result in any + * still pending writes being dropped or completed, depending on the + * underlying OS implementation. + * + *\li If 'action' is NULL, then no completion event will be posted. + * + *\li The caller may not modify 'region', the buffers which are passed + * into this function, or any data they refer to until the completion + * event is received. + * + *\li For isc_socket_sendv() and isc_socket_sendtov(): + * On successful completion, '*buflist' will be empty, and the list of + * all buffers will be returned in the done event's 'bufferlist' + * member. On error return, '*buflist' will be unchanged. + * + *\li For isc_socket_sendto2(): + * 'event' is not NULL, and the non-socket specific fields are + * expected to be initialized. + * + *\li For isc_socket_sendto2(): + * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE + * and ISC_SOCKFLAG_NORETRY. + * + *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the + * return value will be ISC_R_SUCCESS and the event will be filled + * in and not sent. If the operation does not complete, the return + * value will be ISC_R_INPROGRESS and the event will be sent when + * the operation completes. + * + *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set + * and the send operation fails due to a transient error, the send + * will not be retried and the error will be indicated in the event. + * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller + * to specify a region that is allocated on the stack. + * + * Requires: + * + *\li 'socket' is a valid, bound socket. + * + *\li For isc_socket_send(): + * 'region' is a valid region + * + *\li For isc_socket_sendv() and isc_socket_sendtov(): + * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. + * + *\li 'task' is a valid task + * + *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and + * isc_socket_sendto(): + * action == NULL or is a valid action + * + *\li For isc_socket_sendto2(): + * event != NULL + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_INPROGRESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED + * + * Event results: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_UNEXPECTED + *\li XXX needs other net-type errors + */ +/*@}*/ + +isc_result_t +isc_socketmgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx, + isc_socketmgr_t **managerp); + +isc_result_t +isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); + +isc_result_t +isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp, + unsigned int maxsocks); +/*%< + * Create a socket manager. If "maxsocks" is non-zero, it specifies the + * maximum number of sockets that the created manager should handle. + * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with + * "maxsocks" being zero. + * isc_socketmgr_createinctx() also associates the new manager with the + * specified application context. + * + * Notes: + * + *\li All memory will be allocated in memory context 'mctx'. + * + * Requires: + * + *\li 'mctx' is a valid memory context. + * + *\li 'managerp' points to a NULL isc_socketmgr_t. + * + *\li 'actx' is a valid application context (for createinctx()). + * + * Ensures: + * + *\li '*managerp' is a valid isc_socketmgr_t. + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED + *\li #ISC_R_NOTIMPLEMENTED + */ + +isc_result_t +isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp); +/*%< + * Returns in "*nsockp" the maximum number of sockets this manager may open. + * + * Requires: + * + *\li '*manager' is a valid isc_socketmgr_t. + *\li 'nsockp' is not NULL. + * + * Returns: + * + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTIMPLEMENTED + */ + +void +isc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats); +/*%< + * Set a general socket statistics counter set 'stats' for 'manager'. + * + * Requires: + * \li 'manager' is valid, hasn't opened any socket, and doesn't have + * stats already set. + * + *\li stats is a valid statistics supporting socket statistics counters + * (see above). + */ + +void +isc_socketmgr_destroy(isc_socketmgr_t **managerp); +/*%< + * Destroy a socket manager. + * + * Notes: + * + *\li This routine blocks until there are no sockets left in the manager, + * so if the caller holds any socket references using the manager, it + * must detach them before calling isc_socketmgr_destroy() or it will + * block forever. + * + * Requires: + * + *\li '*managerp' is a valid isc_socketmgr_t. + * + *\li All sockets managed by this manager are fully detached. + * + * Ensures: + * + *\li *managerp == NULL + * + *\li All resources used by the manager have been freed. + */ + +isc_sockettype_t +isc_socket_gettype(isc_socket_t *sock); +/*%< + * Returns the socket type for "sock." + * + * Requires: + * + *\li "sock" is a valid socket. + */ + +/*@{*/ +bool +isc__socket_isbound(isc_socket_t *sock); +/*% + * Intended for internal use in BIND9 only + */ + +void +isc_socket_ipv6only(isc_socket_t *sock, bool yes); +/*%< + * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket + * option if the host OS supports this option. + * + * Requires: + *\li 'sock' is a valid socket. + */ +/*@}*/ + +void +isc_socket_dscp(isc_socket_t *sock, isc_dscp_t dscp); +/*%< + * Sets the Differentiated Services Code Point (DSCP) field for packets + * transmitted on this socket. If 'dscp' is -1, return immediately. + * + * Requires: + *\li 'sock' is a valid socket. + */ + +isc_socketevent_t * +isc_socket_socketevent(isc_mem_t *mctx, void *sender, + isc_eventtype_t eventtype, isc_taskaction_t action, + void *arg); +/*%< + * Get a isc_socketevent_t to be used with isc_socket_sendto2(), etc. + */ + +void +isc_socket_cleanunix(isc_sockaddr_t *addr, bool active); + +/*%< + * Cleanup UNIX domain sockets in the file-system. If 'active' is true + * then just unlink the socket. If 'active' is false try to determine + * if there is a listener of the socket or not. If no listener is found + * then unlink socket. + * + * Prior to unlinking the path is tested to see if it a socket. + * + * Note: there are a number of race conditions which cannot be avoided + * both in the filesystem and any application using UNIX domain + * sockets (e.g. socket is tested between bind() and listen(), + * the socket is deleted and replaced in the file-system between + * stat() and unlink()). + */ + +isc_result_t +isc_socket_permunix(isc_sockaddr_t *sockaddr, uint32_t perm, + uint32_t owner, uint32_t group); +/*%< + * Set ownership and file permissions on the UNIX domain socket. + * + * Note: On Solaris and SunOS this secures the directory containing + * the socket as Solaris and SunOS do not honour the filesystem + * permissions on the socket. + * + * Requires: + * \li 'sockaddr' to be a valid UNIX domain sockaddr. + * + * Returns: + * \li #ISC_R_SUCCESS + * \li #ISC_R_FAILURE + */ + +void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag); +/*%< + * Set the name and optional tag for a socket. This allows tracking of the + * owner or purpose for this socket, and is useful for tracing and statistics + * reporting. + */ + +const char *isc_socket_getname(isc_socket_t *socket); +/*%< + * Get the name associated with a socket, if any. + */ + +void *isc_socket_gettag(isc_socket_t *socket); +/*%< + * Get the tag associated with a socket, if any. + */ + +int isc_socket_getfd(isc_socket_t *socket); +/*%< + * Get the file descriptor associated with a socket + */ + +void +isc__socketmgr_setreserved(isc_socketmgr_t *mgr, uint32_t); +/*%< + * Temporary. For use by named only. + */ + +void +isc__socketmgr_maxudp(isc_socketmgr_t *mgr, int maxudp); +/*%< + * Test interface. Drop UDP packet > 'maxudp'. + */ + +#ifdef HAVE_LIBXML2 +int +isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer); +/*%< + * Render internal statistics and other state into the XML document. + */ +#endif /* HAVE_LIBXML2 */ + +#ifdef HAVE_JSON +isc_result_t +isc_socketmgr_renderjson(isc_socketmgr_t *mgr, json_object *stats); +/*%< + * Render internal statistics and other state into JSON format. + */ +#endif /* HAVE_JSON */ + +/*%< + * See isc_socketmgr_create() above. + */ +typedef isc_result_t +(*isc_socketmgrcreatefunc_t)(isc_mem_t *mctx, isc_socketmgr_t **managerp); + +isc_result_t +isc_socket_register(isc_socketmgrcreatefunc_t createfunc); +/*%< + * Register a new socket I/O implementation and add it to the list of + * supported implementations. This function must be called when a different + * event library is used than the one contained in the ISC library. + */ + +isc_result_t +isc__socket_register(void); +/*%< + * A short cut function that specifies the socket I/O module in the ISC + * library for isc_socket_register(). An application that uses the ISC library + * usually do not have to care about this function: it would call + * isc_lib_register(), which internally calls this function. + */ + +ISC_LANG_ENDDECLS + +#endif /* ISC_SOCKET_H */ |