1 /* $NetBSD: socket.h,v 1.9 2014/12/10 04:38:00 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2009, 2011-2014 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1998-2002 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id */ 21 22 #ifndef ISC_SOCKET_H 23 #define ISC_SOCKET_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file isc/socket.h 30 * \brief Provides TCP and UDP sockets for network I/O. The sockets are event 31 * sources in the task system. 32 * 33 * When I/O completes, a completion event for the socket is posted to the 34 * event queue of the task which requested the I/O. 35 * 36 * \li MP: 37 * The module ensures appropriate synchronization of data structures it 38 * creates and manipulates. 39 * Clients of this module must not be holding a socket's task's lock when 40 * making a call that affects that socket. Failure to follow this rule 41 * can result in deadlock. 42 * The caller must ensure that isc_socketmgr_destroy() is called only 43 * once for a given manager. 44 * 45 * \li Reliability: 46 * No anticipated impact. 47 * 48 * \li Resources: 49 * TBS 50 * 51 * \li Security: 52 * No anticipated impact. 53 * 54 * \li Standards: 55 * None. 56 */ 57 58 /*** 59 *** Imports 60 ***/ 61 62 #include <isc/event.h> 63 #include <isc/eventclass.h> 64 #include <isc/lang.h> 65 #include <isc/json.h> 66 #include <isc/region.h> 67 #include <isc/sockaddr.h> 68 #include <isc/time.h> 69 #include <isc/types.h> 70 #include <isc/xml.h> 71 72 #ifdef WIN32 73 74 /* from the old namespace.h */ 75 76 #define isc_socket_create isc__socket_create 77 #define isc_socket_dup isc__socket_dup 78 #define isc_socket_attach isc__socket_attach 79 #define isc_socket_detach isc__socket_detach 80 #define isc_socketmgr_create isc__socketmgr_create 81 #define isc_socketmgr_create2 isc__socketmgr_create2 82 #define isc_socketmgr_destroy isc__socketmgr_destroy 83 #define isc_socket_open isc__socket_open 84 #define isc_socket_close isc__socket_close 85 #define isc_socket_recvv isc__socket_recvv 86 #define isc_socket_recv isc__socket_recv 87 #define isc_socket_recv2 isc__socket_recv2 88 #define isc_socket_send isc__socket_send 89 #define isc_socket_sendto isc__socket_sendto 90 #define isc_socket_sendv isc__socket_sendv 91 #define isc_socket_sendtov isc__socket_sendtov 92 #define isc_socket_sendtov2 isc__socket_sendtov2 93 #define isc_socket_sendto2 isc__socket_sendto2 94 #define isc_socket_cleanunix isc__socket_cleanunix 95 #define isc_socket_permunix isc__socket_permunix 96 #define isc_socket_bind isc__socket_bind 97 #define isc_socket_filter isc__socket_filter 98 #define isc_socket_listen isc__socket_listen 99 #define isc_socket_accept isc__socket_accept 100 #define isc_socket_connect isc__socket_connect 101 #define isc_socket_getfd isc__socket_getfd 102 #define isc_socket_getname isc__socket_getname 103 #define isc_socket_gettag isc__socket_gettag 104 #define isc_socket_getpeername isc__socket_getpeername 105 #define isc_socket_getsockname isc__socket_getsockname 106 #define isc_socket_cancel isc__socket_cancel 107 #define isc_socket_gettype isc__socket_gettype 108 #define isc_socket_isbound isc__socket_isbound 109 #define isc_socket_ipv6only isc__socket_ipv6only 110 #define isc_socket_setname isc__socket_setname 111 #define isc_socketmgr_getmaxsockets isc__socketmgr_getmaxsockets 112 #define isc_socketmgr_setstats isc__socketmgr_setstats 113 #define isc_socketmgr_setreserved isc__socketmgr_setreserved 114 #define isc__socketmgr_maxudp isc___socketmgr_maxudp 115 #define isc_socket_fdwatchcreate isc__socket_fdwatchcreate 116 #define isc_socket_fdwatchpoke isc__socket_fdwatchpoke 117 #define isc_socket_dscp isc__socket_dscp 118 119 #endif 120 121 ISC_LANG_BEGINDECLS 122 123 /*** 124 *** Constants 125 ***/ 126 127 /*% 128 * Maximum number of buffers in a scatter/gather read/write. The operating 129 * system in use must support at least this number (plus one on some.) 130 */ 131 #define ISC_SOCKET_MAXSCATTERGATHER 8 132 133 /*% 134 * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling 135 * bind() if a non zero port is specified (AF_INET and AF_INET6). 136 */ 137 #define ISC_SOCKET_REUSEADDRESS 0x01U 138 139 /*% 140 * Statistics counters. Used as isc_statscounter_t values. 141 */ 142 enum { 143 isc_sockstatscounter_udp4open = 0, 144 isc_sockstatscounter_udp6open = 1, 145 isc_sockstatscounter_tcp4open = 2, 146 isc_sockstatscounter_tcp6open = 3, 147 isc_sockstatscounter_unixopen = 4, 148 149 isc_sockstatscounter_udp4openfail = 5, 150 isc_sockstatscounter_udp6openfail = 6, 151 isc_sockstatscounter_tcp4openfail = 7, 152 isc_sockstatscounter_tcp6openfail = 8, 153 isc_sockstatscounter_unixopenfail = 9, 154 155 isc_sockstatscounter_udp4close = 10, 156 isc_sockstatscounter_udp6close = 11, 157 isc_sockstatscounter_tcp4close = 12, 158 isc_sockstatscounter_tcp6close = 13, 159 isc_sockstatscounter_unixclose = 14, 160 isc_sockstatscounter_fdwatchclose = 15, 161 162 isc_sockstatscounter_udp4bindfail = 16, 163 isc_sockstatscounter_udp6bindfail = 17, 164 isc_sockstatscounter_tcp4bindfail = 18, 165 isc_sockstatscounter_tcp6bindfail = 19, 166 isc_sockstatscounter_unixbindfail = 20, 167 isc_sockstatscounter_fdwatchbindfail = 21, 168 169 isc_sockstatscounter_udp4connect = 22, 170 isc_sockstatscounter_udp6connect = 23, 171 isc_sockstatscounter_tcp4connect = 24, 172 isc_sockstatscounter_tcp6connect = 25, 173 isc_sockstatscounter_unixconnect = 26, 174 isc_sockstatscounter_fdwatchconnect = 27, 175 176 isc_sockstatscounter_udp4connectfail = 28, 177 isc_sockstatscounter_udp6connectfail = 29, 178 isc_sockstatscounter_tcp4connectfail = 30, 179 isc_sockstatscounter_tcp6connectfail = 31, 180 isc_sockstatscounter_unixconnectfail = 32, 181 isc_sockstatscounter_fdwatchconnectfail = 33, 182 183 isc_sockstatscounter_tcp4accept = 34, 184 isc_sockstatscounter_tcp6accept = 35, 185 isc_sockstatscounter_unixaccept = 36, 186 187 isc_sockstatscounter_tcp4acceptfail = 37, 188 isc_sockstatscounter_tcp6acceptfail = 38, 189 isc_sockstatscounter_unixacceptfail = 39, 190 191 isc_sockstatscounter_udp4sendfail = 40, 192 isc_sockstatscounter_udp6sendfail = 41, 193 isc_sockstatscounter_tcp4sendfail = 42, 194 isc_sockstatscounter_tcp6sendfail = 43, 195 isc_sockstatscounter_unixsendfail = 44, 196 isc_sockstatscounter_fdwatchsendfail = 45, 197 198 isc_sockstatscounter_udp4recvfail = 46, 199 isc_sockstatscounter_udp6recvfail = 47, 200 isc_sockstatscounter_tcp4recvfail = 48, 201 isc_sockstatscounter_tcp6recvfail = 49, 202 isc_sockstatscounter_unixrecvfail = 50, 203 isc_sockstatscounter_fdwatchrecvfail = 51, 204 205 isc_sockstatscounter_udp4active = 52, 206 isc_sockstatscounter_udp6active = 53, 207 isc_sockstatscounter_tcp4active = 54, 208 isc_sockstatscounter_tcp6active = 55, 209 isc_sockstatscounter_unixactive = 56, 210 211 isc_sockstatscounter_rawopen = 57, 212 isc_sockstatscounter_rawopenfail = 58, 213 isc_sockstatscounter_rawclose = 59, 214 isc_sockstatscounter_rawrecvfail = 60, 215 isc_sockstatscounter_rawactive = 61, 216 217 isc_sockstatscounter_max = 62 218 }; 219 220 /*** 221 *** Types 222 ***/ 223 224 struct isc_socketevent { 225 ISC_EVENT_COMMON(isc_socketevent_t); 226 isc_result_t result; /*%< OK, EOF, whatever else */ 227 unsigned int minimum; /*%< minimum i/o for event */ 228 unsigned int n; /*%< bytes read or written */ 229 unsigned int offset; /*%< offset into buffer list */ 230 isc_region_t region; /*%< for single-buffer i/o */ 231 isc_bufferlist_t bufferlist; /*%< list of buffers */ 232 isc_sockaddr_t address; /*%< source address */ 233 isc_time_t timestamp; /*%< timestamp of packet recv */ 234 struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ 235 isc_uint32_t attributes; /*%< see below */ 236 isc_eventdestructor_t destroy; /*%< original destructor */ 237 unsigned int dscp; /*%< UDP dscp value */ 238 }; 239 240 typedef struct isc_socket_newconnev isc_socket_newconnev_t; 241 struct isc_socket_newconnev { 242 ISC_EVENT_COMMON(isc_socket_newconnev_t); 243 isc_socket_t * newsocket; 244 isc_result_t result; /*%< OK, EOF, whatever else */ 245 isc_sockaddr_t address; /*%< source address */ 246 }; 247 248 typedef struct isc_socket_connev isc_socket_connev_t; 249 struct isc_socket_connev { 250 ISC_EVENT_COMMON(isc_socket_connev_t); 251 isc_result_t result; /*%< OK, EOF, whatever else */ 252 }; 253 254 /*@{*/ 255 /*! 256 * _ATTACHED: Internal use only. 257 * _TRUNC: Packet was truncated on receive. 258 * _CTRUNC: Packet control information was truncated. This can 259 * indicate that the packet is not complete, even though 260 * all the data is valid. 261 * _TIMESTAMP: The timestamp member is valid. 262 * _PKTINFO: The pktinfo member is valid. 263 * _MULTICAST: The UDP packet was received via a multicast transmission. 264 * _DSCP: The UDP DSCP value is valid. 265 */ 266 #define ISC_SOCKEVENTATTR_ATTACHED 0x80000000U /* internal */ 267 #define ISC_SOCKEVENTATTR_TRUNC 0x00800000U /* public */ 268 #define ISC_SOCKEVENTATTR_CTRUNC 0x00400000U /* public */ 269 #define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */ 270 #define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */ 271 #define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */ 272 #define ISC_SOCKEVENTATTR_DSCP 0x00040000U /* public */ 273 /*@}*/ 274 275 #define ISC_SOCKEVENT_ANYEVENT (0) 276 #define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) 277 #define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2) 278 #define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3) 279 #define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4) 280 281 /* 282 * Internal events. 283 */ 284 #define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256) 285 #define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257) 286 287 typedef enum { 288 isc_sockettype_udp = 1, 289 isc_sockettype_tcp = 2, 290 isc_sockettype_unix = 3, 291 isc_sockettype_fdwatch = 4, 292 isc_sockettype_raw = 5 293 } isc_sockettype_t; 294 295 /*@{*/ 296 /*! 297 * How a socket should be shutdown in isc_socket_shutdown() calls. 298 */ 299 #define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ 300 #define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ 301 #define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ 302 /*@}*/ 303 304 /*@{*/ 305 /*! 306 * What I/O events to cancel in isc_socket_cancel() calls. 307 */ 308 #define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ 309 #define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ 310 #define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ 311 #define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ 312 #define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ 313 /*@}*/ 314 315 /*@{*/ 316 /*! 317 * Flags for isc_socket_send() and isc_socket_recv() calls. 318 */ 319 #define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ 320 #define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ 321 /*@}*/ 322 323 /*@{*/ 324 /*! 325 * Flags for fdwatchcreate. 326 */ 327 #define ISC_SOCKFDWATCH_READ 0x00000001 /*%< watch for readable */ 328 #define ISC_SOCKFDWATCH_WRITE 0x00000002 /*%< watch for writable */ 329 /*@}*/ 330 331 /*% Socket and socket manager methods */ 332 typedef struct isc_socketmgrmethods { 333 void (*destroy)(isc_socketmgr_t **managerp); 334 isc_result_t (*socketcreate)(isc_socketmgr_t *manager, int pf, 335 isc_sockettype_t type, 336 isc_socket_t **socketp); 337 isc_result_t (*fdwatchcreate)(isc_socketmgr_t *manager, int fd, 338 int flags, 339 isc_sockfdwatch_t callback, 340 void *cbarg, isc_task_t *task, 341 isc_socket_t **socketp); 342 } isc_socketmgrmethods_t; 343 344 typedef struct isc_socketmethods { 345 void (*attach)(isc_socket_t *socket, 346 isc_socket_t **socketp); 347 void (*detach)(isc_socket_t **socketp); 348 isc_result_t (*bind)(isc_socket_t *sock, isc_sockaddr_t *sockaddr, 349 unsigned int options); 350 isc_result_t (*sendto)(isc_socket_t *sock, isc_region_t *region, 351 isc_task_t *task, isc_taskaction_t action, 352 void *arg, isc_sockaddr_t *address, 353 struct in6_pktinfo *pktinfo); 354 isc_result_t (*sendto2)(isc_socket_t *sock, isc_region_t *region, 355 isc_task_t *task, isc_sockaddr_t *address, 356 struct in6_pktinfo *pktinfo, 357 isc_socketevent_t *event, 358 unsigned int flags); 359 isc_result_t (*connect)(isc_socket_t *sock, isc_sockaddr_t *addr, 360 isc_task_t *task, isc_taskaction_t action, 361 void *arg); 362 isc_result_t (*recv)(isc_socket_t *sock, isc_region_t *region, 363 unsigned int minimum, isc_task_t *task, 364 isc_taskaction_t action, void *arg); 365 isc_result_t (*recv2)(isc_socket_t *sock, isc_region_t *region, 366 unsigned int minimum, isc_task_t *task, 367 isc_socketevent_t *event, unsigned int flags); 368 void (*cancel)(isc_socket_t *sock, isc_task_t *task, 369 unsigned int how); 370 isc_result_t (*getsockname)(isc_socket_t *sock, 371 isc_sockaddr_t *addressp); 372 isc_sockettype_t (*gettype)(isc_socket_t *sock); 373 void (*ipv6only)(isc_socket_t *sock, isc_boolean_t yes); 374 isc_result_t (*fdwatchpoke)(isc_socket_t *sock, int flags); 375 isc_result_t (*dup)(isc_socket_t *socket, 376 isc_socket_t **socketp); 377 int (*getfd)(isc_socket_t *socket); 378 void (*dscp)(isc_socket_t *socket, isc_dscp_t dscp); 379 } isc_socketmethods_t; 380 381 /*% 382 * This structure is actually just the common prefix of a socket manager 383 * object implementation's version of an isc_socketmgr_t. 384 * \brief 385 * Direct use of this structure by clients is forbidden. socket implementations 386 * may change the structure. 'magic' must be ISCAPI_SOCKETMGR_MAGIC for any 387 * of the isc_socket_ routines to work. socket implementations must maintain 388 * all socket invariants. 389 * In effect, this definition is used only for non-BIND9 version ("export") 390 * of the library, and the export version does not work for win32. So, to avoid 391 * the definition conflict with win32/socket.c, we enable this definition only 392 * for non-Win32 (i.e. Unix) platforms. 393 */ 394 #ifndef WIN32 395 struct isc_socketmgr { 396 unsigned int impmagic; 397 unsigned int magic; 398 isc_socketmgrmethods_t *methods; 399 }; 400 #endif 401 402 #define ISCAPI_SOCKETMGR_MAGIC ISC_MAGIC('A','s','m','g') 403 #define ISCAPI_SOCKETMGR_VALID(m) ((m) != NULL && \ 404 (m)->magic == ISCAPI_SOCKETMGR_MAGIC) 405 406 /*% 407 * This is the common prefix of a socket object. The same note as 408 * that for the socketmgr structure applies. 409 */ 410 #ifndef WIN32 411 struct isc_socket { 412 unsigned int impmagic; 413 unsigned int magic; 414 isc_socketmethods_t *methods; 415 }; 416 #endif 417 418 #define ISCAPI_SOCKET_MAGIC ISC_MAGIC('A','s','c','t') 419 #define ISCAPI_SOCKET_VALID(s) ((s) != NULL && \ 420 (s)->magic == ISCAPI_SOCKET_MAGIC) 421 422 /*** 423 *** Socket and Socket Manager Functions 424 *** 425 *** Note: all Ensures conditions apply only if the result is success for 426 *** those functions which return an isc_result. 427 ***/ 428 429 isc_result_t 430 isc_socket_fdwatchcreate(isc_socketmgr_t *manager, 431 int fd, 432 int flags, 433 isc_sockfdwatch_t callback, 434 void *cbarg, 435 isc_task_t *task, 436 isc_socket_t **socketp); 437 /*%< 438 * Create a new file descriptor watch socket managed by 'manager'. 439 * 440 * Note: 441 * 442 *\li 'fd' is the already-opened file descriptor. 443 *\li This function is not available on Windows. 444 *\li The callback function is called "in-line" - this means the function 445 * needs to return as fast as possible, as all other I/O will be suspended 446 * until the callback completes. 447 * 448 * Requires: 449 * 450 *\li 'manager' is a valid manager 451 * 452 *\li 'socketp' is a valid pointer, and *socketp == NULL 453 * 454 *\li 'fd' be opened. 455 * 456 * Ensures: 457 * 458 * '*socketp' is attached to the newly created fdwatch socket 459 * 460 * Returns: 461 * 462 *\li #ISC_R_SUCCESS 463 *\li #ISC_R_NOMEMORY 464 *\li #ISC_R_NORESOURCES 465 *\li #ISC_R_UNEXPECTED 466 */ 467 468 isc_result_t 469 isc_socket_fdwatchpoke(isc_socket_t *sock, 470 int flags); 471 /*%< 472 * Poke a file descriptor watch socket informing the manager that it 473 * should restart watching the socket 474 * 475 * Note: 476 * 477 *\li 'sock' is the socket returned by isc_socket_fdwatchcreate 478 * 479 *\li 'flags' indicates what the manager should watch for on the socket 480 * in addition to what it may already be watching. It can be one or 481 * both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE. To 482 * temporarily disable watching on a socket the value indicating 483 * no more data should be returned from the call back routine. 484 * 485 *\li This function is not available on Windows. 486 * 487 * Requires: 488 * 489 *\li 'sock' is a valid isc socket 490 * 491 * 492 * Returns: 493 * 494 *\li #ISC_R_SUCCESS 495 */ 496 497 isc_result_t 498 isc_socket_create(isc_socketmgr_t *manager, 499 int pf, 500 isc_sockettype_t type, 501 isc_socket_t **socketp); 502 /*%< 503 * Create a new 'type' socket managed by 'manager'. 504 * 505 * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate() 506 * rather than isc_socket_create(). 507 * 508 * Note: 509 * 510 *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. 511 * 512 * Requires: 513 * 514 *\li 'manager' is a valid manager 515 * 516 *\li 'socketp' is a valid pointer, and *socketp == NULL 517 * 518 *\li 'type' is not isc_sockettype_fdwatch 519 * 520 * Ensures: 521 * 522 * '*socketp' is attached to the newly created socket 523 * 524 * Returns: 525 * 526 *\li #ISC_R_SUCCESS 527 *\li #ISC_R_NOMEMORY 528 *\li #ISC_R_NORESOURCES 529 *\li #ISC_R_UNEXPECTED 530 */ 531 532 isc_result_t 533 isc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp); 534 /*%< 535 * Duplicate an existing socket, reusing its file descriptor. 536 */ 537 538 void 539 isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, 540 unsigned int how); 541 /*%< 542 * Cancel pending I/O of the type specified by "how". 543 * 544 * Note: if "task" is NULL, then the cancel applies to all tasks using the 545 * socket. 546 * 547 * Requires: 548 * 549 * \li "socket" is a valid socket 550 * 551 * \li "task" is NULL or a valid task 552 * 553 * "how" is a bitmask describing the type of cancelation to perform. 554 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this 555 * socket. 556 * 557 * \li ISC_SOCKCANCEL_RECV: 558 * Cancel pending isc_socket_recv() calls. 559 * 560 * \li ISC_SOCKCANCEL_SEND: 561 * Cancel pending isc_socket_send() and isc_socket_sendto() calls. 562 * 563 * \li ISC_SOCKCANCEL_ACCEPT: 564 * Cancel pending isc_socket_accept() calls. 565 * 566 * \li ISC_SOCKCANCEL_CONNECT: 567 * Cancel pending isc_socket_connect() call. 568 */ 569 570 void 571 isc_socket_shutdown(isc_socket_t *sock, unsigned int how); 572 /*%< 573 * Shutdown 'socket' according to 'how'. 574 * 575 * Requires: 576 * 577 * \li 'socket' is a valid socket. 578 * 579 * \li 'task' is NULL or is a valid task. 580 * 581 * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then 582 * 583 * The read queue must be empty. 584 * 585 * No further read requests may be made. 586 * 587 * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then 588 * 589 * The write queue must be empty. 590 * 591 * No further write requests may be made. 592 */ 593 594 void 595 isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); 596 /*%< 597 * Attach *socketp to socket. 598 * 599 * Requires: 600 * 601 * \li 'socket' is a valid socket. 602 * 603 * \li 'socketp' points to a NULL socket. 604 * 605 * Ensures: 606 * 607 * \li *socketp is attached to socket. 608 */ 609 610 void 611 isc_socket_detach(isc_socket_t **socketp); 612 /*%< 613 * Detach *socketp from its socket. 614 * 615 * Requires: 616 * 617 * \li 'socketp' points to a valid socket. 618 * 619 * \li If '*socketp' is the last reference to the socket, 620 * then: 621 * 622 * There must be no pending I/O requests. 623 * 624 * Ensures: 625 * 626 * \li *socketp is NULL. 627 * 628 * \li If '*socketp' is the last reference to the socket, 629 * then: 630 * 631 * The socket will be shutdown (both reading and writing) 632 * for all tasks. 633 * 634 * All resources used by the socket have been freed 635 */ 636 637 isc_result_t 638 isc_socket_open(isc_socket_t *sock); 639 /*%< 640 * Open a new socket file descriptor of the given socket structure. It simply 641 * opens a new descriptor; all of the other parameters including the socket 642 * type are inherited from the existing socket. This function is provided to 643 * avoid overhead of destroying and creating sockets when many short-lived 644 * sockets are frequently opened and closed. When the efficiency is not an 645 * issue, it should be safer to detach the unused socket and re-create a new 646 * one. This optimization may not be available for some systems, in which 647 * case this function will return ISC_R_NOTIMPLEMENTED and must not be used. 648 * 649 * isc_socket_open() should not be called on sockets created by 650 * isc_socket_fdwatchcreate(). 651 * 652 * Requires: 653 * 654 * \li there must be no other reference to this socket. 655 * 656 * \li 'socket' is a valid and previously closed by isc_socket_close() 657 * 658 * \li 'sock->type' is not isc_sockettype_fdwatch 659 * 660 * Returns: 661 * Same as isc_socket_create(). 662 * \li ISC_R_NOTIMPLEMENTED 663 */ 664 665 isc_result_t 666 isc_socket_close(isc_socket_t *sock); 667 /*%< 668 * Close a socket file descriptor of the given socket structure. This function 669 * is provided as an alternative to destroying an unused socket when overhead 670 * destroying/re-creating sockets can be significant, and is expected to be 671 * used with isc_socket_open(). This optimization may not be available for some 672 * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and 673 * must not be used. 674 * 675 * isc_socket_close() should not be called on sockets created by 676 * isc_socket_fdwatchcreate(). 677 * 678 * Requires: 679 * 680 * \li The socket must have a valid descriptor. 681 * 682 * \li There must be no other reference to this socket. 683 * 684 * \li There must be no pending I/O requests. 685 * 686 * \li 'sock->type' is not isc_sockettype_fdwatch 687 * 688 * Returns: 689 * \li #ISC_R_NOTIMPLEMENTED 690 */ 691 692 isc_result_t 693 isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp, 694 unsigned int options); 695 /*%< 696 * Bind 'socket' to '*addressp'. 697 * 698 * Requires: 699 * 700 * \li 'socket' is a valid socket 701 * 702 * \li 'addressp' points to a valid isc_sockaddr. 703 * 704 * Returns: 705 * 706 * \li ISC_R_SUCCESS 707 * \li ISC_R_NOPERM 708 * \li ISC_R_ADDRNOTAVAIL 709 * \li ISC_R_ADDRINUSE 710 * \li ISC_R_BOUND 711 * \li ISC_R_UNEXPECTED 712 */ 713 714 isc_result_t 715 isc_socket_filter(isc_socket_t *sock, const char *filter); 716 /*%< 717 * Inform the kernel that it should perform accept filtering. 718 * If filter is NULL the current filter will be removed.:w 719 */ 720 721 isc_result_t 722 isc_socket_listen(isc_socket_t *sock, unsigned int backlog); 723 /*%< 724 * Set listen mode on the socket. After this call, the only function that 725 * can be used (other than attach and detach) is isc_socket_accept(). 726 * 727 * Notes: 728 * 729 * \li 'backlog' is as in the UNIX system call listen() and may be 730 * ignored by non-UNIX implementations. 731 * 732 * \li If 'backlog' is zero, a reasonable system default is used, usually 733 * SOMAXCONN. 734 * 735 * Requires: 736 * 737 * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. 738 * 739 * Returns: 740 * 741 * \li ISC_R_SUCCESS 742 * \li ISC_R_UNEXPECTED 743 */ 744 745 isc_result_t 746 isc_socket_accept(isc_socket_t *sock, 747 isc_task_t *task, isc_taskaction_t action, void *arg); 748 /*%< 749 * Queue accept event. When a new connection is received, the task will 750 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen 751 * socket. The new socket structure is sent inside the isc_socket_newconnev_t 752 * event type, and is attached to the task 'task'. 753 * 754 * REQUIRES: 755 * \li 'socket' is a valid TCP socket that isc_socket_listen() was called 756 * on. 757 * 758 * \li 'task' is a valid task 759 * 760 * \li 'action' is a valid action 761 * 762 * RETURNS: 763 * \li ISC_R_SUCCESS 764 * \li ISC_R_NOMEMORY 765 * \li ISC_R_UNEXPECTED 766 */ 767 768 isc_result_t 769 isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp, 770 isc_task_t *task, isc_taskaction_t action, 771 void *arg); 772 /*%< 773 * Connect 'socket' to peer with address *saddr. When the connection 774 * succeeds, or when an error occurs, a CONNECT event with action 'action' 775 * and arg 'arg' will be posted to the event queue for 'task'. 776 * 777 * Requires: 778 * 779 * \li 'socket' is a valid TCP socket 780 * 781 * \li 'addressp' points to a valid isc_sockaddr 782 * 783 * \li 'task' is a valid task 784 * 785 * \li 'action' is a valid action 786 * 787 * Returns: 788 * 789 * \li ISC_R_SUCCESS 790 * \li ISC_R_NOMEMORY 791 * \li ISC_R_UNEXPECTED 792 * 793 * Posted event's result code: 794 * 795 * \li ISC_R_SUCCESS 796 * \li ISC_R_TIMEDOUT 797 * \li ISC_R_CONNREFUSED 798 * \li ISC_R_NETUNREACH 799 * \li ISC_R_UNEXPECTED 800 */ 801 802 isc_result_t 803 isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); 804 /*%< 805 * Get the name of the peer connected to 'socket'. 806 * 807 * Requires: 808 * 809 * \li 'socket' is a valid TCP socket. 810 * 811 * Returns: 812 * 813 * \li ISC_R_SUCCESS 814 * \li ISC_R_TOOSMALL 815 * \li ISC_R_UNEXPECTED 816 */ 817 818 isc_result_t 819 isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); 820 /*%< 821 * Get the name of 'socket'. 822 * 823 * Requires: 824 * 825 * \li 'socket' is a valid socket. 826 * 827 * Returns: 828 * 829 * \li ISC_R_SUCCESS 830 * \li ISC_R_TOOSMALL 831 * \li ISC_R_UNEXPECTED 832 */ 833 834 /*@{*/ 835 isc_result_t 836 isc_socket_recv(isc_socket_t *sock, isc_region_t *region, 837 unsigned int minimum, 838 isc_task_t *task, isc_taskaction_t action, void *arg); 839 isc_result_t 840 isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist, 841 unsigned int minimum, 842 isc_task_t *task, isc_taskaction_t action, void *arg); 843 844 isc_result_t 845 isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, 846 unsigned int minimum, isc_task_t *task, 847 isc_socketevent_t *event, unsigned int flags); 848 849 /*! 850 * Receive from 'socket', storing the results in region. 851 * 852 * Notes: 853 * 854 *\li Let 'length' refer to the length of 'region' or to the sum of all 855 * available regions in the list of buffers '*buflist'. 856 * 857 *\li If 'minimum' is non-zero and at least that many bytes are read, 858 * the completion event will be posted to the task 'task.' If minimum 859 * is zero, the exact number of bytes requested in the region must 860 * be read for an event to be posted. This only makes sense for TCP 861 * connections, and is always set to 1 byte for UDP. 862 * 863 *\li The read will complete when the desired number of bytes have been 864 * read, if end-of-input occurs, or if an error occurs. A read done 865 * event with the given 'action' and 'arg' will be posted to the 866 * event queue of 'task'. 867 * 868 *\li The caller may not modify 'region', the buffers which are passed 869 * into this function, or any data they refer to until the completion 870 * event is received. 871 * 872 *\li For isc_socket_recvv(): 873 * On successful completion, '*buflist' will be empty, and the list of 874 * all buffers will be returned in the done event's 'bufferlist' 875 * member. On error return, '*buflist' will be unchanged. 876 * 877 *\li For isc_socket_recv2(): 878 * 'event' is not NULL, and the non-socket specific fields are 879 * expected to be initialized. 880 * 881 *\li For isc_socket_recv2(): 882 * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If 883 * set and the operation completes, the return value will be 884 * ISC_R_SUCCESS and the event will be filled in and not sent. If the 885 * operation does not complete, the return value will be 886 * ISC_R_INPROGRESS and the event will be sent when the operation 887 * completes. 888 * 889 * Requires: 890 * 891 *\li 'socket' is a valid, bound socket. 892 * 893 *\li For isc_socket_recv(): 894 * 'region' is a valid region 895 * 896 *\li For isc_socket_recvv(): 897 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 898 * 899 *\li 'task' is a valid task 900 * 901 *\li For isc_socket_recv() and isc_socket_recvv(): 902 * action != NULL and is a valid action 903 * 904 *\li For isc_socket_recv2(): 905 * event != NULL 906 * 907 * Returns: 908 * 909 *\li #ISC_R_SUCCESS 910 *\li #ISC_R_INPROGRESS 911 *\li #ISC_R_NOMEMORY 912 *\li #ISC_R_UNEXPECTED 913 * 914 * Event results: 915 * 916 *\li #ISC_R_SUCCESS 917 *\li #ISC_R_UNEXPECTED 918 *\li XXX needs other net-type errors 919 */ 920 /*@}*/ 921 922 /*@{*/ 923 isc_result_t 924 isc_socket_send(isc_socket_t *sock, isc_region_t *region, 925 isc_task_t *task, isc_taskaction_t action, void *arg); 926 isc_result_t 927 isc_socket_sendto(isc_socket_t *sock, isc_region_t *region, 928 isc_task_t *task, isc_taskaction_t action, void *arg, 929 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 930 isc_result_t 931 isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist, 932 isc_task_t *task, isc_taskaction_t action, void *arg); 933 isc_result_t 934 isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist, 935 isc_task_t *task, isc_taskaction_t action, void *arg, 936 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 937 isc_result_t 938 isc_socket_sendtov2(isc_socket_t *sock, isc_bufferlist_t *buflist, 939 isc_task_t *task, isc_taskaction_t action, void *arg, 940 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 941 unsigned int flags); 942 isc_result_t 943 isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, 944 isc_task_t *task, 945 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 946 isc_socketevent_t *event, unsigned int flags); 947 948 /*! 949 * Send the contents of 'region' to the socket's peer. 950 * 951 * Notes: 952 * 953 *\li Shutting down the requestor's task *may* result in any 954 * still pending writes being dropped or completed, depending on the 955 * underlying OS implementation. 956 * 957 *\li If 'action' is NULL, then no completion event will be posted. 958 * 959 *\li The caller may not modify 'region', the buffers which are passed 960 * into this function, or any data they refer to until the completion 961 * event is received. 962 * 963 *\li For isc_socket_sendv() and isc_socket_sendtov(): 964 * On successful completion, '*buflist' will be empty, and the list of 965 * all buffers will be returned in the done event's 'bufferlist' 966 * member. On error return, '*buflist' will be unchanged. 967 * 968 *\li For isc_socket_sendto2(): 969 * 'event' is not NULL, and the non-socket specific fields are 970 * expected to be initialized. 971 * 972 *\li For isc_socket_sendto2(): 973 * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE 974 * and ISC_SOCKFLAG_NORETRY. 975 * 976 *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the 977 * return value will be ISC_R_SUCCESS and the event will be filled 978 * in and not sent. If the operation does not complete, the return 979 * value will be ISC_R_INPROGRESS and the event will be sent when 980 * the operation completes. 981 * 982 *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set 983 * and the send operation fails due to a transient error, the send 984 * will not be retried and the error will be indicated in the event. 985 * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller 986 * to specify a region that is allocated on the stack. 987 * 988 * Requires: 989 * 990 *\li 'socket' is a valid, bound socket. 991 * 992 *\li For isc_socket_send(): 993 * 'region' is a valid region 994 * 995 *\li For isc_socket_sendv() and isc_socket_sendtov(): 996 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 997 * 998 *\li 'task' is a valid task 999 * 1000 *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and 1001 * isc_socket_sendto(): 1002 * action == NULL or is a valid action 1003 * 1004 *\li For isc_socket_sendto2(): 1005 * event != NULL 1006 * 1007 * Returns: 1008 * 1009 *\li #ISC_R_SUCCESS 1010 *\li #ISC_R_INPROGRESS 1011 *\li #ISC_R_NOMEMORY 1012 *\li #ISC_R_UNEXPECTED 1013 * 1014 * Event results: 1015 * 1016 *\li #ISC_R_SUCCESS 1017 *\li #ISC_R_UNEXPECTED 1018 *\li XXX needs other net-type errors 1019 */ 1020 /*@}*/ 1021 1022 isc_result_t 1023 isc_socketmgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx, 1024 isc_socketmgr_t **managerp); 1025 1026 isc_result_t 1027 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); 1028 1029 isc_result_t 1030 isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp, 1031 unsigned int maxsocks); 1032 /*%< 1033 * Create a socket manager. If "maxsocks" is non-zero, it specifies the 1034 * maximum number of sockets that the created manager should handle. 1035 * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with 1036 * "maxsocks" being zero. 1037 * isc_socketmgr_createinctx() also associates the new manager with the 1038 * specified application context. 1039 * 1040 * Notes: 1041 * 1042 *\li All memory will be allocated in memory context 'mctx'. 1043 * 1044 * Requires: 1045 * 1046 *\li 'mctx' is a valid memory context. 1047 * 1048 *\li 'managerp' points to a NULL isc_socketmgr_t. 1049 * 1050 *\li 'actx' is a valid application context (for createinctx()). 1051 * 1052 * Ensures: 1053 * 1054 *\li '*managerp' is a valid isc_socketmgr_t. 1055 * 1056 * Returns: 1057 * 1058 *\li #ISC_R_SUCCESS 1059 *\li #ISC_R_NOMEMORY 1060 *\li #ISC_R_UNEXPECTED 1061 *\li #ISC_R_NOTIMPLEMENTED 1062 */ 1063 1064 isc_result_t 1065 isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp); 1066 /*%< 1067 * Returns in "*nsockp" the maximum number of sockets this manager may open. 1068 * 1069 * Requires: 1070 * 1071 *\li '*manager' is a valid isc_socketmgr_t. 1072 *\li 'nsockp' is not NULL. 1073 * 1074 * Returns: 1075 * 1076 *\li #ISC_R_SUCCESS 1077 *\li #ISC_R_NOTIMPLEMENTED 1078 */ 1079 1080 void 1081 isc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats); 1082 /*%< 1083 * Set a general socket statistics counter set 'stats' for 'manager'. 1084 * 1085 * Requires: 1086 * \li 'manager' is valid, hasn't opened any socket, and doesn't have 1087 * stats already set. 1088 * 1089 *\li stats is a valid statistics supporting socket statistics counters 1090 * (see above). 1091 */ 1092 1093 void 1094 isc_socketmgr_destroy(isc_socketmgr_t **managerp); 1095 /*%< 1096 * Destroy a socket manager. 1097 * 1098 * Notes: 1099 * 1100 *\li This routine blocks until there are no sockets left in the manager, 1101 * so if the caller holds any socket references using the manager, it 1102 * must detach them before calling isc_socketmgr_destroy() or it will 1103 * block forever. 1104 * 1105 * Requires: 1106 * 1107 *\li '*managerp' is a valid isc_socketmgr_t. 1108 * 1109 *\li All sockets managed by this manager are fully detached. 1110 * 1111 * Ensures: 1112 * 1113 *\li *managerp == NULL 1114 * 1115 *\li All resources used by the manager have been freed. 1116 */ 1117 1118 isc_sockettype_t 1119 isc_socket_gettype(isc_socket_t *sock); 1120 /*%< 1121 * Returns the socket type for "sock." 1122 * 1123 * Requires: 1124 * 1125 *\li "sock" is a valid socket. 1126 */ 1127 1128 /*@{*/ 1129 isc_boolean_t 1130 isc__socket_isbound(isc_socket_t *sock); 1131 /*% 1132 * Intended for internal use in BIND9 only 1133 */ 1134 1135 void 1136 isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes); 1137 /*%< 1138 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket 1139 * option if the host OS supports this option. 1140 * 1141 * Requires: 1142 *\li 'sock' is a valid socket. 1143 */ 1144 /*@}*/ 1145 1146 void 1147 isc_socket_dscp(isc_socket_t *sock, isc_dscp_t dscp); 1148 /*%< 1149 * Sets the Differentiated Services Code Point (DSCP) field for packets 1150 * transmitted on this socket. If 'dscp' is -1, return immediately. 1151 * 1152 * Requires: 1153 *\li 'sock' is a valid socket. 1154 */ 1155 1156 isc_socketevent_t * 1157 isc_socket_socketevent(isc_mem_t *mctx, void *sender, 1158 isc_eventtype_t eventtype, isc_taskaction_t action, 1159 void *arg); 1160 /*%< 1161 * Get a isc_socketevent_t to be used with isc_socket_sendto2(), etc. 1162 */ 1163 1164 void 1165 isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active); 1166 1167 /*%< 1168 * Cleanup UNIX domain sockets in the file-system. If 'active' is true 1169 * then just unlink the socket. If 'active' is false try to determine 1170 * if there is a listener of the socket or not. If no listener is found 1171 * then unlink socket. 1172 * 1173 * Prior to unlinking the path is tested to see if it a socket. 1174 * 1175 * Note: there are a number of race conditions which cannot be avoided 1176 * both in the filesystem and any application using UNIX domain 1177 * sockets (e.g. socket is tested between bind() and listen(), 1178 * the socket is deleted and replaced in the file-system between 1179 * stat() and unlink()). 1180 */ 1181 1182 isc_result_t 1183 isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm, 1184 isc_uint32_t owner, isc_uint32_t group); 1185 /*%< 1186 * Set ownership and file permissions on the UNIX domain socket. 1187 * 1188 * Note: On Solaris and SunOS this secures the directory containing 1189 * the socket as Solaris and SunOS do not honour the filesystem 1190 * permissions on the socket. 1191 * 1192 * Requires: 1193 * \li 'sockaddr' to be a valid UNIX domain sockaddr. 1194 * 1195 * Returns: 1196 * \li #ISC_R_SUCCESS 1197 * \li #ISC_R_FAILURE 1198 */ 1199 1200 void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag); 1201 /*%< 1202 * Set the name and optional tag for a socket. This allows tracking of the 1203 * owner or purpose for this socket, and is useful for tracing and statistics 1204 * reporting. 1205 */ 1206 1207 const char *isc_socket_getname(isc_socket_t *socket); 1208 /*%< 1209 * Get the name associated with a socket, if any. 1210 */ 1211 1212 void *isc_socket_gettag(isc_socket_t *socket); 1213 /*%< 1214 * Get the tag associated with a socket, if any. 1215 */ 1216 1217 int isc_socket_getfd(isc_socket_t *socket); 1218 /*%< 1219 * Get the file descriptor associated with a socket 1220 */ 1221 1222 void 1223 isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t); 1224 /*%< 1225 * Temporary. For use by named only. 1226 */ 1227 1228 void 1229 isc__socketmgr_maxudp(isc_socketmgr_t *mgr, int maxudp); 1230 /*%< 1231 * Test interface. Drop UDP packet > 'maxudp'. 1232 */ 1233 1234 #ifdef HAVE_LIBXML2 1235 int 1236 isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer); 1237 /*%< 1238 * Render internal statistics and other state into the XML document. 1239 */ 1240 #endif /* HAVE_LIBXML2 */ 1241 1242 #ifdef HAVE_JSON 1243 isc_result_t 1244 isc_socketmgr_renderjson(isc_socketmgr_t *mgr, json_object *stats); 1245 /*%< 1246 * Render internal statistics and other state into JSON format. 1247 */ 1248 #endif /* HAVE_JSON */ 1249 1250 /*%< 1251 * See isc_socketmgr_create() above. 1252 */ 1253 typedef isc_result_t 1254 (*isc_socketmgrcreatefunc_t)(isc_mem_t *mctx, isc_socketmgr_t **managerp); 1255 1256 isc_result_t 1257 isc_socket_register(isc_socketmgrcreatefunc_t createfunc); 1258 /*%< 1259 * Register a new socket I/O implementation and add it to the list of 1260 * supported implementations. This function must be called when a different 1261 * event library is used than the one contained in the ISC library. 1262 */ 1263 1264 isc_result_t 1265 isc__socket_register(void); 1266 /*%< 1267 * A short cut function that specifies the socket I/O module in the ISC 1268 * library for isc_socket_register(). An application that uses the ISC library 1269 * usually do not have to care about this function: it would call 1270 * isc_lib_register(), which internally calls this function. 1271 */ 1272 1273 ISC_LANG_ENDDECLS 1274 1275 #endif /* ISC_SOCKET_H */ 1276