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