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