1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #ifndef ISC_SOCKET_H 13 #define ISC_SOCKET_H 1 14 15 /***** 16 ***** Module Info 17 *****/ 18 19 /*! \file isc/socket.h 20 * \brief Provides TCP and UDP sockets for network I/O. The sockets are event 21 * sources in the task system. 22 * 23 * When I/O completes, a completion event for the socket is posted to the 24 * event queue of the task which requested the I/O. 25 * 26 * \li MP: 27 * The module ensures appropriate synchronization of data structures it 28 * creates and manipulates. 29 * Clients of this module must not be holding a socket's task's lock when 30 * making a call that affects that socket. Failure to follow this rule 31 * can result in deadlock. 32 * The caller must ensure that isc_socketmgr_destroy() is called only 33 * once for a given manager. 34 * 35 * \li Reliability: 36 * No anticipated impact. 37 * 38 * \li Resources: 39 * TBS 40 * 41 * \li Security: 42 * No anticipated impact. 43 * 44 * \li Standards: 45 * None. 46 */ 47 48 /*** 49 *** Imports 50 ***/ 51 52 #include <inttypes.h> 53 #include <stdbool.h> 54 55 #include <isc/event.h> 56 #include <isc/eventclass.h> 57 #include <isc/lang.h> 58 #include <isc/region.h> 59 #include <isc/sockaddr.h> 60 #include <isc/time.h> 61 #include <isc/types.h> 62 63 ISC_LANG_BEGINDECLS 64 65 /*** 66 *** Constants 67 ***/ 68 69 /*% 70 * Maximum number of buffers in a scatter/gather read/write. The operating 71 * system in use must support at least this number (plus one on some.) 72 */ 73 #define ISC_SOCKET_MAXSCATTERGATHER 8 74 75 /*@{*/ 76 /*! 77 * Socket options: 78 * 79 * _REUSEADDRESS: Set SO_REUSEADDR prior to calling bind(), 80 * if a non-zero port is specified (applies to 81 * AF_INET and AF_INET6). 82 */ 83 typedef enum { 84 ISC_SOCKET_REUSEADDRESS = 0x01U, 85 } isc_socket_options_t; 86 /*@}*/ 87 88 /*@{*/ 89 /*! 90 * _ATTACHED: Internal use only. 91 * _TRUNC: Packet was truncated on receive. 92 * _CTRUNC: Packet control information was truncated. This can 93 * indicate that the packet is not complete, even though 94 * all the data is valid. 95 * _TIMESTAMP: The timestamp member is valid. 96 * _PKTINFO: The pktinfo member is valid. 97 * _MULTICAST: The UDP packet was received via a multicast transmission. 98 * _DSCP: The UDP DSCP value is valid. 99 * _USEMINMTU: Set the per packet IPV6_USE_MIN_MTU flag. 100 */ 101 typedef enum { 102 ISC_SOCKEVENTATTR_ATTACHED = 0x10000000U, /* internal */ 103 ISC_SOCKEVENTATTR_TRUNC = 0x00800000U, /* public */ 104 ISC_SOCKEVENTATTR_CTRUNC = 0x00400000U, /* public */ 105 ISC_SOCKEVENTATTR_TIMESTAMP = 0x00200000U, /* public */ 106 ISC_SOCKEVENTATTR_PKTINFO = 0x00100000U, /* public */ 107 ISC_SOCKEVENTATTR_MULTICAST = 0x00080000U, /* public */ 108 ISC_SOCKEVENTATTR_DSCP = 0x00040000U, /* public */ 109 ISC_SOCKEVENTATTR_USEMINMTU = 0x00020000U /* public */ 110 } isc_sockeventattr_t; 111 /*@}*/ 112 113 /*** 114 *** Types 115 ***/ 116 117 struct isc_socketevent { 118 ISC_EVENT_COMMON(isc_socketevent_t); 119 isc_result_t result; /*%< OK, EOF, whatever else */ 120 unsigned int minimum; /*%< minimum i/o for event */ 121 unsigned int n; /*%< bytes read or written */ 122 unsigned int offset; /*%< offset into buffer list */ 123 isc_region_t region; /*%< for single-buffer i/o */ 124 isc_sockaddr_t address; /*%< source address */ 125 isc_time_t timestamp; /*%< timestamp of packet recv */ 126 struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ 127 isc_sockeventattr_t attributes; /*%< see isc_sockeventattr_t 128 * enum */ 129 isc_eventdestructor_t destroy; /*%< original destructor */ 130 unsigned int dscp; /*%< UDP dscp value */ 131 }; 132 133 typedef struct isc_socket_newconnev isc_socket_newconnev_t; 134 struct isc_socket_newconnev { 135 ISC_EVENT_COMMON(isc_socket_newconnev_t); 136 isc_socket_t * newsocket; 137 isc_result_t result; /*%< OK, EOF, whatever else */ 138 isc_sockaddr_t address; /*%< source address */ 139 }; 140 141 typedef struct isc_socket_connev isc_socket_connev_t; 142 struct isc_socket_connev { 143 ISC_EVENT_COMMON(isc_socket_connev_t); 144 isc_result_t result; /*%< OK, EOF, whatever else */ 145 }; 146 147 #define ISC_SOCKEVENT_ANYEVENT (0) 148 #define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) 149 #define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2) 150 #define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3) 151 #define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4) 152 153 /* 154 * Internal events. 155 */ 156 #define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256) 157 #define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257) 158 159 typedef enum { 160 isc_sockettype_udp = 1, 161 isc_sockettype_tcp = 2, 162 isc_sockettype_unix = 3, 163 isc_sockettype_raw = 4 164 } isc_sockettype_t; 165 166 /*@{*/ 167 /*! 168 * How a socket should be shutdown in isc_socket_shutdown() calls. 169 */ 170 #define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ 171 #define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ 172 #define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ 173 /*@}*/ 174 175 /*@{*/ 176 /*! 177 * What I/O events to cancel in isc_socket_cancel() calls. 178 */ 179 #define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ 180 #define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ 181 #define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ 182 #define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ 183 #define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ 184 /*@}*/ 185 186 /*@{*/ 187 /*! 188 * Flags for isc_socket_send() and isc_socket_recv() calls. 189 */ 190 #define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ 191 #define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ 192 /*@}*/ 193 194 /*% 195 * This structure is actually just the common prefix of a socket manager 196 * object implementation's version of an isc_socketmgr_t. 197 * \brief 198 * Direct use of this structure by clients is forbidden. socket implementations 199 * may change the structure. 'magic' must be ISCAPI_SOCKETMGR_MAGIC for any 200 * of the isc_socket_ routines to work. socket implementations must maintain 201 * all socket invariants. 202 * In effect, this definition is used only for non-BIND9 version ("export") 203 * of the library, and the export version does not work for win32. So, to avoid 204 * the definition conflict with win32/socket.c, we enable this definition only 205 * for non-Win32 (i.e. Unix) platforms. 206 */ 207 #ifndef WIN32 208 struct isc_socketmgr { 209 unsigned int impmagic; 210 unsigned int magic; 211 }; 212 #endif /* ifndef WIN32 */ 213 214 #define ISCAPI_SOCKETMGR_MAGIC ISC_MAGIC('A', 's', 'm', 'g') 215 #define ISCAPI_SOCKETMGR_VALID(m) \ 216 ((m) != NULL && (m)->magic == ISCAPI_SOCKETMGR_MAGIC) 217 218 /*% 219 * This is the common prefix of a socket object. The same note as 220 * that for the socketmgr structure applies. 221 */ 222 #ifndef WIN32 223 struct isc_socket { 224 unsigned int impmagic; 225 unsigned int magic; 226 }; 227 #endif /* ifndef WIN32 */ 228 229 #define ISCAPI_SOCKET_MAGIC ISC_MAGIC('A', 's', 'c', 't') 230 #define ISCAPI_SOCKET_VALID(s) \ 231 ((s) != NULL && (s)->magic == ISCAPI_SOCKET_MAGIC) 232 233 /*** 234 *** Socket and Socket Manager Functions 235 *** 236 *** Note: all Ensures conditions apply only if the result is success for 237 *** those functions which return an isc_result. 238 ***/ 239 240 isc_result_t 241 isc_socket_create(isc_socketmgr_t *manager, int pf, isc_sockettype_t type, 242 isc_socket_t **socketp); 243 /*%< 244 * Create a new 'type' socket managed by 'manager'. 245 * 246 * Note: 247 * 248 *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. 249 * 250 * Requires: 251 * 252 *\li 'manager' is a valid manager 253 * 254 *\li 'socketp' is a valid pointer, and *socketp == NULL 255 * 256 * Ensures: 257 * 258 * '*socketp' is attached to the newly created socket 259 * 260 * Returns: 261 * 262 *\li #ISC_R_SUCCESS 263 *\li #ISC_R_NOMEMORY 264 *\li #ISC_R_NORESOURCES 265 *\li #ISC_R_UNEXPECTED 266 */ 267 268 isc_result_t 269 isc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp); 270 /*%< 271 * Duplicate an existing socket, reusing its file descriptor. 272 */ 273 274 void 275 isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, unsigned int how); 276 /*%< 277 * Cancel pending I/O of the type specified by "how". 278 * 279 * Note: if "task" is NULL, then the cancel applies to all tasks using the 280 * socket. 281 * 282 * Requires: 283 * 284 * \li "socket" is a valid socket 285 * 286 * \li "task" is NULL or a valid task 287 * 288 * "how" is a bitmask describing the type of cancellation to perform. 289 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this 290 * socket. 291 * 292 * \li ISC_SOCKCANCEL_RECV: 293 * Cancel pending isc_socket_recv() calls. 294 * 295 * \li ISC_SOCKCANCEL_SEND: 296 * Cancel pending isc_socket_send() and isc_socket_sendto() calls. 297 * 298 * \li ISC_SOCKCANCEL_ACCEPT: 299 * Cancel pending isc_socket_accept() calls. 300 * 301 * \li ISC_SOCKCANCEL_CONNECT: 302 * Cancel pending isc_socket_connect() call. 303 */ 304 305 void 306 isc_socket_shutdown(isc_socket_t *sock, unsigned int how); 307 /*%< 308 * Shutdown 'socket' according to 'how'. 309 * 310 * Requires: 311 * 312 * \li 'socket' is a valid socket. 313 * 314 * \li 'task' is NULL or is a valid task. 315 * 316 * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then 317 * 318 * The read queue must be empty. 319 * 320 * No further read requests may be made. 321 * 322 * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then 323 * 324 * The write queue must be empty. 325 * 326 * No further write requests may be made. 327 */ 328 329 void 330 isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); 331 /*%< 332 * Attach *socketp to socket. 333 * 334 * Requires: 335 * 336 * \li 'socket' is a valid socket. 337 * 338 * \li 'socketp' points to a NULL socket. 339 * 340 * Ensures: 341 * 342 * \li *socketp is attached to socket. 343 */ 344 345 void 346 isc_socket_detach(isc_socket_t **socketp); 347 /*%< 348 * Detach *socketp from its socket. 349 * 350 * Requires: 351 * 352 * \li 'socketp' points to a valid socket. 353 * 354 * \li If '*socketp' is the last reference to the socket, 355 * then: 356 * 357 * There must be no pending I/O requests. 358 * 359 * Ensures: 360 * 361 * \li *socketp is NULL. 362 * 363 * \li If '*socketp' is the last reference to the socket, 364 * then: 365 * 366 * The socket will be shutdown (both reading and writing) 367 * for all tasks. 368 * 369 * All resources used by the socket have been freed 370 */ 371 372 isc_result_t 373 isc_socket_open(isc_socket_t *sock); 374 /*%< 375 * Open a new socket file descriptor of the given socket structure. It simply 376 * opens a new descriptor; all of the other parameters including the socket 377 * type are inherited from the existing socket. This function is provided to 378 * avoid overhead of destroying and creating sockets when many short-lived 379 * sockets are frequently opened and closed. When the efficiency is not an 380 * issue, it should be safer to detach the unused socket and re-create a new 381 * one. This optimization may not be available for some systems, in which 382 * case this function will return ISC_R_NOTIMPLEMENTED and must not be used. 383 * 384 * Requires: 385 * 386 * \li there must be no other reference to this socket. 387 * 388 * \li 'socket' is a valid and previously closed by isc_socket_close() 389 * 390 * Returns: 391 * Same as isc_socket_create(). 392 * \li ISC_R_NOTIMPLEMENTED 393 */ 394 395 isc_result_t 396 isc_socket_close(isc_socket_t *sock); 397 /*%< 398 * Close a socket file descriptor of the given socket structure. This function 399 * is provided as an alternative to destroying an unused socket when overhead 400 * destroying/re-creating sockets can be significant, and is expected to be 401 * used with isc_socket_open(). This optimization may not be available for some 402 * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and 403 * must not be used. 404 * 405 * Requires: 406 * 407 * \li The socket must have a valid descriptor. 408 * 409 * \li There must be no other reference to this socket. 410 * 411 * \li There must be no pending I/O requests. 412 * 413 * Returns: 414 * \li #ISC_R_NOTIMPLEMENTED 415 */ 416 417 isc_result_t 418 isc_socket_bind(isc_socket_t *sock, const isc_sockaddr_t *addressp, 419 isc_socket_options_t options); 420 /*%< 421 * Bind 'socket' to '*addressp'. 422 * 423 * Requires: 424 * 425 * \li 'socket' is a valid socket 426 * 427 * \li 'addressp' points to a valid isc_sockaddr. 428 * 429 * Returns: 430 * 431 * \li ISC_R_SUCCESS 432 * \li ISC_R_NOPERM 433 * \li ISC_R_ADDRNOTAVAIL 434 * \li ISC_R_ADDRINUSE 435 * \li ISC_R_BOUND 436 * \li ISC_R_UNEXPECTED 437 */ 438 439 isc_result_t 440 isc_socket_filter(isc_socket_t *sock, const char *filter); 441 /*%< 442 * Inform the kernel that it should perform accept filtering. 443 * If filter is NULL the current filter will be removed. 444 */ 445 446 isc_result_t 447 isc_socket_listen(isc_socket_t *sock, unsigned int backlog); 448 /*%< 449 * Set listen mode on the socket. After this call, the only function that 450 * can be used (other than attach and detach) is isc_socket_accept(). 451 * 452 * Notes: 453 * 454 * \li 'backlog' is as in the UNIX system call listen() and may be 455 * ignored by non-UNIX implementations. 456 * 457 * \li If 'backlog' is zero, a reasonable system default is used, usually 458 * SOMAXCONN. 459 * 460 * Requires: 461 * 462 * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. 463 * 464 * Returns: 465 * 466 * \li ISC_R_SUCCESS 467 * \li ISC_R_UNEXPECTED 468 */ 469 470 isc_result_t 471 isc_socket_accept(isc_socket_t *sock, isc_task_t *task, isc_taskaction_t action, 472 void *arg); 473 /*%< 474 * Queue accept event. When a new connection is received, the task will 475 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen 476 * socket. The new socket structure is sent inside the isc_socket_newconnev_t 477 * event type, and is attached to the task 'task'. 478 * 479 * REQUIRES: 480 * \li 'socket' is a valid TCP socket that isc_socket_listen() was called 481 * on. 482 * 483 * \li 'task' is a valid task 484 * 485 * \li 'action' is a valid action 486 * 487 * RETURNS: 488 * \li ISC_R_SUCCESS 489 * \li ISC_R_NOMEMORY 490 * \li ISC_R_UNEXPECTED 491 */ 492 493 isc_result_t 494 isc_socket_connect(isc_socket_t *sock, const isc_sockaddr_t *addressp, 495 isc_task_t *task, isc_taskaction_t action, void *arg); 496 /*%< 497 * Connect 'socket' to peer with address *saddr. When the connection 498 * succeeds, or when an error occurs, a CONNECT event with action 'action' 499 * and arg 'arg' will be posted to the event queue for 'task'. 500 * 501 * Requires: 502 * 503 * \li 'socket' is a valid TCP socket 504 * 505 * \li 'addressp' points to a valid isc_sockaddr 506 * 507 * \li 'task' is a valid task 508 * 509 * \li 'action' is a valid action 510 * 511 * Returns: 512 * 513 * \li ISC_R_SUCCESS 514 * \li ISC_R_NOMEMORY 515 * \li ISC_R_UNEXPECTED 516 * 517 * Posted event's result code: 518 * 519 * \li ISC_R_SUCCESS 520 * \li ISC_R_TIMEDOUT 521 * \li ISC_R_CONNREFUSED 522 * \li ISC_R_NETUNREACH 523 * \li ISC_R_UNEXPECTED 524 */ 525 526 isc_result_t 527 isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); 528 /*%< 529 * Get the name of the peer connected to 'socket'. 530 * 531 * Requires: 532 * 533 * \li 'socket' is a valid TCP socket. 534 * 535 * Returns: 536 * 537 * \li ISC_R_SUCCESS 538 * \li ISC_R_TOOSMALL 539 * \li ISC_R_UNEXPECTED 540 */ 541 542 isc_result_t 543 isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); 544 /*%< 545 * Get the name of 'socket'. 546 * 547 * Requires: 548 * 549 * \li 'socket' is a valid socket. 550 * 551 * Returns: 552 * 553 * \li ISC_R_SUCCESS 554 * \li ISC_R_TOOSMALL 555 * \li ISC_R_UNEXPECTED 556 */ 557 558 /*@{*/ 559 isc_result_t 560 isc_socket_recv(isc_socket_t *sock, isc_region_t *region, unsigned int minimum, 561 isc_task_t *task, isc_taskaction_t action, void *arg); 562 563 isc_result_t 564 isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, unsigned int minimum, 565 isc_task_t *task, isc_socketevent_t *event, 566 unsigned int flags); 567 568 /*! 569 * Receive from 'socket', storing the results in region. 570 * 571 * Notes: 572 * 573 *\li Let 'length' refer to the length of 'region' or to the sum of all 574 * available regions in the list of buffers '*buflist'. 575 * 576 *\li If 'minimum' is non-zero and at least that many bytes are read, 577 * the completion event will be posted to the task 'task.' If minimum 578 * is zero, the exact number of bytes requested in the region must 579 * be read for an event to be posted. This only makes sense for TCP 580 * connections, and is always set to 1 byte for UDP. 581 * 582 *\li The read will complete when the desired number of bytes have been 583 * read, if end-of-input occurs, or if an error occurs. A read done 584 * event with the given 'action' and 'arg' will be posted to the 585 * event queue of 'task'. 586 * 587 *\li The caller may not modify 'region', the buffers which are passed 588 * into this function, or any data they refer to until the completion 589 * event is received. 590 * 591 *\li For isc_socket_recv2(): 592 * 'event' is not NULL, and the non-socket specific fields are 593 * expected to be initialized. 594 * 595 *\li For isc_socket_recv2(): 596 * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If 597 * set and the operation completes, the return value will be 598 * ISC_R_SUCCESS and the event will be filled in and not sent. If the 599 * operation does not complete, the return value will be 600 * ISC_R_INPROGRESS and the event will be sent when the operation 601 * completes. 602 * 603 * Requires: 604 * 605 *\li 'socket' is a valid, bound socket. 606 * 607 *\li For isc_socket_recv(): 608 * 'region' is a valid region 609 * 610 *\li For isc_socket_recvv(): 611 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 612 * 613 *\li 'task' is a valid task 614 * 615 *\li For isc_socket_recv() and isc_socket_recvv(): 616 * action != NULL and is a valid action 617 * 618 *\li For isc_socket_recv2(): 619 * event != NULL 620 * 621 * Returns: 622 * 623 *\li #ISC_R_SUCCESS 624 *\li #ISC_R_INPROGRESS 625 *\li #ISC_R_NOMEMORY 626 *\li #ISC_R_UNEXPECTED 627 * 628 * Event results: 629 * 630 *\li #ISC_R_SUCCESS 631 *\li #ISC_R_UNEXPECTED 632 *\li XXX needs other net-type errors 633 */ 634 /*@}*/ 635 636 /*@{*/ 637 isc_result_t 638 isc_socket_send(isc_socket_t *sock, isc_region_t *region, isc_task_t *task, 639 isc_taskaction_t action, void *arg); 640 isc_result_t 641 isc_socket_sendto(isc_socket_t *sock, isc_region_t *region, isc_task_t *task, 642 isc_taskaction_t action, void *arg, 643 const isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 644 isc_result_t 645 isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, isc_task_t *task, 646 const isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 647 isc_socketevent_t *event, unsigned int flags); 648 649 /*! 650 * Send the contents of 'region' to the socket's peer. 651 * 652 * Notes: 653 * 654 *\li Shutting down the requestor's task *may* result in any 655 * still pending writes being dropped or completed, depending on the 656 * underlying OS implementation. 657 * 658 *\li If 'action' is NULL, then no completion event will be posted. 659 * 660 *\li The caller may not modify 'region', the buffers which are passed 661 * into this function, or any data they refer to until the completion 662 * event is received. 663 * 664 *\li For isc_socket_sendto2(): 665 * 'event' is not NULL, and the non-socket specific fields are 666 * expected to be initialized. 667 * 668 *\li For isc_socket_sendto2(): 669 * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE 670 * and ISC_SOCKFLAG_NORETRY. 671 * 672 *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the 673 * return value will be ISC_R_SUCCESS and the event will be filled 674 * in and not sent. If the operation does not complete, the return 675 * value will be ISC_R_INPROGRESS and the event will be sent when 676 * the operation completes. 677 * 678 *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set 679 * and the send operation fails due to a transient error, the send 680 * will not be retried and the error will be indicated in the event. 681 * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller 682 * to specify a region that is allocated on the stack. 683 * 684 * Requires: 685 * 686 *\li 'socket' is a valid, bound socket. 687 * 688 *\li For isc_socket_send(): 689 * 'region' is a valid region 690 * 691 *\li For isc_socket_sendv() and isc_socket_sendtov(): 692 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 693 * 694 *\li 'task' is a valid task 695 * 696 *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and 697 * isc_socket_sendto(): 698 * action == NULL or is a valid action 699 * 700 *\li For isc_socket_sendto2(): 701 * event != NULL 702 * 703 * Returns: 704 * 705 *\li #ISC_R_SUCCESS 706 *\li #ISC_R_INPROGRESS 707 *\li #ISC_R_NOMEMORY 708 *\li #ISC_R_UNEXPECTED 709 * 710 * Event results: 711 * 712 *\li #ISC_R_SUCCESS 713 *\li #ISC_R_UNEXPECTED 714 *\li XXX needs other net-type errors 715 */ 716 /*@}*/ 717 718 isc_result_t 719 isc_socketmgr_createinctx(isc_mem_t *mctx, isc_socketmgr_t **managerp); 720 721 isc_result_t 722 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); 723 724 isc_result_t 725 isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp, 726 unsigned int maxsocks, int nthreads); 727 /*%< 728 * Create a socket manager. If "maxsocks" is non-zero, it specifies the 729 * maximum number of sockets that the created manager should handle. 730 * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with 731 * "maxsocks" being zero. 732 * isc_socketmgr_createinctx() also associates the new manager with the 733 * specified application context. 734 * 735 * Notes: 736 * 737 *\li All memory will be allocated in memory context 'mctx'. 738 * 739 * Requires: 740 * 741 *\li 'mctx' is a valid memory context. 742 * 743 *\li 'managerp' points to a NULL isc_socketmgr_t. 744 * 745 *\li 'actx' is a valid application context (for createinctx()). 746 * 747 * Ensures: 748 * 749 *\li '*managerp' is a valid isc_socketmgr_t. 750 * 751 * Returns: 752 * 753 *\li #ISC_R_SUCCESS 754 *\li #ISC_R_NOMEMORY 755 *\li #ISC_R_UNEXPECTED 756 *\li #ISC_R_NOTIMPLEMENTED 757 */ 758 759 isc_result_t 760 isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp); 761 /*%< 762 * Returns in "*nsockp" the maximum number of sockets this manager may open. 763 * 764 * Requires: 765 * 766 *\li '*manager' is a valid isc_socketmgr_t. 767 *\li 'nsockp' is not NULL. 768 * 769 * Returns: 770 * 771 *\li #ISC_R_SUCCESS 772 *\li #ISC_R_NOTIMPLEMENTED 773 */ 774 775 void 776 isc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats); 777 /*%< 778 * Set a general socket statistics counter set 'stats' for 'manager'. 779 * 780 * Requires: 781 * \li 'manager' is valid, hasn't opened any socket, and doesn't have 782 * stats already set. 783 * 784 *\li stats is a valid statistics supporting socket statistics counters 785 * (see above). 786 */ 787 788 void 789 isc_socketmgr_destroy(isc_socketmgr_t **managerp); 790 /*%< 791 * Destroy a socket manager. 792 * 793 * Notes: 794 * 795 *\li This routine blocks until there are no sockets left in the manager, 796 * so if the caller holds any socket references using the manager, it 797 * must detach them before calling isc_socketmgr_destroy() or it will 798 * block forever. 799 * 800 * Requires: 801 * 802 *\li '*managerp' is a valid isc_socketmgr_t. 803 * 804 *\li All sockets managed by this manager are fully detached. 805 * 806 * Ensures: 807 * 808 *\li *managerp == NULL 809 * 810 *\li All resources used by the manager have been freed. 811 */ 812 813 isc_sockettype_t 814 isc_socket_gettype(isc_socket_t *sock); 815 /*%< 816 * Returns the socket type for "sock." 817 * 818 * Requires: 819 * 820 *\li "sock" is a valid socket. 821 */ 822 823 /*@{*/ 824 void 825 isc_socket_ipv6only(isc_socket_t *sock, bool yes); 826 /*%< 827 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket 828 * option if the host OS supports this option. 829 * 830 * Requires: 831 *\li 'sock' is a valid socket. 832 */ 833 /*@}*/ 834 835 void 836 isc_socket_dscp(isc_socket_t *sock, isc_dscp_t dscp); 837 /*%< 838 * Sets the Differentiated Services Code Point (DSCP) field for packets 839 * transmitted on this socket. If 'dscp' is -1, return immediately. 840 * 841 * Requires: 842 *\li 'sock' is a valid socket. 843 */ 844 845 isc_socketevent_t * 846 isc_socket_socketevent(isc_mem_t *mctx, void *sender, isc_eventtype_t eventtype, 847 isc_taskaction_t action, void *arg); 848 /*%< 849 * Get a isc_socketevent_t to be used with isc_socket_sendto2(), etc. 850 */ 851 852 void 853 isc_socket_cleanunix(const isc_sockaddr_t *addr, bool active); 854 855 /*%< 856 * Cleanup UNIX domain sockets in the file-system. If 'active' is true 857 * then just unlink the socket. If 'active' is false try to determine 858 * if there is a listener of the socket or not. If no listener is found 859 * then unlink socket. 860 * 861 * Prior to unlinking the path is tested to see if it a socket. 862 * 863 * Note: there are a number of race conditions which cannot be avoided 864 * both in the filesystem and any application using UNIX domain 865 * sockets (e.g. socket is tested between bind() and listen(), 866 * the socket is deleted and replaced in the file-system between 867 * stat() and unlink()). 868 */ 869 870 isc_result_t 871 isc_socket_permunix(const isc_sockaddr_t *sockaddr, uint32_t perm, 872 uint32_t owner, uint32_t group); 873 /*%< 874 * Set ownership and file permissions on the UNIX domain socket. 875 * 876 * Note: On Solaris this secures the directory containing 877 * the socket as Solaris do not honour the filesystem 878 * permissions on the socket. 879 * 880 * Requires: 881 * \li 'sockaddr' to be a valid UNIX domain sockaddr. 882 * 883 * Returns: 884 * \li #ISC_R_SUCCESS 885 * \li #ISC_R_FAILURE 886 */ 887 888 void 889 isc_socket_setname(isc_socket_t *socket, const char *name, void *tag); 890 /*%< 891 * Set the name and optional tag for a socket. This allows tracking of the 892 * owner or purpose for this socket, and is useful for tracing and statistics 893 * reporting. 894 */ 895 896 const char * 897 isc_socket_getname(isc_socket_t *socket); 898 /*%< 899 * Get the name associated with a socket, if any. 900 */ 901 902 void * 903 isc_socket_gettag(isc_socket_t *socket); 904 /*%< 905 * Get the tag associated with a socket, if any. 906 */ 907 908 int 909 isc_socket_getfd(isc_socket_t *socket); 910 /*%< 911 * Get the file descriptor associated with a socket 912 */ 913 914 void 915 isc_socketmgr_setreserved(isc_socketmgr_t *mgr, uint32_t); 916 /*%< 917 * Temporary. For use by named only. 918 */ 919 920 void 921 isc_socketmgr_maxudp(isc_socketmgr_t *mgr, unsigned int maxudp); 922 /*%< 923 * Test interface. Drop UDP packet > 'maxudp'. 924 */ 925 926 bool 927 isc_socket_hasreuseport(void); 928 /*%< 929 * Return true if there is SO_REUSEPORT support 930 */ 931 932 #ifdef HAVE_LIBXML2 933 int 934 isc_socketmgr_renderxml(isc_socketmgr_t *mgr, void *writer0); 935 /*%< 936 * Render internal statistics and other state into the XML document. 937 */ 938 #endif /* HAVE_LIBXML2 */ 939 940 #ifdef HAVE_JSON_C 941 isc_result_t 942 isc_socketmgr_renderjson(isc_socketmgr_t *mgr, void *stats0); 943 /*%< 944 * Render internal statistics and other state into JSON format. 945 */ 946 #endif /* HAVE_JSON_C */ 947 948 /*%< 949 * See isc_socketmgr_create() above. 950 */ 951 typedef isc_result_t (*isc_socketmgrcreatefunc_t)(isc_mem_t * mctx, 952 isc_socketmgr_t **managerp); 953 954 ISC_LANG_ENDDECLS 955 956 #endif /* ISC_SOCKET_H */ 957