1135446Strhodes/* 2262706Serwin * Copyright (C) 2004-2009, 2011-2013 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 1998-2002 Internet Software Consortium. 4135446Strhodes * 5182645Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18234010Sdougb/* $Id$ */ 19135446Strhodes 20135446Strhodes#ifndef ISC_SOCKET_H 21135446Strhodes#define ISC_SOCKET_H 1 22135446Strhodes 23135446Strhodes/***** 24135446Strhodes ***** Module Info 25135446Strhodes *****/ 26135446Strhodes 27193149Sdougb/*! \file isc/socket.h 28170222Sdougb * \brief Provides TCP and UDP sockets for network I/O. The sockets are event 29135446Strhodes * sources in the task system. 30135446Strhodes * 31135446Strhodes * When I/O completes, a completion event for the socket is posted to the 32135446Strhodes * event queue of the task which requested the I/O. 33135446Strhodes * 34170222Sdougb * \li MP: 35135446Strhodes * The module ensures appropriate synchronization of data structures it 36135446Strhodes * creates and manipulates. 37135446Strhodes * Clients of this module must not be holding a socket's task's lock when 38135446Strhodes * making a call that affects that socket. Failure to follow this rule 39135446Strhodes * can result in deadlock. 40135446Strhodes * The caller must ensure that isc_socketmgr_destroy() is called only 41135446Strhodes * once for a given manager. 42135446Strhodes * 43170222Sdougb * \li Reliability: 44135446Strhodes * No anticipated impact. 45135446Strhodes * 46170222Sdougb * \li Resources: 47170222Sdougb * TBS 48135446Strhodes * 49170222Sdougb * \li Security: 50135446Strhodes * No anticipated impact. 51135446Strhodes * 52170222Sdougb * \li Standards: 53135446Strhodes * None. 54135446Strhodes */ 55135446Strhodes 56135446Strhodes/*** 57135446Strhodes *** Imports 58135446Strhodes ***/ 59135446Strhodes 60135446Strhodes#include <isc/lang.h> 61135446Strhodes#include <isc/types.h> 62135446Strhodes#include <isc/event.h> 63135446Strhodes#include <isc/eventclass.h> 64135446Strhodes#include <isc/time.h> 65135446Strhodes#include <isc/region.h> 66135446Strhodes#include <isc/sockaddr.h> 67193149Sdougb#include <isc/xml.h> 68135446Strhodes 69135446StrhodesISC_LANG_BEGINDECLS 70135446Strhodes 71135446Strhodes/*** 72135446Strhodes *** Constants 73135446Strhodes ***/ 74135446Strhodes 75170222Sdougb/*% 76135446Strhodes * Maximum number of buffers in a scatter/gather read/write. The operating 77135446Strhodes * system in use must support at least this number (plus one on some.) 78135446Strhodes */ 79135446Strhodes#define ISC_SOCKET_MAXSCATTERGATHER 8 80135446Strhodes 81182645Sdougb/*% 82182645Sdougb * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling 83182645Sdougb * bind() if a non zero port is specified (AF_INET and AF_INET6). 84182645Sdougb */ 85182645Sdougb#define ISC_SOCKET_REUSEADDRESS 0x01U 86182645Sdougb 87193149Sdougb/*% 88193149Sdougb * Statistics counters. Used as isc_statscounter_t values. 89193149Sdougb */ 90193149Sdougbenum { 91193149Sdougb isc_sockstatscounter_udp4open = 0, 92193149Sdougb isc_sockstatscounter_udp6open = 1, 93193149Sdougb isc_sockstatscounter_tcp4open = 2, 94193149Sdougb isc_sockstatscounter_tcp6open = 3, 95193149Sdougb isc_sockstatscounter_unixopen = 4, 96193149Sdougb 97193149Sdougb isc_sockstatscounter_udp4openfail = 5, 98193149Sdougb isc_sockstatscounter_udp6openfail = 6, 99193149Sdougb isc_sockstatscounter_tcp4openfail = 7, 100193149Sdougb isc_sockstatscounter_tcp6openfail = 8, 101193149Sdougb isc_sockstatscounter_unixopenfail = 9, 102193149Sdougb 103193149Sdougb isc_sockstatscounter_udp4close = 10, 104193149Sdougb isc_sockstatscounter_udp6close = 11, 105193149Sdougb isc_sockstatscounter_tcp4close = 12, 106193149Sdougb isc_sockstatscounter_tcp6close = 13, 107193149Sdougb isc_sockstatscounter_unixclose = 14, 108193149Sdougb isc_sockstatscounter_fdwatchclose = 15, 109193149Sdougb 110193149Sdougb isc_sockstatscounter_udp4bindfail = 16, 111193149Sdougb isc_sockstatscounter_udp6bindfail = 17, 112193149Sdougb isc_sockstatscounter_tcp4bindfail = 18, 113193149Sdougb isc_sockstatscounter_tcp6bindfail = 19, 114193149Sdougb isc_sockstatscounter_unixbindfail = 20, 115193149Sdougb isc_sockstatscounter_fdwatchbindfail = 21, 116193149Sdougb 117193149Sdougb isc_sockstatscounter_udp4connect = 22, 118193149Sdougb isc_sockstatscounter_udp6connect = 23, 119193149Sdougb isc_sockstatscounter_tcp4connect = 24, 120193149Sdougb isc_sockstatscounter_tcp6connect = 25, 121193149Sdougb isc_sockstatscounter_unixconnect = 26, 122193149Sdougb isc_sockstatscounter_fdwatchconnect = 27, 123193149Sdougb 124193149Sdougb isc_sockstatscounter_udp4connectfail = 28, 125193149Sdougb isc_sockstatscounter_udp6connectfail = 29, 126193149Sdougb isc_sockstatscounter_tcp4connectfail = 30, 127193149Sdougb isc_sockstatscounter_tcp6connectfail = 31, 128193149Sdougb isc_sockstatscounter_unixconnectfail = 32, 129193149Sdougb isc_sockstatscounter_fdwatchconnectfail = 33, 130193149Sdougb 131193149Sdougb isc_sockstatscounter_tcp4accept = 34, 132193149Sdougb isc_sockstatscounter_tcp6accept = 35, 133193149Sdougb isc_sockstatscounter_unixaccept = 36, 134193149Sdougb 135193149Sdougb isc_sockstatscounter_tcp4acceptfail = 37, 136193149Sdougb isc_sockstatscounter_tcp6acceptfail = 38, 137193149Sdougb isc_sockstatscounter_unixacceptfail = 39, 138193149Sdougb 139193149Sdougb isc_sockstatscounter_udp4sendfail = 40, 140193149Sdougb isc_sockstatscounter_udp6sendfail = 41, 141193149Sdougb isc_sockstatscounter_tcp4sendfail = 42, 142193149Sdougb isc_sockstatscounter_tcp6sendfail = 43, 143193149Sdougb isc_sockstatscounter_unixsendfail = 44, 144193149Sdougb isc_sockstatscounter_fdwatchsendfail = 45, 145193149Sdougb 146193149Sdougb isc_sockstatscounter_udp4recvfail = 46, 147193149Sdougb isc_sockstatscounter_udp6recvfail = 47, 148193149Sdougb isc_sockstatscounter_tcp4recvfail = 48, 149193149Sdougb isc_sockstatscounter_tcp6recvfail = 49, 150193149Sdougb isc_sockstatscounter_unixrecvfail = 50, 151193149Sdougb isc_sockstatscounter_fdwatchrecvfail = 51, 152193149Sdougb 153193149Sdougb isc_sockstatscounter_max = 52 154193149Sdougb}; 155193149Sdougb 156135446Strhodes/*** 157135446Strhodes *** Types 158135446Strhodes ***/ 159135446Strhodes 160135446Strhodesstruct isc_socketevent { 161135446Strhodes ISC_EVENT_COMMON(isc_socketevent_t); 162170222Sdougb isc_result_t result; /*%< OK, EOF, whatever else */ 163170222Sdougb unsigned int minimum; /*%< minimum i/o for event */ 164170222Sdougb unsigned int n; /*%< bytes read or written */ 165170222Sdougb unsigned int offset; /*%< offset into buffer list */ 166170222Sdougb isc_region_t region; /*%< for single-buffer i/o */ 167170222Sdougb isc_bufferlist_t bufferlist; /*%< list of buffers */ 168170222Sdougb isc_sockaddr_t address; /*%< source address */ 169170222Sdougb isc_time_t timestamp; /*%< timestamp of packet recv */ 170170222Sdougb struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ 171170222Sdougb isc_uint32_t attributes; /*%< see below */ 172170222Sdougb isc_eventdestructor_t destroy; /*%< original destructor */ 173135446Strhodes}; 174135446Strhodes 175135446Strhodestypedef struct isc_socket_newconnev isc_socket_newconnev_t; 176135446Strhodesstruct isc_socket_newconnev { 177135446Strhodes ISC_EVENT_COMMON(isc_socket_newconnev_t); 178135446Strhodes isc_socket_t * newsocket; 179170222Sdougb isc_result_t result; /*%< OK, EOF, whatever else */ 180170222Sdougb isc_sockaddr_t address; /*%< source address */ 181135446Strhodes}; 182135446Strhodes 183135446Strhodestypedef struct isc_socket_connev isc_socket_connev_t; 184135446Strhodesstruct isc_socket_connev { 185135446Strhodes ISC_EVENT_COMMON(isc_socket_connev_t); 186170222Sdougb isc_result_t result; /*%< OK, EOF, whatever else */ 187135446Strhodes}; 188135446Strhodes 189170222Sdougb/*@{*/ 190170222Sdougb/*! 191135446Strhodes * _ATTACHED: Internal use only. 192135446Strhodes * _TRUNC: Packet was truncated on receive. 193135446Strhodes * _CTRUNC: Packet control information was truncated. This can 194135446Strhodes * indicate that the packet is not complete, even though 195135446Strhodes * all the data is valid. 196135446Strhodes * _TIMESTAMP: The timestamp member is valid. 197135446Strhodes * _PKTINFO: The pktinfo member is valid. 198135446Strhodes * _MULTICAST: The UDP packet was received via a multicast transmission. 199135446Strhodes */ 200135446Strhodes#define ISC_SOCKEVENTATTR_ATTACHED 0x80000000U /* internal */ 201135446Strhodes#define ISC_SOCKEVENTATTR_TRUNC 0x00800000U /* public */ 202135446Strhodes#define ISC_SOCKEVENTATTR_CTRUNC 0x00400000U /* public */ 203135446Strhodes#define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */ 204135446Strhodes#define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */ 205135446Strhodes#define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */ 206170222Sdougb/*@}*/ 207135446Strhodes 208135446Strhodes#define ISC_SOCKEVENT_ANYEVENT (0) 209135446Strhodes#define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) 210135446Strhodes#define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2) 211135446Strhodes#define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3) 212135446Strhodes#define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4) 213135446Strhodes 214135446Strhodes/* 215135446Strhodes * Internal events. 216135446Strhodes */ 217135446Strhodes#define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256) 218135446Strhodes#define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257) 219135446Strhodes 220135446Strhodestypedef enum { 221135446Strhodes isc_sockettype_udp = 1, 222170222Sdougb isc_sockettype_tcp = 2, 223193149Sdougb isc_sockettype_unix = 3, 224193149Sdougb isc_sockettype_fdwatch = 4 225135446Strhodes} isc_sockettype_t; 226135446Strhodes 227170222Sdougb/*@{*/ 228170222Sdougb/*! 229135446Strhodes * How a socket should be shutdown in isc_socket_shutdown() calls. 230135446Strhodes */ 231170222Sdougb#define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ 232170222Sdougb#define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ 233170222Sdougb#define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ 234170222Sdougb/*@}*/ 235135446Strhodes 236170222Sdougb/*@{*/ 237170222Sdougb/*! 238135446Strhodes * What I/O events to cancel in isc_socket_cancel() calls. 239135446Strhodes */ 240170222Sdougb#define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ 241170222Sdougb#define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ 242170222Sdougb#define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ 243170222Sdougb#define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ 244170222Sdougb#define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ 245170222Sdougb/*@}*/ 246135446Strhodes 247170222Sdougb/*@{*/ 248170222Sdougb/*! 249135446Strhodes * Flags for isc_socket_send() and isc_socket_recv() calls. 250135446Strhodes */ 251170222Sdougb#define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ 252170222Sdougb#define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ 253170222Sdougb/*@}*/ 254135446Strhodes 255193149Sdougb/*@{*/ 256193149Sdougb/*! 257193149Sdougb * Flags for fdwatchcreate. 258193149Sdougb */ 259193149Sdougb#define ISC_SOCKFDWATCH_READ 0x00000001 /*%< watch for readable */ 260193149Sdougb#define ISC_SOCKFDWATCH_WRITE 0x00000002 /*%< watch for writable */ 261193149Sdougb/*@}*/ 262193149Sdougb 263224092Sdougb/*% Socket and socket manager methods */ 264224092Sdougbtypedef struct isc_socketmgrmethods { 265224092Sdougb void (*destroy)(isc_socketmgr_t **managerp); 266224092Sdougb isc_result_t (*socketcreate)(isc_socketmgr_t *manager, int pf, 267224092Sdougb isc_sockettype_t type, 268224092Sdougb isc_socket_t **socketp); 269224092Sdougb isc_result_t (*fdwatchcreate)(isc_socketmgr_t *manager, int fd, 270224092Sdougb int flags, 271224092Sdougb isc_sockfdwatch_t callback, 272224092Sdougb void *cbarg, isc_task_t *task, 273224092Sdougb isc_socket_t **socketp); 274224092Sdougb} isc_socketmgrmethods_t; 275224092Sdougb 276224092Sdougbtypedef struct isc_socketmethods { 277224092Sdougb void (*attach)(isc_socket_t *socket, 278224092Sdougb isc_socket_t **socketp); 279224092Sdougb void (*detach)(isc_socket_t **socketp); 280224092Sdougb isc_result_t (*bind)(isc_socket_t *sock, isc_sockaddr_t *sockaddr, 281224092Sdougb unsigned int options); 282224092Sdougb isc_result_t (*sendto)(isc_socket_t *sock, isc_region_t *region, 283224092Sdougb isc_task_t *task, isc_taskaction_t action, 284224092Sdougb const void *arg, isc_sockaddr_t *address, 285224092Sdougb struct in6_pktinfo *pktinfo); 286254897Serwin isc_result_t (*sendto2)(isc_socket_t *sock, isc_region_t *region, 287254897Serwin isc_task_t *task, isc_sockaddr_t *address, 288254897Serwin struct in6_pktinfo *pktinfo, 289254897Serwin isc_socketevent_t *event, 290254897Serwin unsigned int flags); 291224092Sdougb isc_result_t (*connect)(isc_socket_t *sock, isc_sockaddr_t *addr, 292224092Sdougb isc_task_t *task, isc_taskaction_t action, 293224092Sdougb const void *arg); 294224092Sdougb isc_result_t (*recv)(isc_socket_t *sock, isc_region_t *region, 295224092Sdougb unsigned int minimum, isc_task_t *task, 296224092Sdougb isc_taskaction_t action, const void *arg); 297254897Serwin isc_result_t (*recv2)(isc_socket_t *sock, isc_region_t *region, 298254897Serwin unsigned int minimum, isc_task_t *task, 299254897Serwin isc_socketevent_t *event, unsigned int flags); 300224092Sdougb void (*cancel)(isc_socket_t *sock, isc_task_t *task, 301224092Sdougb unsigned int how); 302224092Sdougb isc_result_t (*getsockname)(isc_socket_t *sock, 303224092Sdougb isc_sockaddr_t *addressp); 304224092Sdougb isc_sockettype_t (*gettype)(isc_socket_t *sock); 305224092Sdougb void (*ipv6only)(isc_socket_t *sock, isc_boolean_t yes); 306224092Sdougb isc_result_t (*fdwatchpoke)(isc_socket_t *sock, int flags); 307254897Serwin isc_result_t (*dup)(isc_socket_t *socket, 308254897Serwin isc_socket_t **socketp); 309254897Serwin int (*getfd)(isc_socket_t *socket); 310224092Sdougb} isc_socketmethods_t; 311224092Sdougb 312224092Sdougb/*% 313224092Sdougb * This structure is actually just the common prefix of a socket manager 314224092Sdougb * object implementation's version of an isc_socketmgr_t. 315224092Sdougb * \brief 316224092Sdougb * Direct use of this structure by clients is forbidden. socket implementations 317224092Sdougb * may change the structure. 'magic' must be ISCAPI_SOCKETMGR_MAGIC for any 318224092Sdougb * of the isc_socket_ routines to work. socket implementations must maintain 319224092Sdougb * all socket invariants. 320224092Sdougb * In effect, this definition is used only for non-BIND9 version ("export") 321224092Sdougb * of the library, and the export version does not work for win32. So, to avoid 322224092Sdougb * the definition conflict with win32/socket.c, we enable this definition only 323224092Sdougb * for non-Win32 (i.e. Unix) platforms. 324224092Sdougb */ 325224092Sdougb#ifndef WIN32 326224092Sdougbstruct isc_socketmgr { 327224092Sdougb unsigned int impmagic; 328224092Sdougb unsigned int magic; 329224092Sdougb isc_socketmgrmethods_t *methods; 330224092Sdougb}; 331224092Sdougb#endif 332224092Sdougb 333224092Sdougb#define ISCAPI_SOCKETMGR_MAGIC ISC_MAGIC('A','s','m','g') 334224092Sdougb#define ISCAPI_SOCKETMGR_VALID(m) ((m) != NULL && \ 335224092Sdougb (m)->magic == ISCAPI_SOCKETMGR_MAGIC) 336224092Sdougb 337224092Sdougb/*% 338224092Sdougb * This is the common prefix of a socket object. The same note as 339224092Sdougb * that for the socketmgr structure applies. 340224092Sdougb */ 341224092Sdougb#ifndef WIN32 342224092Sdougbstruct isc_socket { 343224092Sdougb unsigned int impmagic; 344224092Sdougb unsigned int magic; 345224092Sdougb isc_socketmethods_t *methods; 346224092Sdougb}; 347224092Sdougb#endif 348224092Sdougb 349224092Sdougb#define ISCAPI_SOCKET_MAGIC ISC_MAGIC('A','s','c','t') 350224092Sdougb#define ISCAPI_SOCKET_VALID(s) ((s) != NULL && \ 351224092Sdougb (s)->magic == ISCAPI_SOCKET_MAGIC) 352224092Sdougb 353135446Strhodes/*** 354135446Strhodes *** Socket and Socket Manager Functions 355135446Strhodes *** 356135446Strhodes *** Note: all Ensures conditions apply only if the result is success for 357135446Strhodes *** those functions which return an isc_result. 358135446Strhodes ***/ 359135446Strhodes 360135446Strhodesisc_result_t 361193149Sdougbisc_socket_fdwatchcreate(isc_socketmgr_t *manager, 362193149Sdougb int fd, 363193149Sdougb int flags, 364193149Sdougb isc_sockfdwatch_t callback, 365193149Sdougb void *cbarg, 366193149Sdougb isc_task_t *task, 367193149Sdougb isc_socket_t **socketp); 368193149Sdougb/*%< 369193149Sdougb * Create a new file descriptor watch socket managed by 'manager'. 370193149Sdougb * 371193149Sdougb * Note: 372193149Sdougb * 373193149Sdougb *\li 'fd' is the already-opened file descriptor. 374193149Sdougb *\li This function is not available on Windows. 375193149Sdougb *\li The callback function is called "in-line" - this means the function 376193149Sdougb * needs to return as fast as possible, as all other I/O will be suspended 377193149Sdougb * until the callback completes. 378193149Sdougb * 379193149Sdougb * Requires: 380193149Sdougb * 381193149Sdougb *\li 'manager' is a valid manager 382193149Sdougb * 383193149Sdougb *\li 'socketp' is a valid pointer, and *socketp == NULL 384193149Sdougb * 385193149Sdougb *\li 'fd' be opened. 386193149Sdougb * 387193149Sdougb * Ensures: 388193149Sdougb * 389193149Sdougb * '*socketp' is attached to the newly created fdwatch socket 390193149Sdougb * 391193149Sdougb * Returns: 392193149Sdougb * 393193149Sdougb *\li #ISC_R_SUCCESS 394193149Sdougb *\li #ISC_R_NOMEMORY 395193149Sdougb *\li #ISC_R_NORESOURCES 396193149Sdougb *\li #ISC_R_UNEXPECTED 397193149Sdougb */ 398193149Sdougb 399193149Sdougbisc_result_t 400224092Sdougbisc_socket_fdwatchpoke(isc_socket_t *sock, 401224092Sdougb int flags); 402224092Sdougb/*%< 403224092Sdougb * Poke a file descriptor watch socket informing the manager that it 404224092Sdougb * should restart watching the socket 405224092Sdougb * 406224092Sdougb * Note: 407224092Sdougb * 408224092Sdougb *\li 'sock' is the socket returned by isc_socket_fdwatchcreate 409224092Sdougb * 410224092Sdougb *\li 'flags' indicates what the manager should watch for on the socket 411224092Sdougb * in addition to what it may already be watching. It can be one or 412224092Sdougb * both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE. To 413224092Sdougb * temporarily disable watching on a socket the value indicating 414224092Sdougb * no more data should be returned from the call back routine. 415224092Sdougb * 416224092Sdougb *\li This function is not available on Windows. 417224092Sdougb * 418224092Sdougb * Requires: 419224092Sdougb * 420224092Sdougb *\li 'sock' is a valid isc socket 421224092Sdougb * 422224092Sdougb * 423224092Sdougb * Returns: 424224092Sdougb * 425224092Sdougb *\li #ISC_R_SUCCESS 426224092Sdougb */ 427224092Sdougb 428224092Sdougbisc_result_t 429135446Strhodesisc_socket_create(isc_socketmgr_t *manager, 430135446Strhodes int pf, 431135446Strhodes isc_sockettype_t type, 432135446Strhodes isc_socket_t **socketp); 433170222Sdougb/*%< 434135446Strhodes * Create a new 'type' socket managed by 'manager'. 435135446Strhodes * 436193149Sdougb * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate() 437193149Sdougb * rather than isc_socket_create(). 438193149Sdougb * 439135446Strhodes * Note: 440135446Strhodes * 441170222Sdougb *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. 442135446Strhodes * 443135446Strhodes * Requires: 444135446Strhodes * 445170222Sdougb *\li 'manager' is a valid manager 446135446Strhodes * 447170222Sdougb *\li 'socketp' is a valid pointer, and *socketp == NULL 448135446Strhodes * 449193149Sdougb *\li 'type' is not isc_sockettype_fdwatch 450193149Sdougb * 451135446Strhodes * Ensures: 452135446Strhodes * 453135446Strhodes * '*socketp' is attached to the newly created socket 454135446Strhodes * 455135446Strhodes * Returns: 456135446Strhodes * 457170222Sdougb *\li #ISC_R_SUCCESS 458170222Sdougb *\li #ISC_R_NOMEMORY 459170222Sdougb *\li #ISC_R_NORESOURCES 460170222Sdougb *\li #ISC_R_UNEXPECTED 461135446Strhodes */ 462135446Strhodes 463254897Serwinisc_result_t 464254897Serwinisc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp); 465254897Serwin/*%< 466254897Serwin * Duplicate an existing socket, reusing its file descriptor. 467254897Serwin */ 468254897Serwin 469135446Strhodesvoid 470135446Strhodesisc_socket_cancel(isc_socket_t *sock, isc_task_t *task, 471135446Strhodes unsigned int how); 472170222Sdougb/*%< 473135446Strhodes * Cancel pending I/O of the type specified by "how". 474135446Strhodes * 475135446Strhodes * Note: if "task" is NULL, then the cancel applies to all tasks using the 476135446Strhodes * socket. 477135446Strhodes * 478135446Strhodes * Requires: 479135446Strhodes * 480170222Sdougb * \li "socket" is a valid socket 481135446Strhodes * 482170222Sdougb * \li "task" is NULL or a valid task 483135446Strhodes * 484135446Strhodes * "how" is a bitmask describing the type of cancelation to perform. 485135446Strhodes * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this 486135446Strhodes * socket. 487135446Strhodes * 488170222Sdougb * \li ISC_SOCKCANCEL_RECV: 489135446Strhodes * Cancel pending isc_socket_recv() calls. 490135446Strhodes * 491170222Sdougb * \li ISC_SOCKCANCEL_SEND: 492135446Strhodes * Cancel pending isc_socket_send() and isc_socket_sendto() calls. 493135446Strhodes * 494170222Sdougb * \li ISC_SOCKCANCEL_ACCEPT: 495135446Strhodes * Cancel pending isc_socket_accept() calls. 496135446Strhodes * 497170222Sdougb * \li ISC_SOCKCANCEL_CONNECT: 498135446Strhodes * Cancel pending isc_socket_connect() call. 499135446Strhodes */ 500135446Strhodes 501135446Strhodesvoid 502135446Strhodesisc_socket_shutdown(isc_socket_t *sock, unsigned int how); 503170222Sdougb/*%< 504135446Strhodes * Shutdown 'socket' according to 'how'. 505135446Strhodes * 506135446Strhodes * Requires: 507135446Strhodes * 508170222Sdougb * \li 'socket' is a valid socket. 509135446Strhodes * 510170222Sdougb * \li 'task' is NULL or is a valid task. 511135446Strhodes * 512170222Sdougb * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then 513135446Strhodes * 514135446Strhodes * The read queue must be empty. 515135446Strhodes * 516135446Strhodes * No further read requests may be made. 517135446Strhodes * 518170222Sdougb * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then 519135446Strhodes * 520135446Strhodes * The write queue must be empty. 521135446Strhodes * 522135446Strhodes * No further write requests may be made. 523135446Strhodes */ 524135446Strhodes 525135446Strhodesvoid 526135446Strhodesisc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); 527170222Sdougb/*%< 528135446Strhodes * Attach *socketp to socket. 529135446Strhodes * 530135446Strhodes * Requires: 531135446Strhodes * 532170222Sdougb * \li 'socket' is a valid socket. 533135446Strhodes * 534170222Sdougb * \li 'socketp' points to a NULL socket. 535135446Strhodes * 536135446Strhodes * Ensures: 537135446Strhodes * 538170222Sdougb * \li *socketp is attached to socket. 539135446Strhodes */ 540135446Strhodes 541135446Strhodesvoid 542135446Strhodesisc_socket_detach(isc_socket_t **socketp); 543170222Sdougb/*%< 544135446Strhodes * Detach *socketp from its socket. 545135446Strhodes * 546135446Strhodes * Requires: 547135446Strhodes * 548170222Sdougb * \li 'socketp' points to a valid socket. 549135446Strhodes * 550170222Sdougb * \li If '*socketp' is the last reference to the socket, 551135446Strhodes * then: 552135446Strhodes * 553135446Strhodes * There must be no pending I/O requests. 554135446Strhodes * 555135446Strhodes * Ensures: 556135446Strhodes * 557170222Sdougb * \li *socketp is NULL. 558135446Strhodes * 559170222Sdougb * \li If '*socketp' is the last reference to the socket, 560135446Strhodes * then: 561135446Strhodes * 562135446Strhodes * The socket will be shutdown (both reading and writing) 563135446Strhodes * for all tasks. 564135446Strhodes * 565135446Strhodes * All resources used by the socket have been freed 566135446Strhodes */ 567135446Strhodes 568135446Strhodesisc_result_t 569186462Sdougbisc_socket_open(isc_socket_t *sock); 570186462Sdougb/*%< 571186462Sdougb * Open a new socket file descriptor of the given socket structure. It simply 572186462Sdougb * opens a new descriptor; all of the other parameters including the socket 573186462Sdougb * type are inherited from the existing socket. This function is provided to 574186462Sdougb * avoid overhead of destroying and creating sockets when many short-lived 575186462Sdougb * sockets are frequently opened and closed. When the efficiency is not an 576186462Sdougb * issue, it should be safer to detach the unused socket and re-create a new 577186462Sdougb * one. This optimization may not be available for some systems, in which 578186462Sdougb * case this function will return ISC_R_NOTIMPLEMENTED and must not be used. 579186462Sdougb * 580193149Sdougb * isc_socket_open() should not be called on sockets created by 581193149Sdougb * isc_socket_fdwatchcreate(). 582193149Sdougb * 583186462Sdougb * Requires: 584186462Sdougb * 585186462Sdougb * \li there must be no other reference to this socket. 586186462Sdougb * 587186462Sdougb * \li 'socket' is a valid and previously closed by isc_socket_close() 588186462Sdougb * 589193149Sdougb * \li 'sock->type' is not isc_sockettype_fdwatch 590193149Sdougb * 591186462Sdougb * Returns: 592186462Sdougb * Same as isc_socket_create(). 593186462Sdougb * \li ISC_R_NOTIMPLEMENTED 594186462Sdougb */ 595186462Sdougb 596186462Sdougbisc_result_t 597186462Sdougbisc_socket_close(isc_socket_t *sock); 598186462Sdougb/*%< 599186462Sdougb * Close a socket file descriptor of the given socket structure. This function 600186462Sdougb * is provided as an alternative to destroying an unused socket when overhead 601186462Sdougb * destroying/re-creating sockets can be significant, and is expected to be 602186462Sdougb * used with isc_socket_open(). This optimization may not be available for some 603186462Sdougb * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and 604186462Sdougb * must not be used. 605186462Sdougb * 606193149Sdougb * isc_socket_close() should not be called on sockets created by 607193149Sdougb * isc_socket_fdwatchcreate(). 608193149Sdougb * 609186462Sdougb * Requires: 610186462Sdougb * 611186462Sdougb * \li The socket must have a valid descriptor. 612186462Sdougb * 613186462Sdougb * \li There must be no other reference to this socket. 614186462Sdougb * 615186462Sdougb * \li There must be no pending I/O requests. 616186462Sdougb * 617193149Sdougb * \li 'sock->type' is not isc_sockettype_fdwatch 618193149Sdougb * 619186462Sdougb * Returns: 620186462Sdougb * \li #ISC_R_NOTIMPLEMENTED 621186462Sdougb */ 622186462Sdougb 623186462Sdougbisc_result_t 624182645Sdougbisc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp, 625186462Sdougb unsigned int options); 626170222Sdougb/*%< 627135446Strhodes * Bind 'socket' to '*addressp'. 628135446Strhodes * 629135446Strhodes * Requires: 630135446Strhodes * 631170222Sdougb * \li 'socket' is a valid socket 632135446Strhodes * 633170222Sdougb * \li 'addressp' points to a valid isc_sockaddr. 634135446Strhodes * 635135446Strhodes * Returns: 636135446Strhodes * 637170222Sdougb * \li ISC_R_SUCCESS 638170222Sdougb * \li ISC_R_NOPERM 639170222Sdougb * \li ISC_R_ADDRNOTAVAIL 640170222Sdougb * \li ISC_R_ADDRINUSE 641170222Sdougb * \li ISC_R_BOUND 642170222Sdougb * \li ISC_R_UNEXPECTED 643135446Strhodes */ 644135446Strhodes 645135446Strhodesisc_result_t 646135446Strhodesisc_socket_filter(isc_socket_t *sock, const char *filter); 647170222Sdougb/*%< 648135446Strhodes * Inform the kernel that it should perform accept filtering. 649135446Strhodes * If filter is NULL the current filter will be removed.:w 650135446Strhodes */ 651135446Strhodes 652135446Strhodesisc_result_t 653135446Strhodesisc_socket_listen(isc_socket_t *sock, unsigned int backlog); 654170222Sdougb/*%< 655135446Strhodes * Set listen mode on the socket. After this call, the only function that 656135446Strhodes * can be used (other than attach and detach) is isc_socket_accept(). 657135446Strhodes * 658135446Strhodes * Notes: 659135446Strhodes * 660170222Sdougb * \li 'backlog' is as in the UNIX system call listen() and may be 661135446Strhodes * ignored by non-UNIX implementations. 662135446Strhodes * 663170222Sdougb * \li If 'backlog' is zero, a reasonable system default is used, usually 664135446Strhodes * SOMAXCONN. 665135446Strhodes * 666135446Strhodes * Requires: 667135446Strhodes * 668170222Sdougb * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. 669135446Strhodes * 670135446Strhodes * Returns: 671135446Strhodes * 672170222Sdougb * \li ISC_R_SUCCESS 673170222Sdougb * \li ISC_R_UNEXPECTED 674135446Strhodes */ 675135446Strhodes 676135446Strhodesisc_result_t 677135446Strhodesisc_socket_accept(isc_socket_t *sock, 678135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg); 679170222Sdougb/*%< 680135446Strhodes * Queue accept event. When a new connection is received, the task will 681135446Strhodes * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen 682135446Strhodes * socket. The new socket structure is sent inside the isc_socket_newconnev_t 683135446Strhodes * event type, and is attached to the task 'task'. 684135446Strhodes * 685135446Strhodes * REQUIRES: 686170222Sdougb * \li 'socket' is a valid TCP socket that isc_socket_listen() was called 687135446Strhodes * on. 688135446Strhodes * 689170222Sdougb * \li 'task' is a valid task 690135446Strhodes * 691170222Sdougb * \li 'action' is a valid action 692135446Strhodes * 693135446Strhodes * RETURNS: 694170222Sdougb * \li ISC_R_SUCCESS 695170222Sdougb * \li ISC_R_NOMEMORY 696170222Sdougb * \li ISC_R_UNEXPECTED 697135446Strhodes */ 698135446Strhodes 699135446Strhodesisc_result_t 700135446Strhodesisc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp, 701135446Strhodes isc_task_t *task, isc_taskaction_t action, 702135446Strhodes const void *arg); 703170222Sdougb/*%< 704135446Strhodes * Connect 'socket' to peer with address *saddr. When the connection 705135446Strhodes * succeeds, or when an error occurs, a CONNECT event with action 'action' 706135446Strhodes * and arg 'arg' will be posted to the event queue for 'task'. 707135446Strhodes * 708135446Strhodes * Requires: 709135446Strhodes * 710170222Sdougb * \li 'socket' is a valid TCP socket 711135446Strhodes * 712170222Sdougb * \li 'addressp' points to a valid isc_sockaddr 713135446Strhodes * 714170222Sdougb * \li 'task' is a valid task 715135446Strhodes * 716170222Sdougb * \li 'action' is a valid action 717135446Strhodes * 718135446Strhodes * Returns: 719135446Strhodes * 720170222Sdougb * \li ISC_R_SUCCESS 721170222Sdougb * \li ISC_R_NOMEMORY 722170222Sdougb * \li ISC_R_UNEXPECTED 723135446Strhodes * 724135446Strhodes * Posted event's result code: 725135446Strhodes * 726170222Sdougb * \li ISC_R_SUCCESS 727170222Sdougb * \li ISC_R_TIMEDOUT 728170222Sdougb * \li ISC_R_CONNREFUSED 729170222Sdougb * \li ISC_R_NETUNREACH 730170222Sdougb * \li ISC_R_UNEXPECTED 731135446Strhodes */ 732135446Strhodes 733135446Strhodesisc_result_t 734135446Strhodesisc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); 735170222Sdougb/*%< 736135446Strhodes * Get the name of the peer connected to 'socket'. 737135446Strhodes * 738135446Strhodes * Requires: 739135446Strhodes * 740170222Sdougb * \li 'socket' is a valid TCP socket. 741135446Strhodes * 742135446Strhodes * Returns: 743135446Strhodes * 744170222Sdougb * \li ISC_R_SUCCESS 745170222Sdougb * \li ISC_R_TOOSMALL 746170222Sdougb * \li ISC_R_UNEXPECTED 747135446Strhodes */ 748135446Strhodes 749135446Strhodesisc_result_t 750135446Strhodesisc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); 751170222Sdougb/*%< 752135446Strhodes * Get the name of 'socket'. 753135446Strhodes * 754135446Strhodes * Requires: 755135446Strhodes * 756170222Sdougb * \li 'socket' is a valid socket. 757135446Strhodes * 758135446Strhodes * Returns: 759135446Strhodes * 760170222Sdougb * \li ISC_R_SUCCESS 761170222Sdougb * \li ISC_R_TOOSMALL 762170222Sdougb * \li ISC_R_UNEXPECTED 763135446Strhodes */ 764135446Strhodes 765170222Sdougb/*@{*/ 766135446Strhodesisc_result_t 767135446Strhodesisc_socket_recv(isc_socket_t *sock, isc_region_t *region, 768135446Strhodes unsigned int minimum, 769135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg); 770135446Strhodesisc_result_t 771135446Strhodesisc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist, 772135446Strhodes unsigned int minimum, 773135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg); 774135446Strhodes 775135446Strhodesisc_result_t 776135446Strhodesisc_socket_recv2(isc_socket_t *sock, isc_region_t *region, 777135446Strhodes unsigned int minimum, isc_task_t *task, 778135446Strhodes isc_socketevent_t *event, unsigned int flags); 779135446Strhodes 780170222Sdougb/*! 781135446Strhodes * Receive from 'socket', storing the results in region. 782135446Strhodes * 783135446Strhodes * Notes: 784135446Strhodes * 785170222Sdougb *\li Let 'length' refer to the length of 'region' or to the sum of all 786135446Strhodes * available regions in the list of buffers '*buflist'. 787135446Strhodes * 788170222Sdougb *\li If 'minimum' is non-zero and at least that many bytes are read, 789135446Strhodes * the completion event will be posted to the task 'task.' If minimum 790135446Strhodes * is zero, the exact number of bytes requested in the region must 791135446Strhodes * be read for an event to be posted. This only makes sense for TCP 792135446Strhodes * connections, and is always set to 1 byte for UDP. 793135446Strhodes * 794170222Sdougb *\li The read will complete when the desired number of bytes have been 795135446Strhodes * read, if end-of-input occurs, or if an error occurs. A read done 796135446Strhodes * event with the given 'action' and 'arg' will be posted to the 797135446Strhodes * event queue of 'task'. 798135446Strhodes * 799170222Sdougb *\li The caller may not modify 'region', the buffers which are passed 800135446Strhodes * into this function, or any data they refer to until the completion 801135446Strhodes * event is received. 802135446Strhodes * 803170222Sdougb *\li For isc_socket_recvv(): 804135446Strhodes * On successful completion, '*buflist' will be empty, and the list of 805135446Strhodes * all buffers will be returned in the done event's 'bufferlist' 806135446Strhodes * member. On error return, '*buflist' will be unchanged. 807135446Strhodes * 808170222Sdougb *\li For isc_socket_recv2(): 809135446Strhodes * 'event' is not NULL, and the non-socket specific fields are 810135446Strhodes * expected to be initialized. 811135446Strhodes * 812170222Sdougb *\li For isc_socket_recv2(): 813135446Strhodes * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If 814135446Strhodes * set and the operation completes, the return value will be 815135446Strhodes * ISC_R_SUCCESS and the event will be filled in and not sent. If the 816135446Strhodes * operation does not complete, the return value will be 817135446Strhodes * ISC_R_INPROGRESS and the event will be sent when the operation 818135446Strhodes * completes. 819135446Strhodes * 820135446Strhodes * Requires: 821135446Strhodes * 822170222Sdougb *\li 'socket' is a valid, bound socket. 823135446Strhodes * 824170222Sdougb *\li For isc_socket_recv(): 825135446Strhodes * 'region' is a valid region 826135446Strhodes * 827170222Sdougb *\li For isc_socket_recvv(): 828135446Strhodes * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 829135446Strhodes * 830170222Sdougb *\li 'task' is a valid task 831135446Strhodes * 832170222Sdougb *\li For isc_socket_recv() and isc_socket_recvv(): 833135446Strhodes * action != NULL and is a valid action 834135446Strhodes * 835170222Sdougb *\li For isc_socket_recv2(): 836135446Strhodes * event != NULL 837135446Strhodes * 838135446Strhodes * Returns: 839135446Strhodes * 840170222Sdougb *\li #ISC_R_SUCCESS 841170222Sdougb *\li #ISC_R_INPROGRESS 842170222Sdougb *\li #ISC_R_NOMEMORY 843170222Sdougb *\li #ISC_R_UNEXPECTED 844135446Strhodes * 845135446Strhodes * Event results: 846135446Strhodes * 847170222Sdougb *\li #ISC_R_SUCCESS 848170222Sdougb *\li #ISC_R_UNEXPECTED 849170222Sdougb *\li XXX needs other net-type errors 850135446Strhodes */ 851170222Sdougb/*@}*/ 852135446Strhodes 853170222Sdougb/*@{*/ 854135446Strhodesisc_result_t 855135446Strhodesisc_socket_send(isc_socket_t *sock, isc_region_t *region, 856135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg); 857135446Strhodesisc_result_t 858135446Strhodesisc_socket_sendto(isc_socket_t *sock, isc_region_t *region, 859135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg, 860135446Strhodes isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 861135446Strhodesisc_result_t 862135446Strhodesisc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist, 863135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg); 864135446Strhodesisc_result_t 865135446Strhodesisc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist, 866135446Strhodes isc_task_t *task, isc_taskaction_t action, const void *arg, 867135446Strhodes isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 868135446Strhodesisc_result_t 869262706Serwinisc_socket_sendtov2(isc_socket_t *sock, isc_bufferlist_t *buflist, 870262706Serwin isc_task_t *task, isc_taskaction_t action, const void *arg, 871262706Serwin isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 872262706Serwin unsigned int flags); 873262706Serwinisc_result_t 874135446Strhodesisc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, 875135446Strhodes isc_task_t *task, 876135446Strhodes isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 877135446Strhodes isc_socketevent_t *event, unsigned int flags); 878135446Strhodes 879170222Sdougb/*! 880135446Strhodes * Send the contents of 'region' to the socket's peer. 881135446Strhodes * 882135446Strhodes * Notes: 883135446Strhodes * 884170222Sdougb *\li Shutting down the requestor's task *may* result in any 885135446Strhodes * still pending writes being dropped or completed, depending on the 886135446Strhodes * underlying OS implementation. 887135446Strhodes * 888170222Sdougb *\li If 'action' is NULL, then no completion event will be posted. 889135446Strhodes * 890170222Sdougb *\li The caller may not modify 'region', the buffers which are passed 891135446Strhodes * into this function, or any data they refer to until the completion 892135446Strhodes * event is received. 893135446Strhodes * 894170222Sdougb *\li For isc_socket_sendv() and isc_socket_sendtov(): 895135446Strhodes * On successful completion, '*buflist' will be empty, and the list of 896135446Strhodes * all buffers will be returned in the done event's 'bufferlist' 897135446Strhodes * member. On error return, '*buflist' will be unchanged. 898135446Strhodes * 899170222Sdougb *\li For isc_socket_sendto2(): 900135446Strhodes * 'event' is not NULL, and the non-socket specific fields are 901135446Strhodes * expected to be initialized. 902135446Strhodes * 903170222Sdougb *\li For isc_socket_sendto2(): 904135446Strhodes * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE 905135446Strhodes * and ISC_SOCKFLAG_NORETRY. 906135446Strhodes * 907170222Sdougb *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the 908135446Strhodes * return value will be ISC_R_SUCCESS and the event will be filled 909135446Strhodes * in and not sent. If the operation does not complete, the return 910135446Strhodes * value will be ISC_R_INPROGRESS and the event will be sent when 911135446Strhodes * the operation completes. 912135446Strhodes * 913170222Sdougb *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set 914135446Strhodes * and the send operation fails due to a transient error, the send 915135446Strhodes * will not be retried and the error will be indicated in the event. 916135446Strhodes * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller 917135446Strhodes * to specify a region that is allocated on the stack. 918135446Strhodes * 919135446Strhodes * Requires: 920135446Strhodes * 921170222Sdougb *\li 'socket' is a valid, bound socket. 922135446Strhodes * 923170222Sdougb *\li For isc_socket_send(): 924135446Strhodes * 'region' is a valid region 925135446Strhodes * 926170222Sdougb *\li For isc_socket_sendv() and isc_socket_sendtov(): 927135446Strhodes * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 928135446Strhodes * 929170222Sdougb *\li 'task' is a valid task 930135446Strhodes * 931170222Sdougb *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and 932135446Strhodes * isc_socket_sendto(): 933135446Strhodes * action == NULL or is a valid action 934135446Strhodes * 935170222Sdougb *\li For isc_socket_sendto2(): 936135446Strhodes * event != NULL 937135446Strhodes * 938135446Strhodes * Returns: 939135446Strhodes * 940170222Sdougb *\li #ISC_R_SUCCESS 941170222Sdougb *\li #ISC_R_INPROGRESS 942170222Sdougb *\li #ISC_R_NOMEMORY 943170222Sdougb *\li #ISC_R_UNEXPECTED 944135446Strhodes * 945135446Strhodes * Event results: 946135446Strhodes * 947170222Sdougb *\li #ISC_R_SUCCESS 948170222Sdougb *\li #ISC_R_UNEXPECTED 949170222Sdougb *\li XXX needs other net-type errors 950135446Strhodes */ 951170222Sdougb/*@}*/ 952135446Strhodes 953135446Strhodesisc_result_t 954224092Sdougbisc_socketmgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx, 955224092Sdougb isc_socketmgr_t **managerp); 956224092Sdougb 957224092Sdougbisc_result_t 958135446Strhodesisc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); 959186462Sdougb 960186462Sdougbisc_result_t 961186462Sdougbisc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp, 962186462Sdougb unsigned int maxsocks); 963170222Sdougb/*%< 964186462Sdougb * Create a socket manager. If "maxsocks" is non-zero, it specifies the 965186462Sdougb * maximum number of sockets that the created manager should handle. 966186462Sdougb * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with 967186462Sdougb * "maxsocks" being zero. 968224092Sdougb * isc_socketmgr_createinctx() also associates the new manager with the 969224092Sdougb * specified application context. 970135446Strhodes * 971135446Strhodes * Notes: 972135446Strhodes * 973170222Sdougb *\li All memory will be allocated in memory context 'mctx'. 974135446Strhodes * 975135446Strhodes * Requires: 976135446Strhodes * 977170222Sdougb *\li 'mctx' is a valid memory context. 978135446Strhodes * 979170222Sdougb *\li 'managerp' points to a NULL isc_socketmgr_t. 980135446Strhodes * 981224092Sdougb *\li 'actx' is a valid application context (for createinctx()). 982224092Sdougb * 983135446Strhodes * Ensures: 984135446Strhodes * 985170222Sdougb *\li '*managerp' is a valid isc_socketmgr_t. 986135446Strhodes * 987135446Strhodes * Returns: 988135446Strhodes * 989170222Sdougb *\li #ISC_R_SUCCESS 990170222Sdougb *\li #ISC_R_NOMEMORY 991170222Sdougb *\li #ISC_R_UNEXPECTED 992186462Sdougb *\li #ISC_R_NOTIMPLEMENTED 993135446Strhodes */ 994135446Strhodes 995186462Sdougbisc_result_t 996186462Sdougbisc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp); 997186462Sdougb/*%< 998186462Sdougb * Returns in "*nsockp" the maximum number of sockets this manager may open. 999186462Sdougb * 1000186462Sdougb * Requires: 1001186462Sdougb * 1002186462Sdougb *\li '*manager' is a valid isc_socketmgr_t. 1003186462Sdougb *\li 'nsockp' is not NULL. 1004186462Sdougb * 1005186462Sdougb * Returns: 1006186462Sdougb * 1007186462Sdougb *\li #ISC_R_SUCCESS 1008186462Sdougb *\li #ISC_R_NOTIMPLEMENTED 1009186462Sdougb */ 1010186462Sdougb 1011135446Strhodesvoid 1012193149Sdougbisc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats); 1013193149Sdougb/*%< 1014193149Sdougb * Set a general socket statistics counter set 'stats' for 'manager'. 1015193149Sdougb * 1016193149Sdougb * Requires: 1017193149Sdougb * \li 'manager' is valid, hasn't opened any socket, and doesn't have 1018193149Sdougb * stats already set. 1019193149Sdougb * 1020193149Sdougb *\li stats is a valid statistics supporting socket statistics counters 1021193149Sdougb * (see above). 1022193149Sdougb */ 1023193149Sdougb 1024193149Sdougbvoid 1025135446Strhodesisc_socketmgr_destroy(isc_socketmgr_t **managerp); 1026170222Sdougb/*%< 1027135446Strhodes * Destroy a socket manager. 1028135446Strhodes * 1029135446Strhodes * Notes: 1030135446Strhodes * 1031170222Sdougb *\li This routine blocks until there are no sockets left in the manager, 1032135446Strhodes * so if the caller holds any socket references using the manager, it 1033135446Strhodes * must detach them before calling isc_socketmgr_destroy() or it will 1034135446Strhodes * block forever. 1035135446Strhodes * 1036135446Strhodes * Requires: 1037135446Strhodes * 1038170222Sdougb *\li '*managerp' is a valid isc_socketmgr_t. 1039135446Strhodes * 1040170222Sdougb *\li All sockets managed by this manager are fully detached. 1041135446Strhodes * 1042135446Strhodes * Ensures: 1043135446Strhodes * 1044170222Sdougb *\li *managerp == NULL 1045135446Strhodes * 1046170222Sdougb *\li All resources used by the manager have been freed. 1047135446Strhodes */ 1048135446Strhodes 1049135446Strhodesisc_sockettype_t 1050135446Strhodesisc_socket_gettype(isc_socket_t *sock); 1051170222Sdougb/*%< 1052135446Strhodes * Returns the socket type for "sock." 1053135446Strhodes * 1054135446Strhodes * Requires: 1055135446Strhodes * 1056170222Sdougb *\li "sock" is a valid socket. 1057135446Strhodes */ 1058135446Strhodes 1059170222Sdougb/*@{*/ 1060135446Strhodesisc_boolean_t 1061135446Strhodesisc_socket_isbound(isc_socket_t *sock); 1062135446Strhodes 1063135446Strhodesvoid 1064135446Strhodesisc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes); 1065170222Sdougb/*%< 1066135446Strhodes * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket 1067135446Strhodes * option if the host OS supports this option. 1068135446Strhodes * 1069135446Strhodes * Requires: 1070170222Sdougb *\li 'sock' is a valid socket. 1071135446Strhodes */ 1072170222Sdougb/*@}*/ 1073135446Strhodes 1074170222Sdougbvoid 1075170222Sdougbisc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active); 1076170222Sdougb 1077170222Sdougb/*%< 1078170222Sdougb * Cleanup UNIX domain sockets in the file-system. If 'active' is true 1079170222Sdougb * then just unlink the socket. If 'active' is false try to determine 1080170222Sdougb * if there is a listener of the socket or not. If no listener is found 1081170222Sdougb * then unlink socket. 1082170222Sdougb * 1083170222Sdougb * Prior to unlinking the path is tested to see if it a socket. 1084170222Sdougb * 1085170222Sdougb * Note: there are a number of race conditions which cannot be avoided 1086170222Sdougb * both in the filesystem and any application using UNIX domain 1087170222Sdougb * sockets (e.g. socket is tested between bind() and listen(), 1088170222Sdougb * the socket is deleted and replaced in the file-system between 1089170222Sdougb * stat() and unlink()). 1090170222Sdougb */ 1091170222Sdougb 1092170222Sdougbisc_result_t 1093170222Sdougbisc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm, 1094186462Sdougb isc_uint32_t owner, isc_uint32_t group); 1095170222Sdougb/*%< 1096170222Sdougb * Set ownership and file permissions on the UNIX domain socket. 1097170222Sdougb * 1098170222Sdougb * Note: On Solaris and SunOS this secures the directory containing 1099193149Sdougb * the socket as Solaris and SunOS do not honour the filesystem 1100170222Sdougb * permissions on the socket. 1101170222Sdougb * 1102170222Sdougb * Requires: 1103170222Sdougb * \li 'sockaddr' to be a valid UNIX domain sockaddr. 1104170222Sdougb * 1105170222Sdougb * Returns: 1106170222Sdougb * \li #ISC_R_SUCCESS 1107170222Sdougb * \li #ISC_R_FAILURE 1108170222Sdougb */ 1109170222Sdougb 1110193149Sdougbvoid isc_socket_setname(isc_socket_t *socket, const char *name, void *tag); 1111193149Sdougb/*%< 1112193149Sdougb * Set the name and optional tag for a socket. This allows tracking of the 1113193149Sdougb * owner or purpose for this socket, and is useful for tracing and statistics 1114193149Sdougb * reporting. 1115193149Sdougb */ 1116193149Sdougb 1117193149Sdougbconst char *isc_socket_getname(isc_socket_t *socket); 1118193149Sdougb/*%< 1119193149Sdougb * Get the name associated with a socket, if any. 1120193149Sdougb */ 1121193149Sdougb 1122193149Sdougbvoid *isc_socket_gettag(isc_socket_t *socket); 1123193149Sdougb/*%< 1124193149Sdougb * Get the tag associated with a socket, if any. 1125193149Sdougb */ 1126193149Sdougb 1127254897Serwinint isc_socket_getfd(isc_socket_t *socket); 1128254897Serwin/*%< 1129254897Serwin * Get the file descriptor associated with a socket 1130254897Serwin */ 1131254897Serwin 1132182645Sdougbvoid 1133182645Sdougbisc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t); 1134182645Sdougb/*%< 1135182645Sdougb * Temporary. For use by named only. 1136182645Sdougb */ 1137182645Sdougb 1138224092Sdougbvoid 1139224092Sdougbisc__socketmgr_maxudp(isc_socketmgr_t *mgr, int maxudp); 1140224092Sdougb/*%< 1141224092Sdougb * Test interface. Drop UDP packet > 'maxudp'. 1142224092Sdougb */ 1143224092Sdougb 1144193149Sdougb#ifdef HAVE_LIBXML2 1145193149Sdougb 1146254402Serwinint 1147193149Sdougbisc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer); 1148193149Sdougb/*%< 1149193149Sdougb * Render internal statistics and other state into the XML document. 1150193149Sdougb */ 1151193149Sdougb 1152193149Sdougb#endif /* HAVE_LIBXML2 */ 1153193149Sdougb 1154224092Sdougb#ifdef USE_SOCKETIMPREGISTER 1155224092Sdougb/*%< 1156224092Sdougb * See isc_socketmgr_create() above. 1157224092Sdougb */ 1158224092Sdougbtypedef isc_result_t 1159224092Sdougb(*isc_socketmgrcreatefunc_t)(isc_mem_t *mctx, isc_socketmgr_t **managerp); 1160224092Sdougb 1161224092Sdougbisc_result_t 1162224092Sdougbisc_socket_register(isc_socketmgrcreatefunc_t createfunc); 1163224092Sdougb/*%< 1164224092Sdougb * Register a new socket I/O implementation and add it to the list of 1165224092Sdougb * supported implementations. This function must be called when a different 1166224092Sdougb * event library is used than the one contained in the ISC library. 1167224092Sdougb */ 1168224092Sdougb 1169224092Sdougbisc_result_t 1170224092Sdougbisc__socket_register(void); 1171224092Sdougb/*%< 1172224092Sdougb * A short cut function that specifies the socket I/O module in the ISC 1173224092Sdougb * library for isc_socket_register(). An application that uses the ISC library 1174224092Sdougb * usually do not have to care about this function: it would call 1175224092Sdougb * isc_lib_register(), which internally calls this function. 1176224092Sdougb */ 1177224092Sdougb#endif /* USE_SOCKETIMPREGISTER */ 1178224092Sdougb 1179135446StrhodesISC_LANG_ENDDECLS 1180135446Strhodes 1181135446Strhodes#endif /* ISC_SOCKET_H */ 1182