socket.h revision 170222
1/* 2 * Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 1998-2002 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and 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.6 2006/06/07 00:29:45 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 *** Types 82 ***/ 83 84struct isc_socketevent { 85 ISC_EVENT_COMMON(isc_socketevent_t); 86 isc_result_t result; /*%< OK, EOF, whatever else */ 87 unsigned int minimum; /*%< minimum i/o for event */ 88 unsigned int n; /*%< bytes read or written */ 89 unsigned int offset; /*%< offset into buffer list */ 90 isc_region_t region; /*%< for single-buffer i/o */ 91 isc_bufferlist_t bufferlist; /*%< list of buffers */ 92 isc_sockaddr_t address; /*%< source address */ 93 isc_time_t timestamp; /*%< timestamp of packet recv */ 94 struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ 95 isc_uint32_t attributes; /*%< see below */ 96 isc_eventdestructor_t destroy; /*%< original destructor */ 97}; 98 99typedef struct isc_socket_newconnev isc_socket_newconnev_t; 100struct isc_socket_newconnev { 101 ISC_EVENT_COMMON(isc_socket_newconnev_t); 102 isc_socket_t * newsocket; 103 isc_result_t result; /*%< OK, EOF, whatever else */ 104 isc_sockaddr_t address; /*%< source address */ 105}; 106 107typedef struct isc_socket_connev isc_socket_connev_t; 108struct isc_socket_connev { 109 ISC_EVENT_COMMON(isc_socket_connev_t); 110 isc_result_t result; /*%< OK, EOF, whatever else */ 111}; 112 113/*@{*/ 114/*! 115 * _ATTACHED: Internal use only. 116 * _TRUNC: Packet was truncated on receive. 117 * _CTRUNC: Packet control information was truncated. This can 118 * indicate that the packet is not complete, even though 119 * all the data is valid. 120 * _TIMESTAMP: The timestamp member is valid. 121 * _PKTINFO: The pktinfo member is valid. 122 * _MULTICAST: The UDP packet was received via a multicast transmission. 123 */ 124#define ISC_SOCKEVENTATTR_ATTACHED 0x80000000U /* internal */ 125#define ISC_SOCKEVENTATTR_TRUNC 0x00800000U /* public */ 126#define ISC_SOCKEVENTATTR_CTRUNC 0x00400000U /* public */ 127#define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */ 128#define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */ 129#define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */ 130/*@}*/ 131 132#define ISC_SOCKEVENT_ANYEVENT (0) 133#define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) 134#define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2) 135#define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3) 136#define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4) 137 138/* 139 * Internal events. 140 */ 141#define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256) 142#define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257) 143 144typedef enum { 145 isc_sockettype_udp = 1, 146 isc_sockettype_tcp = 2, 147 isc_sockettype_unix = 3 148} isc_sockettype_t; 149 150/*@{*/ 151/*! 152 * How a socket should be shutdown in isc_socket_shutdown() calls. 153 */ 154#define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ 155#define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ 156#define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ 157/*@}*/ 158 159/*@{*/ 160/*! 161 * What I/O events to cancel in isc_socket_cancel() calls. 162 */ 163#define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ 164#define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ 165#define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ 166#define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ 167#define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ 168/*@}*/ 169 170/*@{*/ 171/*! 172 * Flags for isc_socket_send() and isc_socket_recv() calls. 173 */ 174#define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ 175#define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ 176/*@}*/ 177 178/*** 179 *** Socket and Socket Manager Functions 180 *** 181 *** Note: all Ensures conditions apply only if the result is success for 182 *** those functions which return an isc_result. 183 ***/ 184 185isc_result_t 186isc_socket_create(isc_socketmgr_t *manager, 187 int pf, 188 isc_sockettype_t type, 189 isc_socket_t **socketp); 190/*%< 191 * Create a new 'type' socket managed by 'manager'. 192 * 193 * Note: 194 * 195 *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. 196 * 197 * Requires: 198 * 199 *\li 'manager' is a valid manager 200 * 201 *\li 'socketp' is a valid pointer, and *socketp == NULL 202 * 203 * Ensures: 204 * 205 * '*socketp' is attached to the newly created socket 206 * 207 * Returns: 208 * 209 *\li #ISC_R_SUCCESS 210 *\li #ISC_R_NOMEMORY 211 *\li #ISC_R_NORESOURCES 212 *\li #ISC_R_UNEXPECTED 213 */ 214 215void 216isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, 217 unsigned int how); 218/*%< 219 * Cancel pending I/O of the type specified by "how". 220 * 221 * Note: if "task" is NULL, then the cancel applies to all tasks using the 222 * socket. 223 * 224 * Requires: 225 * 226 * \li "socket" is a valid socket 227 * 228 * \li "task" is NULL or a valid task 229 * 230 * "how" is a bitmask describing the type of cancelation to perform. 231 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this 232 * socket. 233 * 234 * \li ISC_SOCKCANCEL_RECV: 235 * Cancel pending isc_socket_recv() calls. 236 * 237 * \li ISC_SOCKCANCEL_SEND: 238 * Cancel pending isc_socket_send() and isc_socket_sendto() calls. 239 * 240 * \li ISC_SOCKCANCEL_ACCEPT: 241 * Cancel pending isc_socket_accept() calls. 242 * 243 * \li ISC_SOCKCANCEL_CONNECT: 244 * Cancel pending isc_socket_connect() call. 245 */ 246 247void 248isc_socket_shutdown(isc_socket_t *sock, unsigned int how); 249/*%< 250 * Shutdown 'socket' according to 'how'. 251 * 252 * Requires: 253 * 254 * \li 'socket' is a valid socket. 255 * 256 * \li 'task' is NULL or is a valid task. 257 * 258 * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then 259 * 260 * The read queue must be empty. 261 * 262 * No further read requests may be made. 263 * 264 * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then 265 * 266 * The write queue must be empty. 267 * 268 * No further write requests may be made. 269 */ 270 271void 272isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); 273/*%< 274 * Attach *socketp to socket. 275 * 276 * Requires: 277 * 278 * \li 'socket' is a valid socket. 279 * 280 * \li 'socketp' points to a NULL socket. 281 * 282 * Ensures: 283 * 284 * \li *socketp is attached to socket. 285 */ 286 287void 288isc_socket_detach(isc_socket_t **socketp); 289/*%< 290 * Detach *socketp from its socket. 291 * 292 * Requires: 293 * 294 * \li 'socketp' points to a valid socket. 295 * 296 * \li If '*socketp' is the last reference to the socket, 297 * then: 298 * 299 * There must be no pending I/O requests. 300 * 301 * Ensures: 302 * 303 * \li *socketp is NULL. 304 * 305 * \li If '*socketp' is the last reference to the socket, 306 * then: 307 * 308 * The socket will be shutdown (both reading and writing) 309 * for all tasks. 310 * 311 * All resources used by the socket have been freed 312 */ 313 314isc_result_t 315isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp); 316/*%< 317 * Bind 'socket' to '*addressp'. 318 * 319 * Requires: 320 * 321 * \li 'socket' is a valid socket 322 * 323 * \li 'addressp' points to a valid isc_sockaddr. 324 * 325 * Returns: 326 * 327 * \li ISC_R_SUCCESS 328 * \li ISC_R_NOPERM 329 * \li ISC_R_ADDRNOTAVAIL 330 * \li ISC_R_ADDRINUSE 331 * \li ISC_R_BOUND 332 * \li ISC_R_UNEXPECTED 333 */ 334 335isc_result_t 336isc_socket_filter(isc_socket_t *sock, const char *filter); 337/*%< 338 * Inform the kernel that it should perform accept filtering. 339 * If filter is NULL the current filter will be removed.:w 340 */ 341 342isc_result_t 343isc_socket_listen(isc_socket_t *sock, unsigned int backlog); 344/*%< 345 * Set listen mode on the socket. After this call, the only function that 346 * can be used (other than attach and detach) is isc_socket_accept(). 347 * 348 * Notes: 349 * 350 * \li 'backlog' is as in the UNIX system call listen() and may be 351 * ignored by non-UNIX implementations. 352 * 353 * \li If 'backlog' is zero, a reasonable system default is used, usually 354 * SOMAXCONN. 355 * 356 * Requires: 357 * 358 * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. 359 * 360 * Returns: 361 * 362 * \li ISC_R_SUCCESS 363 * \li ISC_R_UNEXPECTED 364 */ 365 366isc_result_t 367isc_socket_accept(isc_socket_t *sock, 368 isc_task_t *task, isc_taskaction_t action, const void *arg); 369/*%< 370 * Queue accept event. When a new connection is received, the task will 371 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen 372 * socket. The new socket structure is sent inside the isc_socket_newconnev_t 373 * event type, and is attached to the task 'task'. 374 * 375 * REQUIRES: 376 * \li 'socket' is a valid TCP socket that isc_socket_listen() was called 377 * on. 378 * 379 * \li 'task' is a valid task 380 * 381 * \li 'action' is a valid action 382 * 383 * RETURNS: 384 * \li ISC_R_SUCCESS 385 * \li ISC_R_NOMEMORY 386 * \li ISC_R_UNEXPECTED 387 */ 388 389isc_result_t 390isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp, 391 isc_task_t *task, isc_taskaction_t action, 392 const void *arg); 393/*%< 394 * Connect 'socket' to peer with address *saddr. When the connection 395 * succeeds, or when an error occurs, a CONNECT event with action 'action' 396 * and arg 'arg' will be posted to the event queue for 'task'. 397 * 398 * Requires: 399 * 400 * \li 'socket' is a valid TCP socket 401 * 402 * \li 'addressp' points to a valid isc_sockaddr 403 * 404 * \li 'task' is a valid task 405 * 406 * \li 'action' is a valid action 407 * 408 * Returns: 409 * 410 * \li ISC_R_SUCCESS 411 * \li ISC_R_NOMEMORY 412 * \li ISC_R_UNEXPECTED 413 * 414 * Posted event's result code: 415 * 416 * \li ISC_R_SUCCESS 417 * \li ISC_R_TIMEDOUT 418 * \li ISC_R_CONNREFUSED 419 * \li ISC_R_NETUNREACH 420 * \li ISC_R_UNEXPECTED 421 */ 422 423isc_result_t 424isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); 425/*%< 426 * Get the name of the peer connected to 'socket'. 427 * 428 * Requires: 429 * 430 * \li 'socket' is a valid TCP socket. 431 * 432 * Returns: 433 * 434 * \li ISC_R_SUCCESS 435 * \li ISC_R_TOOSMALL 436 * \li ISC_R_UNEXPECTED 437 */ 438 439isc_result_t 440isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); 441/*%< 442 * Get the name of 'socket'. 443 * 444 * Requires: 445 * 446 * \li 'socket' is a valid socket. 447 * 448 * Returns: 449 * 450 * \li ISC_R_SUCCESS 451 * \li ISC_R_TOOSMALL 452 * \li ISC_R_UNEXPECTED 453 */ 454 455/*@{*/ 456isc_result_t 457isc_socket_recv(isc_socket_t *sock, isc_region_t *region, 458 unsigned int minimum, 459 isc_task_t *task, isc_taskaction_t action, const void *arg); 460isc_result_t 461isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist, 462 unsigned int minimum, 463 isc_task_t *task, isc_taskaction_t action, const void *arg); 464 465isc_result_t 466isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, 467 unsigned int minimum, isc_task_t *task, 468 isc_socketevent_t *event, unsigned int flags); 469 470/*! 471 * Receive from 'socket', storing the results in region. 472 * 473 * Notes: 474 * 475 *\li Let 'length' refer to the length of 'region' or to the sum of all 476 * available regions in the list of buffers '*buflist'. 477 * 478 *\li If 'minimum' is non-zero and at least that many bytes are read, 479 * the completion event will be posted to the task 'task.' If minimum 480 * is zero, the exact number of bytes requested in the region must 481 * be read for an event to be posted. This only makes sense for TCP 482 * connections, and is always set to 1 byte for UDP. 483 * 484 *\li The read will complete when the desired number of bytes have been 485 * read, if end-of-input occurs, or if an error occurs. A read done 486 * event with the given 'action' and 'arg' will be posted to the 487 * event queue of 'task'. 488 * 489 *\li The caller may not modify 'region', the buffers which are passed 490 * into this function, or any data they refer to until the completion 491 * event is received. 492 * 493 *\li For isc_socket_recvv(): 494 * On successful completion, '*buflist' will be empty, and the list of 495 * all buffers will be returned in the done event's 'bufferlist' 496 * member. On error return, '*buflist' will be unchanged. 497 * 498 *\li For isc_socket_recv2(): 499 * 'event' is not NULL, and the non-socket specific fields are 500 * expected to be initialized. 501 * 502 *\li For isc_socket_recv2(): 503 * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If 504 * set and the operation completes, the return value will be 505 * ISC_R_SUCCESS and the event will be filled in and not sent. If the 506 * operation does not complete, the return value will be 507 * ISC_R_INPROGRESS and the event will be sent when the operation 508 * completes. 509 * 510 * Requires: 511 * 512 *\li 'socket' is a valid, bound socket. 513 * 514 *\li For isc_socket_recv(): 515 * 'region' is a valid region 516 * 517 *\li For isc_socket_recvv(): 518 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 519 * 520 *\li 'task' is a valid task 521 * 522 *\li For isc_socket_recv() and isc_socket_recvv(): 523 * action != NULL and is a valid action 524 * 525 *\li For isc_socket_recv2(): 526 * event != NULL 527 * 528 * Returns: 529 * 530 *\li #ISC_R_SUCCESS 531 *\li #ISC_R_INPROGRESS 532 *\li #ISC_R_NOMEMORY 533 *\li #ISC_R_UNEXPECTED 534 * 535 * Event results: 536 * 537 *\li #ISC_R_SUCCESS 538 *\li #ISC_R_UNEXPECTED 539 *\li XXX needs other net-type errors 540 */ 541/*@}*/ 542 543/*@{*/ 544isc_result_t 545isc_socket_send(isc_socket_t *sock, isc_region_t *region, 546 isc_task_t *task, isc_taskaction_t action, const void *arg); 547isc_result_t 548isc_socket_sendto(isc_socket_t *sock, isc_region_t *region, 549 isc_task_t *task, isc_taskaction_t action, const void *arg, 550 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 551isc_result_t 552isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist, 553 isc_task_t *task, isc_taskaction_t action, const void *arg); 554isc_result_t 555isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist, 556 isc_task_t *task, isc_taskaction_t action, const void *arg, 557 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo); 558isc_result_t 559isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, 560 isc_task_t *task, 561 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, 562 isc_socketevent_t *event, unsigned int flags); 563 564/*! 565 * Send the contents of 'region' to the socket's peer. 566 * 567 * Notes: 568 * 569 *\li Shutting down the requestor's task *may* result in any 570 * still pending writes being dropped or completed, depending on the 571 * underlying OS implementation. 572 * 573 *\li If 'action' is NULL, then no completion event will be posted. 574 * 575 *\li The caller may not modify 'region', the buffers which are passed 576 * into this function, or any data they refer to until the completion 577 * event is received. 578 * 579 *\li For isc_socket_sendv() and isc_socket_sendtov(): 580 * On successful completion, '*buflist' will be empty, and the list of 581 * all buffers will be returned in the done event's 'bufferlist' 582 * member. On error return, '*buflist' will be unchanged. 583 * 584 *\li For isc_socket_sendto2(): 585 * 'event' is not NULL, and the non-socket specific fields are 586 * expected to be initialized. 587 * 588 *\li For isc_socket_sendto2(): 589 * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE 590 * and ISC_SOCKFLAG_NORETRY. 591 * 592 *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the 593 * return value will be ISC_R_SUCCESS and the event will be filled 594 * in and not sent. If the operation does not complete, the return 595 * value will be ISC_R_INPROGRESS and the event will be sent when 596 * the operation completes. 597 * 598 *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set 599 * and the send operation fails due to a transient error, the send 600 * will not be retried and the error will be indicated in the event. 601 * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller 602 * to specify a region that is allocated on the stack. 603 * 604 * Requires: 605 * 606 *\li 'socket' is a valid, bound socket. 607 * 608 *\li For isc_socket_send(): 609 * 'region' is a valid region 610 * 611 *\li For isc_socket_sendv() and isc_socket_sendtov(): 612 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. 613 * 614 *\li 'task' is a valid task 615 * 616 *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and 617 * isc_socket_sendto(): 618 * action == NULL or is a valid action 619 * 620 *\li For isc_socket_sendto2(): 621 * event != NULL 622 * 623 * Returns: 624 * 625 *\li #ISC_R_SUCCESS 626 *\li #ISC_R_INPROGRESS 627 *\li #ISC_R_NOMEMORY 628 *\li #ISC_R_UNEXPECTED 629 * 630 * Event results: 631 * 632 *\li #ISC_R_SUCCESS 633 *\li #ISC_R_UNEXPECTED 634 *\li XXX needs other net-type errors 635 */ 636/*@}*/ 637 638isc_result_t 639isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); 640/*%< 641 * Create a socket manager. 642 * 643 * Notes: 644 * 645 *\li All memory will be allocated in memory context 'mctx'. 646 * 647 * Requires: 648 * 649 *\li 'mctx' is a valid memory context. 650 * 651 *\li 'managerp' points to a NULL isc_socketmgr_t. 652 * 653 * Ensures: 654 * 655 *\li '*managerp' is a valid isc_socketmgr_t. 656 * 657 * Returns: 658 * 659 *\li #ISC_R_SUCCESS 660 *\li #ISC_R_NOMEMORY 661 *\li #ISC_R_UNEXPECTED 662 */ 663 664void 665isc_socketmgr_destroy(isc_socketmgr_t **managerp); 666/*%< 667 * Destroy a socket manager. 668 * 669 * Notes: 670 * 671 *\li This routine blocks until there are no sockets left in the manager, 672 * so if the caller holds any socket references using the manager, it 673 * must detach them before calling isc_socketmgr_destroy() or it will 674 * block forever. 675 * 676 * Requires: 677 * 678 *\li '*managerp' is a valid isc_socketmgr_t. 679 * 680 *\li All sockets managed by this manager are fully detached. 681 * 682 * Ensures: 683 * 684 *\li *managerp == NULL 685 * 686 *\li All resources used by the manager have been freed. 687 */ 688 689isc_sockettype_t 690isc_socket_gettype(isc_socket_t *sock); 691/*%< 692 * Returns the socket type for "sock." 693 * 694 * Requires: 695 * 696 *\li "sock" is a valid socket. 697 */ 698 699/*@{*/ 700isc_boolean_t 701isc_socket_isbound(isc_socket_t *sock); 702 703void 704isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes); 705/*%< 706 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket 707 * option if the host OS supports this option. 708 * 709 * Requires: 710 *\li 'sock' is a valid socket. 711 */ 712/*@}*/ 713 714void 715isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active); 716 717/*%< 718 * Cleanup UNIX domain sockets in the file-system. If 'active' is true 719 * then just unlink the socket. If 'active' is false try to determine 720 * if there is a listener of the socket or not. If no listener is found 721 * then unlink socket. 722 * 723 * Prior to unlinking the path is tested to see if it a socket. 724 * 725 * Note: there are a number of race conditions which cannot be avoided 726 * both in the filesystem and any application using UNIX domain 727 * sockets (e.g. socket is tested between bind() and listen(), 728 * the socket is deleted and replaced in the file-system between 729 * stat() and unlink()). 730 */ 731 732isc_result_t 733isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm, 734 isc_uint32_t owner, isc_uint32_t group); 735/*%< 736 * Set ownership and file permissions on the UNIX domain socket. 737 * 738 * Note: On Solaris and SunOS this secures the directory containing 739 * the socket as Solaris and SunOS do not honour the filesytem 740 * permissions on the socket. 741 * 742 * Requires: 743 * \li 'sockaddr' to be a valid UNIX domain sockaddr. 744 * 745 * Returns: 746 * \li #ISC_R_SUCCESS 747 * \li #ISC_R_FAILURE 748 */ 749 750ISC_LANG_ENDDECLS 751 752#endif /* ISC_SOCKET_H */ 753