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

   1 /*
   2  * Copyright (C) 2004-2009, 2011-2014, 2016  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$ */
  19
  20 #ifndef ISC_SOCKET_H
  21 #define ISC_SOCKET_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/socket.h
  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 #include <isc/xml.h>
  68
  69 ISC_LANG_BEGINDECLS
  70
  71 /***
  72  *** Constants
  73  ***/
  74
  75 /*%
  76  * Maximum number of buffers in a scatter/gather read/write.  The operating
  77  * system in use must support at least this number (plus one on some.)
  78  */
  79 #define ISC_SOCKET_MAXSCATTERGATHER     8
  80
  81 /*%
  82  * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling
  83  * bind() if a non zero port is specified (AF_INET and AF_INET6).
  84  */
  85 #define ISC_SOCKET_REUSEADDRESS         0x01U
  86
  87 /*%
  88  * Statistics counters.  Used as isc_statscounter_t values.
  89  */
  90 enum {
  91         isc_sockstatscounter_udp4open = 0,
  92         isc_sockstatscounter_udp6open = 1,
  93         isc_sockstatscounter_tcp4open = 2,
  94         isc_sockstatscounter_tcp6open = 3,
  95         isc_sockstatscounter_unixopen = 4,
  96
  97         isc_sockstatscounter_udp4openfail = 5,
  98         isc_sockstatscounter_udp6openfail = 6,
  99         isc_sockstatscounter_tcp4openfail = 7,
 100         isc_sockstatscounter_tcp6openfail = 8,
 101         isc_sockstatscounter_unixopenfail = 9,
 102
 103         isc_sockstatscounter_udp4close = 10,
 104         isc_sockstatscounter_udp6close = 11,
 105         isc_sockstatscounter_tcp4close = 12,
 106         isc_sockstatscounter_tcp6close = 13,
 107         isc_sockstatscounter_unixclose = 14,
 108         isc_sockstatscounter_fdwatchclose = 15,
 109
 110         isc_sockstatscounter_udp4bindfail = 16,
 111         isc_sockstatscounter_udp6bindfail = 17,
 112         isc_sockstatscounter_tcp4bindfail = 18,
 113         isc_sockstatscounter_tcp6bindfail = 19,
 114         isc_sockstatscounter_unixbindfail = 20,
 115         isc_sockstatscounter_fdwatchbindfail = 21,
 116
 117         isc_sockstatscounter_udp4connect = 22,
 118         isc_sockstatscounter_udp6connect = 23,
 119         isc_sockstatscounter_tcp4connect = 24,
 120         isc_sockstatscounter_tcp6connect = 25,
 121         isc_sockstatscounter_unixconnect = 26,
 122         isc_sockstatscounter_fdwatchconnect = 27,
 123
 124         isc_sockstatscounter_udp4connectfail = 28,
 125         isc_sockstatscounter_udp6connectfail = 29,
 126         isc_sockstatscounter_tcp4connectfail = 30,
 127         isc_sockstatscounter_tcp6connectfail = 31,
 128         isc_sockstatscounter_unixconnectfail = 32,
 129         isc_sockstatscounter_fdwatchconnectfail = 33,
 130
 131         isc_sockstatscounter_tcp4accept = 34,
 132         isc_sockstatscounter_tcp6accept = 35,
 133         isc_sockstatscounter_unixaccept = 36,
 134
 135         isc_sockstatscounter_tcp4acceptfail = 37,
 136         isc_sockstatscounter_tcp6acceptfail = 38,
 137         isc_sockstatscounter_unixacceptfail = 39,
 138
 139         isc_sockstatscounter_udp4sendfail = 40,
 140         isc_sockstatscounter_udp6sendfail = 41,
 141         isc_sockstatscounter_tcp4sendfail = 42,
 142         isc_sockstatscounter_tcp6sendfail = 43,
 143         isc_sockstatscounter_unixsendfail = 44,
 144         isc_sockstatscounter_fdwatchsendfail = 45,
 145
 146         isc_sockstatscounter_udp4recvfail = 46,
 147         isc_sockstatscounter_udp6recvfail = 47,
 148         isc_sockstatscounter_tcp4recvfail = 48,
 149         isc_sockstatscounter_tcp6recvfail = 49,
 150         isc_sockstatscounter_unixrecvfail = 50,
 151         isc_sockstatscounter_fdwatchrecvfail = 51,
 152
 153         isc_sockstatscounter_max = 52
 154 };
 155
 156 /***
 157  *** Types
 158  ***/
 159
 160 struct isc_socketevent {
 161         ISC_EVENT_COMMON(isc_socketevent_t);
 162         isc_result_t            result;         /*%< OK, EOF, whatever else */
 163         unsigned int            minimum;        /*%< minimum i/o for event */
 164         unsigned int            n;              /*%< bytes read or written */
 165         unsigned int            offset;         /*%< offset into buffer list */
 166         isc_region_t            region;         /*%< for single-buffer i/o */
 167         isc_bufferlist_t        bufferlist;     /*%< list of buffers */
 168         isc_sockaddr_t          address;        /*%< source address */
 169         isc_time_t              timestamp;      /*%< timestamp of packet recv */
 170         struct in6_pktinfo      pktinfo;        /*%< ipv6 pktinfo */
 171         isc_uint32_t            attributes;     /*%< see below */
 172         isc_eventdestructor_t   destroy;        /*%< original destructor */
 173 };
 174
 175 typedef struct isc_socket_newconnev isc_socket_newconnev_t;
 176 struct isc_socket_newconnev {
 177         ISC_EVENT_COMMON(isc_socket_newconnev_t);
 178         isc_socket_t *          newsocket;
 179         isc_result_t            result;         /*%< OK, EOF, whatever else */
 180         isc_sockaddr_t          address;        /*%< source address */
 181 };
 182
 183 typedef struct isc_socket_connev isc_socket_connev_t;
 184 struct isc_socket_connev {
 185         ISC_EVENT_COMMON(isc_socket_connev_t);
 186         isc_result_t            result;         /*%< OK, EOF, whatever else */
 187 };
 188
 189 /*@{*/
 190 /*!
 191  * _ATTACHED:   Internal use only.
 192  * _TRUNC:      Packet was truncated on receive.
 193  * _CTRUNC:     Packet control information was truncated.  This can
 194  *              indicate that the packet is not complete, even though
 195  *              all the data is valid.
 196  * _TIMESTAMP:  The timestamp member is valid.
 197  * _PKTINFO:    The pktinfo member is valid.
 198  * _MULTICAST:  The UDP packet was received via a multicast transmission.
 199  */
 200 #define ISC_SOCKEVENTATTR_ATTACHED              0x80000000U /* internal */
 201 #define ISC_SOCKEVENTATTR_TRUNC                 0x00800000U /* public */
 202 #define ISC_SOCKEVENTATTR_CTRUNC                0x00400000U /* public */
 203 #define ISC_SOCKEVENTATTR_TIMESTAMP             0x00200000U /* public */
 204 #define ISC_SOCKEVENTATTR_PKTINFO               0x00100000U /* public */
 205 #define ISC_SOCKEVENTATTR_MULTICAST             0x00080000U /* public */
 206 /*@}*/
 207
 208 #define ISC_SOCKEVENT_ANYEVENT  (0)
 209 #define ISC_SOCKEVENT_RECVDONE  (ISC_EVENTCLASS_SOCKET + 1)
 210 #define ISC_SOCKEVENT_SENDDONE  (ISC_EVENTCLASS_SOCKET + 2)
 211 #define ISC_SOCKEVENT_NEWCONN   (ISC_EVENTCLASS_SOCKET + 3)
 212 #define ISC_SOCKEVENT_CONNECT   (ISC_EVENTCLASS_SOCKET + 4)
 213
 214 /*
 215  * Internal events.
 216  */
 217 #define ISC_SOCKEVENT_INTR      (ISC_EVENTCLASS_SOCKET + 256)
 218 #define ISC_SOCKEVENT_INTW      (ISC_EVENTCLASS_SOCKET + 257)
 219
 220 typedef enum {
 221         isc_sockettype_udp = 1,
 222         isc_sockettype_tcp = 2,
 223         isc_sockettype_unix = 3,
 224         isc_sockettype_fdwatch = 4
 225 } isc_sockettype_t;
 226
 227 /*@{*/
 228 /*!
 229  * How a socket should be shutdown in isc_socket_shutdown() calls.
 230  */
 231 #define ISC_SOCKSHUT_RECV       0x00000001      /*%< close read side */
 232 #define ISC_SOCKSHUT_SEND       0x00000002      /*%< close write side */
 233 #define ISC_SOCKSHUT_ALL        0x00000003      /*%< close them all */
 234 /*@}*/
 235
 236 /*@{*/
 237 /*!
 238  * What I/O events to cancel in isc_socket_cancel() calls.
 239  */
 240 #define ISC_SOCKCANCEL_RECV     0x00000001      /*%< cancel recv */
 241 #define ISC_SOCKCANCEL_SEND     0x00000002      /*%< cancel send */
 242 #define ISC_SOCKCANCEL_ACCEPT   0x00000004      /*%< cancel accept */
 243 #define ISC_SOCKCANCEL_CONNECT  0x00000008      /*%< cancel connect */
 244 #define ISC_SOCKCANCEL_ALL      0x0000000f      /*%< cancel everything */
 245 /*@}*/
 246
 247 /*@{*/
 248 /*!
 249  * Flags for isc_socket_send() and isc_socket_recv() calls.
 250  */
 251 #define ISC_SOCKFLAG_IMMEDIATE  0x00000001      /*%< send event only if needed */
 252 #define ISC_SOCKFLAG_NORETRY    0x00000002      /*%< drop failed UDP sends */
 253 /*@}*/
 254
 255 /*@{*/
 256 /*!
 257  * Flags for fdwatchcreate.
 258  */
 259 #define ISC_SOCKFDWATCH_READ    0x00000001      /*%< watch for readable */
 260 #define ISC_SOCKFDWATCH_WRITE   0x00000002      /*%< watch for writable */
 261 /*@}*/
 262
 263 /*% Socket and socket manager methods */
 264 typedef struct isc_socketmgrmethods {
 265         void            (*destroy)(isc_socketmgr_t **managerp);
 266         isc_result_t    (*socketcreate)(isc_socketmgr_t *manager, int pf,
 267                                         isc_sockettype_t type,
 268                                         isc_socket_t **socketp);
 269         isc_result_t    (*fdwatchcreate)(isc_socketmgr_t *manager, int fd,
 270                                          int flags,
 271                                          isc_sockfdwatch_t callback,
 272                                          void *cbarg, isc_task_t *task,
 273                                          isc_socket_t **socketp);
 274 } isc_socketmgrmethods_t;
 275
 276 typedef struct isc_socketmethods {
 277         void            (*attach)(isc_socket_t *socket,
 278                                   isc_socket_t **socketp);
 279         void            (*detach)(isc_socket_t **socketp);
 280         isc_result_t    (*bind)(isc_socket_t *sock, isc_sockaddr_t *sockaddr,
 281                                 unsigned int options);
 282         isc_result_t    (*sendto)(isc_socket_t *sock, isc_region_t *region,
 283                                   isc_task_t *task, isc_taskaction_t action,
 284                                   void *arg, isc_sockaddr_t *address,
 285                                   struct in6_pktinfo *pktinfo);
 286         isc_result_t    (*sendto2)(isc_socket_t *sock, isc_region_t *region,
 287                                    isc_task_t *task, isc_sockaddr_t *address,
 288                                    struct in6_pktinfo *pktinfo,
 289                                    isc_socketevent_t *event,
 290                                    unsigned int flags);
 291         isc_result_t    (*connect)(isc_socket_t *sock, isc_sockaddr_t *addr,
 292                                    isc_task_t *task, isc_taskaction_t action,
 293                                    void *arg);
 294         isc_result_t    (*recv)(isc_socket_t *sock, isc_region_t *region,
 295                                 unsigned int minimum, isc_task_t *task,
 296                                 isc_taskaction_t action, void *arg);
 297         isc_result_t    (*recv2)(isc_socket_t *sock, isc_region_t *region,
 298                                  unsigned int minimum, isc_task_t *task,
 299                                  isc_socketevent_t *event, unsigned int flags);
 300         void            (*cancel)(isc_socket_t *sock, isc_task_t *task,
 301                                   unsigned int how);
 302         isc_result_t    (*getsockname)(isc_socket_t *sock,
 303                                        isc_sockaddr_t *addressp);
 304         isc_sockettype_t (*gettype)(isc_socket_t *sock);
 305         void            (*ipv6only)(isc_socket_t *sock, isc_boolean_t yes);
 306         isc_result_t    (*fdwatchpoke)(isc_socket_t *sock, int flags);
 307         isc_result_t            (*dup)(isc_socket_t *socket,
 308                                   isc_socket_t **socketp);
 309         int             (*getfd)(isc_socket_t *socket);
 310 } isc_socketmethods_t;
 311
 312 /*%
 313  * This structure is actually just the common prefix of a socket manager
 314  * object implementation's version of an isc_socketmgr_t.
 315  * \brief
 316  * Direct use of this structure by clients is forbidden.  socket implementations
 317  * may change the structure.  'magic' must be ISCAPI_SOCKETMGR_MAGIC for any
 318  * of the isc_socket_ routines to work.  socket implementations must maintain
 319  * all socket invariants.
 320  * In effect, this definition is used only for non-BIND9 version ("export")
 321  * of the library, and the export version does not work for win32.  So, to avoid
 322  * the definition conflict with win32/socket.c, we enable this definition only
 323  * for non-Win32 (i.e. Unix) platforms.
 324  */
 325 #ifndef WIN32
 326 struct isc_socketmgr {
 327         unsigned int            impmagic;
 328         unsigned int            magic;
 329         isc_socketmgrmethods_t  *methods;
 330 };
 331 #endif
 332
 333 #define ISCAPI_SOCKETMGR_MAGIC          ISC_MAGIC('A','s','m','g')
 334 #define ISCAPI_SOCKETMGR_VALID(m)       ((m) != NULL && \
 335                                          (m)->magic == ISCAPI_SOCKETMGR_MAGIC)
 336
 337 /*%
 338  * This is the common prefix of a socket object.  The same note as
 339  * that for the socketmgr structure applies.
 340  */
 341 #ifndef WIN32
 342 struct isc_socket {
 343         unsigned int            impmagic;
 344         unsigned int            magic;
 345         isc_socketmethods_t     *methods;
 346 };
 347 #endif
 348
 349 #define ISCAPI_SOCKET_MAGIC     ISC_MAGIC('A','s','c','t')
 350 #define ISCAPI_SOCKET_VALID(s)  ((s) != NULL && \
 351                                  (s)->magic == ISCAPI_SOCKET_MAGIC)
 352
 353 /***
 354  *** Socket and Socket Manager Functions
 355  ***
 356  *** Note: all Ensures conditions apply only if the result is success for
 357  *** those functions which return an isc_result.
 358  ***/
 359
 360 isc_result_t
 361 isc_socket_fdwatchcreate(isc_socketmgr_t *manager,
 362                          int fd,
 363                          int flags,
 364                          isc_sockfdwatch_t callback,
 365                          void *cbarg,
 366                          isc_task_t *task,
 367                          isc_socket_t **socketp);
 368 /*%<
 369  * Create a new file descriptor watch socket managed by 'manager'.
 370  *
 371  * Note:
 372  *
 373  *\li   'fd' is the already-opened file descriptor (must be less
 374  *      than maxsockets).
 375  *\li   This function is not available on Windows.
 376  *\li   The callback function is called "in-line" - this means the function
 377  *      needs to return as fast as possible, as all other I/O will be suspended
 378  *      until the callback completes.
 379  *
 380  * Requires:
 381  *
 382  *\li   'manager' is a valid manager
 383  *
 384  *\li   'socketp' is a valid pointer, and *socketp == NULL
 385  *
 386  *\li   'fd' be opened.
 387  *
 388  * Ensures:
 389  *
 390  *      '*socketp' is attached to the newly created fdwatch socket
 391  *
 392  * Returns:
 393  *
 394  *\li   #ISC_R_SUCCESS
 395  *\li   #ISC_R_NOMEMORY
 396  *\li   #ISC_R_NORESOURCES
 397  *\li   #ISC_R_UNEXPECTED
 398  *\li   #ISC_R_RANGE
 399  */
 400
 401 isc_result_t
 402 isc_socket_fdwatchpoke(isc_socket_t *sock,
 403                        int flags);
 404 /*%<
 405  * Poke a file descriptor watch socket informing the manager that it
 406  * should restart watching the socket
 407  *
 408  * Note:
 409  *
 410  *\li   'sock' is the socket returned by isc_socket_fdwatchcreate
 411  *
 412  *\li   'flags' indicates what the manager should watch for on the socket
 413  *      in addition to what it may already be watching.  It can be one or
 414  *      both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE.  To
 415  *      temporarily disable watching on a socket the value indicating
 416  *      no more data should be returned from the call back routine.
 417  *
 418  *\li   This function is not available on Windows.
 419  *
 420  * Requires:
 421  *
 422  *\li   'sock' is a valid isc socket
 423  *
 424  *
 425  * Returns:
 426  *
 427  *\li   #ISC_R_SUCCESS
 428  */
 429
 430 isc_result_t
 431 isc_socket_create(isc_socketmgr_t *manager,
 432                   int pf,
 433                   isc_sockettype_t type,
 434                   isc_socket_t **socketp);
 435 /*%<
 436  * Create a new 'type' socket managed by 'manager'.
 437  *
 438  * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate()
 439  * rather than isc_socket_create().
 440  *
 441  * Note:
 442  *
 443  *\li   'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
 444  *
 445  * Requires:
 446  *
 447  *\li   'manager' is a valid manager
 448  *
 449  *\li   'socketp' is a valid pointer, and *socketp == NULL
 450  *
 451  *\li   'type' is not isc_sockettype_fdwatch
 452  *
 453  * Ensures:
 454  *
 455  *      '*socketp' is attached to the newly created socket
 456  *
 457  * Returns:
 458  *
 459  *\li   #ISC_R_SUCCESS
 460  *\li   #ISC_R_NOMEMORY
 461  *\li   #ISC_R_NORESOURCES
 462  *\li   #ISC_R_UNEXPECTED
 463  */
 464
 465 isc_result_t
 466 isc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp);
 467 /*%<
 468  * Duplicate an existing socket, reusing its file descriptor.
 469  */
 470
 471 void
 472 isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
 473                   unsigned int how);
 474 /*%<
 475  * Cancel pending I/O of the type specified by "how".
 476  *
 477  * Note: if "task" is NULL, then the cancel applies to all tasks using the
 478  * socket.
 479  *
 480  * Requires:
 481  *
 482  * \li  "socket" is a valid socket
 483  *
 484  * \li  "task" is NULL or a valid task
 485  *
 486  * "how" is a bitmask describing the type of cancelation to perform.
 487  * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
 488  * socket.
 489  *
 490  * \li ISC_SOCKCANCEL_RECV:
 491  *      Cancel pending isc_socket_recv() calls.
 492  *
 493  * \li ISC_SOCKCANCEL_SEND:
 494  *      Cancel pending isc_socket_send() and isc_socket_sendto() calls.
 495  *
 496  * \li ISC_SOCKCANCEL_ACCEPT:
 497  *      Cancel pending isc_socket_accept() calls.
 498  *
 499  * \li ISC_SOCKCANCEL_CONNECT:
 500  *      Cancel pending isc_socket_connect() call.
 501  */
 502
 503 void
 504 isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
 505 /*%<
 506  * Shutdown 'socket' according to 'how'.
 507  *
 508  * Requires:
 509  *
 510  * \li  'socket' is a valid socket.
 511  *
 512  * \li  'task' is NULL or is a valid task.
 513  *
 514  * \li  If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then
 515  *
 516  *              The read queue must be empty.
 517  *
 518  *              No further read requests may be made.
 519  *
 520  * \li  If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
 521  *
 522  *              The write queue must be empty.
 523  *
 524  *              No further write requests may be made.
 525  */
 526
 527 void
 528 isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
 529 /*%<
 530  * Attach *socketp to socket.
 531  *
 532  * Requires:
 533  *
 534  * \li  'socket' is a valid socket.
 535  *
 536  * \li  'socketp' points to a NULL socket.
 537  *
 538  * Ensures:
 539  *
 540  * \li  *socketp is attached to socket.
 541  */
 542
 543 void
 544 isc_socket_detach(isc_socket_t **socketp);
 545 /*%<
 546  * Detach *socketp from its socket.
 547  *
 548  * Requires:
 549  *
 550  * \li  'socketp' points to a valid socket.
 551  *
 552  * \li  If '*socketp' is the last reference to the socket,
 553  *      then:
 554  *
 555  *              There must be no pending I/O requests.
 556  *
 557  * Ensures:
 558  *
 559  * \li  *socketp is NULL.
 560  *
 561  * \li  If '*socketp' is the last reference to the socket,
 562  *      then:
 563  *
 564  *              The socket will be shutdown (both reading and writing)
 565  *              for all tasks.
 566  *
 567  *              All resources used by the socket have been freed
 568  */
 569
 570 isc_result_t
 571 isc_socket_open(isc_socket_t *sock);
 572 /*%<
 573  * Open a new socket file descriptor of the given socket structure.  It simply
 574  * opens a new descriptor; all of the other parameters including the socket
 575  * type are inherited from the existing socket.  This function is provided to
 576  * avoid overhead of destroying and creating sockets when many short-lived
 577  * sockets are frequently opened and closed.  When the efficiency is not an
 578  * issue, it should be safer to detach the unused socket and re-create a new
 579  * one.  This optimization may not be available for some systems, in which
 580  * case this function will return ISC_R_NOTIMPLEMENTED and must not be used.
 581  *
 582  * isc_socket_open() should not be called on sockets created by
 583  * isc_socket_fdwatchcreate().
 584  *
 585  * Requires:
 586  *
 587  * \li  there must be no other reference to this socket.
 588  *
 589  * \li  'socket' is a valid and previously closed by isc_socket_close()
 590  *
 591  * \li  'sock->type' is not isc_sockettype_fdwatch
 592  *
 593  * Returns:
 594  *      Same as isc_socket_create().
 595  * \li  ISC_R_NOTIMPLEMENTED
 596  */
 597
 598 isc_result_t
 599 isc_socket_close(isc_socket_t *sock);
 600 /*%<
 601  * Close a socket file descriptor of the given socket structure.  This function
 602  * is provided as an alternative to destroying an unused socket when overhead
 603  * destroying/re-creating sockets can be significant, and is expected to be
 604  * used with isc_socket_open().  This optimization may not be available for some
 605  * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and
 606  * must not be used.
 607  *
 608  * isc_socket_close() should not be called on sockets created by
 609  * isc_socket_fdwatchcreate().
 610  *
 611  * Requires:
 612  *
 613  * \li  The socket must have a valid descriptor.
 614  *
 615  * \li  There must be no other reference to this socket.
 616  *
 617  * \li  There must be no pending I/O requests.
 618  *
 619  * \li  'sock->type' is not isc_sockettype_fdwatch
 620  *
 621  * Returns:
 622  * \li  #ISC_R_NOTIMPLEMENTED
 623  */
 624
 625 isc_result_t
 626 isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
 627                 unsigned int options);
 628 /*%<
 629  * Bind 'socket' to '*addressp'.
 630  *
 631  * Requires:
 632  *
 633  * \li  'socket' is a valid socket
 634  *
 635  * \li  'addressp' points to a valid isc_sockaddr.
 636  *
 637  * Returns:
 638  *
 639  * \li  ISC_R_SUCCESS
 640  * \li  ISC_R_NOPERM
 641  * \li  ISC_R_ADDRNOTAVAIL
 642  * \li  ISC_R_ADDRINUSE
 643  * \li  ISC_R_BOUND
 644  * \li  ISC_R_UNEXPECTED
 645  */
 646
 647 isc_result_t
 648 isc_socket_filter(isc_socket_t *sock, const char *filter);
 649 /*%<
 650  * Inform the kernel that it should perform accept filtering.
 651  * If filter is NULL the current filter will be removed.:w
 652  */
 653
 654 isc_result_t
 655 isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
 656 /*%<
 657  * Set listen mode on the socket.  After this call, the only function that
 658  * can be used (other than attach and detach) is isc_socket_accept().
 659  *
 660  * Notes:
 661  *
 662  * \li  'backlog' is as in the UNIX system call listen() and may be
 663  *      ignored by non-UNIX implementations.
 664  *
 665  * \li  If 'backlog' is zero, a reasonable system default is used, usually
 666  *      SOMAXCONN.
 667  *
 668  * Requires:
 669  *
 670  * \li  'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
 671  *
 672  * Returns:
 673  *
 674  * \li  ISC_R_SUCCESS
 675  * \li  ISC_R_UNEXPECTED
 676  */
 677
 678 isc_result_t
 679 isc_socket_accept(isc_socket_t *sock,
 680                   isc_task_t *task, isc_taskaction_t action, void *arg);
 681 /*%<
 682  * Queue accept event.  When a new connection is received, the task will
 683  * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
 684  * socket.  The new socket structure is sent inside the isc_socket_newconnev_t
 685  * event type, and is attached to the task 'task'.
 686  *
 687  * REQUIRES:
 688  * \li  'socket' is a valid TCP socket that isc_socket_listen() was called
 689  *      on.
 690  *
 691  * \li  'task' is a valid task
 692  *
 693  * \li  'action' is a valid action
 694  *
 695  * RETURNS:
 696  * \li  ISC_R_SUCCESS
 697  * \li  ISC_R_NOMEMORY
 698  * \li  ISC_R_UNEXPECTED
 699  */
 700
 701 isc_result_t
 702 isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
 703                    isc_task_t *task, isc_taskaction_t action,
 704                    void *arg);
 705 /*%<
 706  * Connect 'socket' to peer with address *saddr.  When the connection
 707  * succeeds, or when an error occurs, a CONNECT event with action 'action'
 708  * and arg 'arg' will be posted to the event queue for 'task'.
 709  *
 710  * Requires:
 711  *
 712  * \li  'socket' is a valid TCP socket
 713  *
 714  * \li  'addressp' points to a valid isc_sockaddr
 715  *
 716  * \li  'task' is a valid task
 717  *
 718  * \li  'action' is a valid action
 719  *
 720  * Returns:
 721  *
 722  * \li  ISC_R_SUCCESS
 723  * \li  ISC_R_NOMEMORY
 724  * \li  ISC_R_UNEXPECTED
 725  *
 726  * Posted event's result code:
 727  *
 728  * \li  ISC_R_SUCCESS
 729  * \li  ISC_R_TIMEDOUT
 730  * \li  ISC_R_CONNREFUSED
 731  * \li  ISC_R_NETUNREACH
 732  * \li  ISC_R_UNEXPECTED
 733  */
 734
 735 isc_result_t
 736 isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
 737 /*%<
 738  * Get the name of the peer connected to 'socket'.
 739  *
 740  * Requires:
 741  *
 742  * \li  'socket' is a valid TCP socket.
 743  *
 744  * Returns:
 745  *
 746  * \li  ISC_R_SUCCESS
 747  * \li  ISC_R_TOOSMALL
 748  * \li  ISC_R_UNEXPECTED
 749  */
 750
 751 isc_result_t
 752 isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
 753 /*%<
 754  * Get the name of 'socket'.
 755  *
 756  * Requires:
 757  *
 758  * \li  'socket' is a valid socket.
 759  *
 760  * Returns:
 761  *
 762  * \li  ISC_R_SUCCESS
 763  * \li  ISC_R_TOOSMALL
 764  * \li  ISC_R_UNEXPECTED
 765  */
 766
 767 /*@{*/
 768 isc_result_t
 769 isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
 770                 unsigned int minimum,
 771                 isc_task_t *task, isc_taskaction_t action, void *arg);
 772 isc_result_t
 773 isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
 774                  unsigned int minimum,
 775                  isc_task_t *task, isc_taskaction_t action, void *arg);
 776
 777 isc_result_t
 778 isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
 779                  unsigned int minimum, isc_task_t *task,
 780                  isc_socketevent_t *event, unsigned int flags);
 781
 782 /*!
 783  * Receive from 'socket', storing the results in region.
 784  *
 785  * Notes:
 786  *
 787  *\li   Let 'length' refer to the length of 'region' or to the sum of all
 788  *      available regions in the list of buffers '*buflist'.
 789  *
 790  *\li   If 'minimum' is non-zero and at least that many bytes are read,
 791  *      the completion event will be posted to the task 'task.'  If minimum
 792  *      is zero, the exact number of bytes requested in the region must
 793  *      be read for an event to be posted.  This only makes sense for TCP
 794  *      connections, and is always set to 1 byte for UDP.
 795  *
 796  *\li   The read will complete when the desired number of bytes have been
 797  *      read, if end-of-input occurs, or if an error occurs.  A read done
 798  *      event with the given 'action' and 'arg' will be posted to the
 799  *      event queue of 'task'.
 800  *
 801  *\li   The caller may not modify 'region', the buffers which are passed
 802  *      into this function, or any data they refer to until the completion
 803  *      event is received.
 804  *
 805  *\li   For isc_socket_recvv():
 806  *      On successful completion, '*buflist' will be empty, and the list of
 807  *      all buffers will be returned in the done event's 'bufferlist'
 808  *      member.  On error return, '*buflist' will be unchanged.
 809  *
 810  *\li   For isc_socket_recv2():
 811  *      'event' is not NULL, and the non-socket specific fields are
 812  *      expected to be initialized.
 813  *
 814  *\li   For isc_socket_recv2():
 815  *      The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE.  If
 816  *      set and the operation completes, the return value will be
 817  *      ISC_R_SUCCESS and the event will be filled in and not sent.  If the
 818  *      operation does not complete, the return value will be
 819  *      ISC_R_INPROGRESS and the event will be sent when the operation
 820  *      completes.
 821  *
 822  * Requires:
 823  *
 824  *\li   'socket' is a valid, bound socket.
 825  *
 826  *\li   For isc_socket_recv():
 827  *      'region' is a valid region
 828  *
 829  *\li   For isc_socket_recvv():
 830  *      'buflist' is non-NULL, and '*buflist' contain at least one buffer.
 831  *
 832  *\li   'task' is a valid task
 833  *
 834  *\li   For isc_socket_recv() and isc_socket_recvv():
 835  *      action != NULL and is a valid action
 836  *
 837  *\li   For isc_socket_recv2():
 838  *      event != NULL
 839  *
 840  * Returns:
 841  *
 842  *\li   #ISC_R_SUCCESS
 843  *\li   #ISC_R_INPROGRESS
 844  *\li   #ISC_R_NOMEMORY
 845  *\li   #ISC_R_UNEXPECTED
 846  *
 847  * Event results:
 848  *
 849  *\li   #ISC_R_SUCCESS
 850  *\li   #ISC_R_UNEXPECTED
 851  *\li   XXX needs other net-type errors
 852  */
 853 /*@}*/
 854
 855 /*@{*/
 856 isc_result_t
 857 isc_socket_send(isc_socket_t *sock, isc_region_t *region,
 858                 isc_task_t *task, isc_taskaction_t action, void *arg);
 859 isc_result_t
 860 isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
 861                   isc_task_t *task, isc_taskaction_t action, void *arg,
 862                   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
 863 isc_result_t
 864 isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
 865                  isc_task_t *task, isc_taskaction_t action, void *arg);
 866 isc_result_t
 867 isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
 868                    isc_task_t *task, isc_taskaction_t action, void *arg,
 869                    isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
 870 isc_result_t
 871 isc_socket_sendtov2(isc_socket_t *sock, isc_bufferlist_t *buflist,
 872                     isc_task_t *task, isc_taskaction_t action, void *arg,
 873                     isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
 874                     unsigned int flags);
 875 isc_result_t
 876 isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
 877                    isc_task_t *task,
 878                    isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
 879                    isc_socketevent_t *event, unsigned int flags);
 880
 881 /*!
 882  * Send the contents of 'region' to the socket's peer.
 883  *
 884  * Notes:
 885  *
 886  *\li   Shutting down the requestor's task *may* result in any
 887  *      still pending writes being dropped or completed, depending on the
 888  *      underlying OS implementation.
 889  *
 890  *\li   If 'action' is NULL, then no completion event will be posted.
 891  *
 892  *\li   The caller may not modify 'region', the buffers which are passed
 893  *      into this function, or any data they refer to until the completion
 894  *      event is received.
 895  *
 896  *\li   For isc_socket_sendv() and isc_socket_sendtov():
 897  *      On successful completion, '*buflist' will be empty, and the list of
 898  *      all buffers will be returned in the done event's 'bufferlist'
 899  *      member.  On error return, '*buflist' will be unchanged.
 900  *
 901  *\li   For isc_socket_sendto2():
 902  *      'event' is not NULL, and the non-socket specific fields are
 903  *      expected to be initialized.
 904  *
 905  *\li   For isc_socket_sendto2():
 906  *      The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
 907  *      and ISC_SOCKFLAG_NORETRY.
 908  *
 909  *\li   If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
 910  *      return value will be ISC_R_SUCCESS and the event will be filled
 911  *      in and not sent.  If the operation does not complete, the return
 912  *      value will be ISC_R_INPROGRESS and the event will be sent when
 913  *      the operation completes.
 914  *
 915  *\li   ISC_SOCKFLAG_NORETRY can only be set for UDP sockets.  If set
 916  *      and the send operation fails due to a transient error, the send
 917  *      will not be retried and the error will be indicated in the event.
 918  *      Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
 919  *      to specify a region that is allocated on the stack.
 920  *
 921  * Requires:
 922  *
 923  *\li   'socket' is a valid, bound socket.
 924  *
 925  *\li   For isc_socket_send():
 926  *      'region' is a valid region
 927  *
 928  *\li   For isc_socket_sendv() and isc_socket_sendtov():
 929  *      'buflist' is non-NULL, and '*buflist' contain at least one buffer.
 930  *
 931  *\li   'task' is a valid task
 932  *
 933  *\li   For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and
 934  *      isc_socket_sendto():
 935  *      action == NULL or is a valid action
 936  *
 937  *\li   For isc_socket_sendto2():
 938  *      event != NULL
 939  *
 940  * Returns:
 941  *
 942  *\li   #ISC_R_SUCCESS
 943  *\li   #ISC_R_INPROGRESS
 944  *\li   #ISC_R_NOMEMORY
 945  *\li   #ISC_R_UNEXPECTED
 946  *
 947  * Event results:
 948  *
 949  *\li   #ISC_R_SUCCESS
 950  *\li   #ISC_R_UNEXPECTED
 951  *\li   XXX needs other net-type errors
 952  */
 953 /*@}*/
 954
 955 isc_result_t
 956 isc_socketmgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx,
 957                           isc_socketmgr_t **managerp);
 958
 959 isc_result_t
 960 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
 961
 962 isc_result_t
 963 isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp,
 964                       unsigned int maxsocks);
 965 /*%<
 966  * Create a socket manager.  If "maxsocks" is non-zero, it specifies the
 967  * maximum number of sockets that the created manager should handle.
 968  * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with
 969  * "maxsocks" being zero.
 970  * isc_socketmgr_createinctx() also associates the new manager with the
 971  * specified application context.
 972  *
 973  * Notes:
 974  *
 975  *\li   All memory will be allocated in memory context 'mctx'.
 976  *
 977  * Requires:
 978  *
 979  *\li   'mctx' is a valid memory context.
 980  *
 981  *\li   'managerp' points to a NULL isc_socketmgr_t.
 982  *
 983  *\li   'actx' is a valid application context (for createinctx()).
 984  *
 985  * Ensures:
 986  *
 987  *\li   '*managerp' is a valid isc_socketmgr_t.
 988  *
 989  * Returns:
 990  *
 991  *\li   #ISC_R_SUCCESS
 992  *\li   #ISC_R_NOMEMORY
 993  *\li   #ISC_R_UNEXPECTED
 994  *\li   #ISC_R_NOTIMPLEMENTED
 995  */
 996
 997 isc_result_t
 998 isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp);
 999 /*%<
1000  * Returns in "*nsockp" the maximum number of sockets this manager may open.
1001  *
1002  * Requires:
1003  *
1004  *\li   '*manager' is a valid isc_socketmgr_t.
1005  *\li   'nsockp' is not NULL.
1006  *
1007  * Returns:
1008  *
1009  *\li   #ISC_R_SUCCESS
1010  *\li   #ISC_R_NOTIMPLEMENTED
1011  */
1012
1013 void
1014 isc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats);
1015 /*%<
1016  * Set a general socket statistics counter set 'stats' for 'manager'.
1017  *
1018  * Requires:
1019  * \li  'manager' is valid, hasn't opened any socket, and doesn't have
1020  *      stats already set.
1021  *
1022  *\li   stats is a valid statistics supporting socket statistics counters
1023  *      (see above).
1024  */
1025
1026 void
1027 isc_socketmgr_destroy(isc_socketmgr_t **managerp);
1028 /*%<
1029  * Destroy a socket manager.
1030  *
1031  * Notes:
1032  *
1033  *\li   This routine blocks until there are no sockets left in the manager,
1034  *      so if the caller holds any socket references using the manager, it
1035  *      must detach them before calling isc_socketmgr_destroy() or it will
1036  *      block forever.
1037  *
1038  * Requires:
1039  *
1040  *\li   '*managerp' is a valid isc_socketmgr_t.
1041  *
1042  *\li   All sockets managed by this manager are fully detached.
1043  *
1044  * Ensures:
1045  *
1046  *\li   *managerp == NULL
1047  *
1048  *\li   All resources used by the manager have been freed.
1049  */
1050
1051 isc_sockettype_t
1052 isc_socket_gettype(isc_socket_t *sock);
1053 /*%<
1054  * Returns the socket type for "sock."
1055  *
1056  * Requires:
1057  *
1058  *\li   "sock" is a valid socket.
1059  */
1060
1061 /*@{*/
1062 isc_boolean_t
1063 isc_socket_isbound(isc_socket_t *sock);
1064
1065 void
1066 isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
1067 /*%<
1068  * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
1069  * option if the host OS supports this option.
1070  *
1071  * Requires:
1072  *\li   'sock' is a valid socket.
1073  */
1074 /*@}*/
1075
1076 void
1077 isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);
1078
1079 /*%<
1080  * Cleanup UNIX domain sockets in the file-system.  If 'active' is true
1081  * then just unlink the socket.  If 'active' is false try to determine
1082  * if there is a listener of the socket or not.  If no listener is found
1083  * then unlink socket.
1084  *
1085  * Prior to unlinking the path is tested to see if it a socket.
1086  *
1087  * Note: there are a number of race conditions which cannot be avoided
1088  *       both in the filesystem and any application using UNIX domain
1089  *       sockets (e.g. socket is tested between bind() and listen(),
1090  *       the socket is deleted and replaced in the file-system between
1091  *       stat() and unlink()).
1092  */
1093
1094 isc_result_t
1095 isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
1096                     isc_uint32_t owner, isc_uint32_t group);
1097 /*%<
1098  * Set ownership and file permissions on the UNIX domain socket.
1099  *
1100  * Note: On Solaris and SunOS this secures the directory containing
1101  *       the socket as Solaris and SunOS do not honour the filesystem
1102  *       permissions on the socket.
1103  *
1104  * Requires:
1105  * \li  'sockaddr' to be a valid UNIX domain sockaddr.
1106  *
1107  * Returns:
1108  * \li  #ISC_R_SUCCESS
1109  * \li  #ISC_R_FAILURE
1110  */
1111
1112 void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag);
1113 /*%<
1114  * Set the name and optional tag for a socket.  This allows tracking of the
1115  * owner or purpose for this socket, and is useful for tracing and statistics
1116  * reporting.
1117  */
1118
1119 const char *isc_socket_getname(isc_socket_t *socket);
1120 /*%<
1121  * Get the name associated with a socket, if any.
1122  */
1123
1124 void *isc_socket_gettag(isc_socket_t *socket);
1125 /*%<
1126  * Get the tag associated with a socket, if any.
1127  */
1128
1129 int isc_socket_getfd(isc_socket_t *socket);
1130 /*%<
1131  * Get the file descriptor associated with a socket
1132  */
1133
1134 void
1135 isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
1136 /*%<
1137  * Temporary.  For use by named only.
1138  */
1139
1140 void
1141 isc__socketmgr_maxudp(isc_socketmgr_t *mgr, int maxudp);
1142 /*%<
1143  * Test interface. Drop UDP packet > 'maxudp'.
1144  */
1145
1146 #ifdef HAVE_LIBXML2
1147
1148 int
1149 isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer);
1150 /*%<
1151  * Render internal statistics and other state into the XML document.
1152  */
1153
1154 #endif /* HAVE_LIBXML2 */
1155
1156 #ifdef USE_SOCKETIMPREGISTER
1157 /*%<
1158  * See isc_socketmgr_create() above.
1159  */
1160 typedef isc_result_t
1161 (*isc_socketmgrcreatefunc_t)(isc_mem_t *mctx, isc_socketmgr_t **managerp);
1162
1163 isc_result_t
1164 isc_socket_register(isc_socketmgrcreatefunc_t createfunc);
1165 /*%<
1166  * Register a new socket I/O implementation and add it to the list of
1167  * supported implementations.  This function must be called when a different
1168  * event library is used than the one contained in the ISC library.
1169  */
1170
1171 isc_result_t
1172 isc__socket_register(void);
1173 /*%<
1174  * A short cut function that specifies the socket I/O module in the ISC
1175  * library for isc_socket_register().  An application that uses the ISC library
1176  * usually do not have to care about this function: it would call
1177  * isc_lib_register(), which internally calls this function.
1178  */
1179 #endif /* USE_SOCKETIMPREGISTER */
1180
1181 ISC_LANG_ENDDECLS
1182
1183 #endif /* ISC_SOCKET_H */