contrib/bind9/lib/isc/include/isc/socket.h

   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
  68 ISC_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
  90 struct 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
 105 typedef struct isc_socket_newconnev isc_socket_newconnev_t;
 106 struct 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
 113 typedef struct isc_socket_connev isc_socket_connev_t;
 114 struct 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
 150 typedef 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
 191 isc_result_t
 192 isc_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
 221 void
 222 isc_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
 253 void
 254 isc_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
 277 void
 278 isc_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
 293 void
 294 isc_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
 320 isc_result_t
 321 isc_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
 343 isc_result_t
 344 isc_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
 365 isc_result_t
 366 isc_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
 387 isc_result_t
 388 isc_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
 394 isc_result_t
 395 isc_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
 418 isc_result_t
 419 isc_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
 441 isc_result_t
 442 isc_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
 475 isc_result_t
 476 isc_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
 491 isc_result_t
 492 isc_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 /*@{*/
 508 isc_result_t
 509 isc_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);
 512 isc_result_t
 513 isc_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
 517 isc_result_t
 518 isc_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 /*@{*/
 596 isc_result_t
 597 isc_socket_send(isc_socket_t *sock, isc_region_t *region,
 598                 isc_task_t *task, isc_taskaction_t action, const void *arg);
 599 isc_result_t
 600 isc_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);
 603 isc_result_t
 604 isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
 605                  isc_task_t *task, isc_taskaction_t action, const void *arg);
 606 isc_result_t
 607 isc_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);
 610 isc_result_t
 611 isc_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
 690 isc_result_t
 691 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
 692
 693 isc_result_t
 694 isc_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
 724 isc_result_t
 725 isc_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
 740 void
 741 isc_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
 765 isc_sockettype_t
 766 isc_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 /*@{*/
 776 isc_boolean_t
 777 isc_socket_isbound(isc_socket_t *sock);
 778
 779 void
 780 isc_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
 790 void
 791 isc_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
 808 isc_result_t
 809 isc_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
 826 void
 827 isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
 828 /*%<
 829  * Temporary.  For use by named only.
 830  */
 831
 832 ISC_LANG_ENDDECLS
 833
 834 #endif /* ISC_SOCKET_H */