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