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