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