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

   1 /*
   2  * Copyright (C) 2004-2009, 2011, 2012  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                                   const 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                                    const 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, const 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.
 374  *\li   This function is not available on Windows.
 375  *\li   The callback function is called "in-line" - this means the function
 376  *      needs to return as fast as possible, as all other I/O will be suspended
 377  *      until the callback completes.
 378  *
 379  * Requires:
 380  *
 381  *\li   'manager' is a valid manager
 382  *
 383  *\li   'socketp' is a valid pointer, and *socketp == NULL
 384  *
 385  *\li   'fd' be opened.
 386  *
 387  * Ensures:
 388  *
 389  *      '*socketp' is attached to the newly created fdwatch socket
 390  *
 391  * Returns:
 392  *
 393  *\li   #ISC_R_SUCCESS
 394  *\li   #ISC_R_NOMEMORY
 395  *\li   #ISC_R_NORESOURCES
 396  *\li   #ISC_R_UNEXPECTED
 397  */
 398
 399 isc_result_t
 400 isc_socket_fdwatchpoke(isc_socket_t *sock,
 401                        int flags);
 402 /*%<
 403  * Poke a file descriptor watch socket informing the manager that it
 404  * should restart watching the socket
 405  *
 406  * Note:
 407  *
 408  *\li   'sock' is the socket returned by isc_socket_fdwatchcreate
 409  *
 410  *\li   'flags' indicates what the manager should watch for on the socket
 411  *      in addition to what it may already be watching.  It can be one or
 412  *      both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE.  To
 413  *      temporarily disable watching on a socket the value indicating
 414  *      no more data should be returned from the call back routine.
 415  *
 416  *\li   This function is not available on Windows.
 417  *
 418  * Requires:
 419  *
 420  *\li   'sock' is a valid isc socket
 421  *
 422  *
 423  * Returns:
 424  *
 425  *\li   #ISC_R_SUCCESS
 426  */
 427
 428 isc_result_t
 429 isc_socket_create(isc_socketmgr_t *manager,
 430                   int pf,
 431                   isc_sockettype_t type,
 432                   isc_socket_t **socketp);
 433 /*%<
 434  * Create a new 'type' socket managed by 'manager'.
 435  *
 436  * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate()
 437  * rather than isc_socket_create().
 438  *
 439  * Note:
 440  *
 441  *\li   'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
 442  *
 443  * Requires:
 444  *
 445  *\li   'manager' is a valid manager
 446  *
 447  *\li   'socketp' is a valid pointer, and *socketp == NULL
 448  *
 449  *\li   'type' is not isc_sockettype_fdwatch
 450  *
 451  * Ensures:
 452  *
 453  *      '*socketp' is attached to the newly created socket
 454  *
 455  * Returns:
 456  *
 457  *\li   #ISC_R_SUCCESS
 458  *\li   #ISC_R_NOMEMORY
 459  *\li   #ISC_R_NORESOURCES
 460  *\li   #ISC_R_UNEXPECTED
 461  */
 462
 463 isc_result_t
 464 isc_socket_dup(isc_socket_t *sock0, isc_socket_t **socketp);
 465 /*%<
 466  * Duplicate an existing socket, reusing its file descriptor.
 467  */
 468
 469 void
 470 isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
 471                   unsigned int how);
 472 /*%<
 473  * Cancel pending I/O of the type specified by "how".
 474  *
 475  * Note: if "task" is NULL, then the cancel applies to all tasks using the
 476  * socket.
 477  *
 478  * Requires:
 479  *
 480  * \li  "socket" is a valid socket
 481  *
 482  * \li  "task" is NULL or a valid task
 483  *
 484  * "how" is a bitmask describing the type of cancelation to perform.
 485  * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
 486  * socket.
 487  *
 488  * \li ISC_SOCKCANCEL_RECV:
 489  *      Cancel pending isc_socket_recv() calls.
 490  *
 491  * \li ISC_SOCKCANCEL_SEND:
 492  *      Cancel pending isc_socket_send() and isc_socket_sendto() calls.
 493  *
 494  * \li ISC_SOCKCANCEL_ACCEPT:
 495  *      Cancel pending isc_socket_accept() calls.
 496  *
 497  * \li ISC_SOCKCANCEL_CONNECT:
 498  *      Cancel pending isc_socket_connect() call.
 499  */
 500
 501 void
 502 isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
 503 /*%<
 504  * Shutdown 'socket' according to 'how'.
 505  *
 506  * Requires:
 507  *
 508  * \li  'socket' is a valid socket.
 509  *
 510  * \li  'task' is NULL or is a valid task.
 511  *
 512  * \li  If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then
 513  *
 514  *              The read queue must be empty.
 515  *
 516  *              No further read requests may be made.
 517  *
 518  * \li  If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
 519  *
 520  *              The write queue must be empty.
 521  *
 522  *              No further write requests may be made.
 523  */
 524
 525 void
 526 isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
 527 /*%<
 528  * Attach *socketp to socket.
 529  *
 530  * Requires:
 531  *
 532  * \li  'socket' is a valid socket.
 533  *
 534  * \li  'socketp' points to a NULL socket.
 535  *
 536  * Ensures:
 537  *
 538  * \li  *socketp is attached to socket.
 539  */
 540
 541 void
 542 isc_socket_detach(isc_socket_t **socketp);
 543 /*%<
 544  * Detach *socketp from its socket.
 545  *
 546  * Requires:
 547  *
 548  * \li  'socketp' points to a valid socket.
 549  *
 550  * \li  If '*socketp' is the last reference to the socket,
 551  *      then:
 552  *
 553  *              There must be no pending I/O requests.
 554  *
 555  * Ensures:
 556  *
 557  * \li  *socketp is NULL.
 558  *
 559  * \li  If '*socketp' is the last reference to the socket,
 560  *      then:
 561  *
 562  *              The socket will be shutdown (both reading and writing)
 563  *              for all tasks.
 564  *
 565  *              All resources used by the socket have been freed
 566  */
 567
 568 isc_result_t
 569 isc_socket_open(isc_socket_t *sock);
 570 /*%<
 571  * Open a new socket file descriptor of the given socket structure.  It simply
 572  * opens a new descriptor; all of the other parameters including the socket
 573  * type are inherited from the existing socket.  This function is provided to
 574  * avoid overhead of destroying and creating sockets when many short-lived
 575  * sockets are frequently opened and closed.  When the efficiency is not an
 576  * issue, it should be safer to detach the unused socket and re-create a new
 577  * one.  This optimization may not be available for some systems, in which
 578  * case this function will return ISC_R_NOTIMPLEMENTED and must not be used.
 579  *
 580  * isc_socket_open() should not be called on sockets created by
 581  * isc_socket_fdwatchcreate().
 582  *
 583  * Requires:
 584  *
 585  * \li  there must be no other reference to this socket.
 586  *
 587  * \li  'socket' is a valid and previously closed by isc_socket_close()
 588  *
 589  * \li  'sock->type' is not isc_sockettype_fdwatch
 590  *
 591  * Returns:
 592  *      Same as isc_socket_create().
 593  * \li  ISC_R_NOTIMPLEMENTED
 594  */
 595
 596 isc_result_t
 597 isc_socket_close(isc_socket_t *sock);
 598 /*%<
 599  * Close a socket file descriptor of the given socket structure.  This function
 600  * is provided as an alternative to destroying an unused socket when overhead
 601  * destroying/re-creating sockets can be significant, and is expected to be
 602  * used with isc_socket_open().  This optimization may not be available for some
 603  * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and
 604  * must not be used.
 605  *
 606  * isc_socket_close() should not be called on sockets created by
 607  * isc_socket_fdwatchcreate().
 608  *
 609  * Requires:
 610  *
 611  * \li  The socket must have a valid descriptor.
 612  *
 613  * \li  There must be no other reference to this socket.
 614  *
 615  * \li  There must be no pending I/O requests.
 616  *
 617  * \li  'sock->type' is not isc_sockettype_fdwatch
 618  *
 619  * Returns:
 620  * \li  #ISC_R_NOTIMPLEMENTED
 621  */
 622
 623 isc_result_t
 624 isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
 625                 unsigned int options);
 626 /*%<
 627  * Bind 'socket' to '*addressp'.
 628  *
 629  * Requires:
 630  *
 631  * \li  'socket' is a valid socket
 632  *
 633  * \li  'addressp' points to a valid isc_sockaddr.
 634  *
 635  * Returns:
 636  *
 637  * \li  ISC_R_SUCCESS
 638  * \li  ISC_R_NOPERM
 639  * \li  ISC_R_ADDRNOTAVAIL
 640  * \li  ISC_R_ADDRINUSE
 641  * \li  ISC_R_BOUND
 642  * \li  ISC_R_UNEXPECTED
 643  */
 644
 645 isc_result_t
 646 isc_socket_filter(isc_socket_t *sock, const char *filter);
 647 /*%<
 648  * Inform the kernel that it should perform accept filtering.
 649  * If filter is NULL the current filter will be removed.:w
 650  */
 651
 652 isc_result_t
 653 isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
 654 /*%<
 655  * Set listen mode on the socket.  After this call, the only function that
 656  * can be used (other than attach and detach) is isc_socket_accept().
 657  *
 658  * Notes:
 659  *
 660  * \li  'backlog' is as in the UNIX system call listen() and may be
 661  *      ignored by non-UNIX implementations.
 662  *
 663  * \li  If 'backlog' is zero, a reasonable system default is used, usually
 664  *      SOMAXCONN.
 665  *
 666  * Requires:
 667  *
 668  * \li  'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
 669  *
 670  * Returns:
 671  *
 672  * \li  ISC_R_SUCCESS
 673  * \li  ISC_R_UNEXPECTED
 674  */
 675
 676 isc_result_t
 677 isc_socket_accept(isc_socket_t *sock,
 678                   isc_task_t *task, isc_taskaction_t action, const void *arg);
 679 /*%<
 680  * Queue accept event.  When a new connection is received, the task will
 681  * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
 682  * socket.  The new socket structure is sent inside the isc_socket_newconnev_t
 683  * event type, and is attached to the task 'task'.
 684  *
 685  * REQUIRES:
 686  * \li  'socket' is a valid TCP socket that isc_socket_listen() was called
 687  *      on.
 688  *
 689  * \li  'task' is a valid task
 690  *
 691  * \li  'action' is a valid action
 692  *
 693  * RETURNS:
 694  * \li  ISC_R_SUCCESS
 695  * \li  ISC_R_NOMEMORY
 696  * \li  ISC_R_UNEXPECTED
 697  */
 698
 699 isc_result_t
 700 isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
 701                    isc_task_t *task, isc_taskaction_t action,
 702                    const void *arg);
 703 /*%<
 704  * Connect 'socket' to peer with address *saddr.  When the connection
 705  * succeeds, or when an error occurs, a CONNECT event with action 'action'
 706  * and arg 'arg' will be posted to the event queue for 'task'.
 707  *
 708  * Requires:
 709  *
 710  * \li  'socket' is a valid TCP socket
 711  *
 712  * \li  'addressp' points to a valid isc_sockaddr
 713  *
 714  * \li  'task' is a valid task
 715  *
 716  * \li  'action' is a valid action
 717  *
 718  * Returns:
 719  *
 720  * \li  ISC_R_SUCCESS
 721  * \li  ISC_R_NOMEMORY
 722  * \li  ISC_R_UNEXPECTED
 723  *
 724  * Posted event's result code:
 725  *
 726  * \li  ISC_R_SUCCESS
 727  * \li  ISC_R_TIMEDOUT
 728  * \li  ISC_R_CONNREFUSED
 729  * \li  ISC_R_NETUNREACH
 730  * \li  ISC_R_UNEXPECTED
 731  */
 732
 733 isc_result_t
 734 isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
 735 /*%<
 736  * Get the name of the peer connected to 'socket'.
 737  *
 738  * Requires:
 739  *
 740  * \li  'socket' is a valid TCP socket.
 741  *
 742  * Returns:
 743  *
 744  * \li  ISC_R_SUCCESS
 745  * \li  ISC_R_TOOSMALL
 746  * \li  ISC_R_UNEXPECTED
 747  */
 748
 749 isc_result_t
 750 isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
 751 /*%<
 752  * Get the name of 'socket'.
 753  *
 754  * Requires:
 755  *
 756  * \li  'socket' is a valid socket.
 757  *
 758  * Returns:
 759  *
 760  * \li  ISC_R_SUCCESS
 761  * \li  ISC_R_TOOSMALL
 762  * \li  ISC_R_UNEXPECTED
 763  */
 764
 765 /*@{*/
 766 isc_result_t
 767 isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
 768                 unsigned int minimum,
 769                 isc_task_t *task, isc_taskaction_t action, const void *arg);
 770 isc_result_t
 771 isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
 772                  unsigned int minimum,
 773                  isc_task_t *task, isc_taskaction_t action, const void *arg);
 774
 775 isc_result_t
 776 isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
 777                  unsigned int minimum, isc_task_t *task,
 778                  isc_socketevent_t *event, unsigned int flags);
 779
 780 /*!
 781  * Receive from 'socket', storing the results in region.
 782  *
 783  * Notes:
 784  *
 785  *\li   Let 'length' refer to the length of 'region' or to the sum of all
 786  *      available regions in the list of buffers '*buflist'.
 787  *
 788  *\li   If 'minimum' is non-zero and at least that many bytes are read,
 789  *      the completion event will be posted to the task 'task.'  If minimum
 790  *      is zero, the exact number of bytes requested in the region must
 791  *      be read for an event to be posted.  This only makes sense for TCP
 792  *      connections, and is always set to 1 byte for UDP.
 793  *
 794  *\li   The read will complete when the desired number of bytes have been
 795  *      read, if end-of-input occurs, or if an error occurs.  A read done
 796  *      event with the given 'action' and 'arg' will be posted to the
 797  *      event queue of 'task'.
 798  *
 799  *\li   The caller may not modify 'region', the buffers which are passed
 800  *      into this function, or any data they refer to until the completion
 801  *      event is received.
 802  *
 803  *\li   For isc_socket_recvv():
 804  *      On successful completion, '*buflist' will be empty, and the list of
 805  *      all buffers will be returned in the done event's 'bufferlist'
 806  *      member.  On error return, '*buflist' will be unchanged.
 807  *
 808  *\li   For isc_socket_recv2():
 809  *      'event' is not NULL, and the non-socket specific fields are
 810  *      expected to be initialized.
 811  *
 812  *\li   For isc_socket_recv2():
 813  *      The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE.  If
 814  *      set and the operation completes, the return value will be
 815  *      ISC_R_SUCCESS and the event will be filled in and not sent.  If the
 816  *      operation does not complete, the return value will be
 817  *      ISC_R_INPROGRESS and the event will be sent when the operation
 818  *      completes.
 819  *
 820  * Requires:
 821  *
 822  *\li   'socket' is a valid, bound socket.
 823  *
 824  *\li   For isc_socket_recv():
 825  *      'region' is a valid region
 826  *
 827  *\li   For isc_socket_recvv():
 828  *      'buflist' is non-NULL, and '*buflist' contain at least one buffer.
 829  *
 830  *\li   'task' is a valid task
 831  *
 832  *\li   For isc_socket_recv() and isc_socket_recvv():
 833  *      action != NULL and is a valid action
 834  *
 835  *\li   For isc_socket_recv2():
 836  *      event != NULL
 837  *
 838  * Returns:
 839  *
 840  *\li   #ISC_R_SUCCESS
 841  *\li   #ISC_R_INPROGRESS
 842  *\li   #ISC_R_NOMEMORY
 843  *\li   #ISC_R_UNEXPECTED
 844  *
 845  * Event results:
 846  *
 847  *\li   #ISC_R_SUCCESS
 848  *\li   #ISC_R_UNEXPECTED
 849  *\li   XXX needs other net-type errors
 850  */
 851 /*@}*/
 852
 853 /*@{*/
 854 isc_result_t
 855 isc_socket_send(isc_socket_t *sock, isc_region_t *region,
 856                 isc_task_t *task, isc_taskaction_t action, const void *arg);
 857 isc_result_t
 858 isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
 859                   isc_task_t *task, isc_taskaction_t action, const void *arg,
 860                   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
 861 isc_result_t
 862 isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
 863                  isc_task_t *task, isc_taskaction_t action, const void *arg);
 864 isc_result_t
 865 isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
 866                    isc_task_t *task, isc_taskaction_t action, const void *arg,
 867                    isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
 868 isc_result_t
 869 isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
 870                    isc_task_t *task,
 871                    isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
 872                    isc_socketevent_t *event, unsigned int flags);
 873
 874 /*!
 875  * Send the contents of 'region' to the socket's peer.
 876  *
 877  * Notes:
 878  *
 879  *\li   Shutting down the requestor's task *may* result in any
 880  *      still pending writes being dropped or completed, depending on the
 881  *      underlying OS implementation.
 882  *
 883  *\li   If 'action' is NULL, then no completion event will be posted.
 884  *
 885  *\li   The caller may not modify 'region', the buffers which are passed
 886  *      into this function, or any data they refer to until the completion
 887  *      event is received.
 888  *
 889  *\li   For isc_socket_sendv() and isc_socket_sendtov():
 890  *      On successful completion, '*buflist' will be empty, and the list of
 891  *      all buffers will be returned in the done event's 'bufferlist'
 892  *      member.  On error return, '*buflist' will be unchanged.
 893  *
 894  *\li   For isc_socket_sendto2():
 895  *      'event' is not NULL, and the non-socket specific fields are
 896  *      expected to be initialized.
 897  *
 898  *\li   For isc_socket_sendto2():
 899  *      The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
 900  *      and ISC_SOCKFLAG_NORETRY.
 901  *
 902  *\li   If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
 903  *      return value will be ISC_R_SUCCESS and the event will be filled
 904  *      in and not sent.  If the operation does not complete, the return
 905  *      value will be ISC_R_INPROGRESS and the event will be sent when
 906  *      the operation completes.
 907  *
 908  *\li   ISC_SOCKFLAG_NORETRY can only be set for UDP sockets.  If set
 909  *      and the send operation fails due to a transient error, the send
 910  *      will not be retried and the error will be indicated in the event.
 911  *      Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
 912  *      to specify a region that is allocated on the stack.
 913  *
 914  * Requires:
 915  *
 916  *\li   'socket' is a valid, bound socket.
 917  *
 918  *\li   For isc_socket_send():
 919  *      'region' is a valid region
 920  *
 921  *\li   For isc_socket_sendv() and isc_socket_sendtov():
 922  *      'buflist' is non-NULL, and '*buflist' contain at least one buffer.
 923  *
 924  *\li   'task' is a valid task
 925  *
 926  *\li   For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and
 927  *      isc_socket_sendto():
 928  *      action == NULL or is a valid action
 929  *
 930  *\li   For isc_socket_sendto2():
 931  *      event != NULL
 932  *
 933  * Returns:
 934  *
 935  *\li   #ISC_R_SUCCESS
 936  *\li   #ISC_R_INPROGRESS
 937  *\li   #ISC_R_NOMEMORY
 938  *\li   #ISC_R_UNEXPECTED
 939  *
 940  * Event results:
 941  *
 942  *\li   #ISC_R_SUCCESS
 943  *\li   #ISC_R_UNEXPECTED
 944  *\li   XXX needs other net-type errors
 945  */
 946 /*@}*/
 947
 948 isc_result_t
 949 isc_socketmgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx,
 950                           isc_socketmgr_t **managerp);
 951
 952 isc_result_t
 953 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
 954
 955 isc_result_t
 956 isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp,
 957                       unsigned int maxsocks);
 958 /*%<
 959  * Create a socket manager.  If "maxsocks" is non-zero, it specifies the
 960  * maximum number of sockets that the created manager should handle.
 961  * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with
 962  * "maxsocks" being zero.
 963  * isc_socketmgr_createinctx() also associates the new manager with the
 964  * specified application context.
 965  *
 966  * Notes:
 967  *
 968  *\li   All memory will be allocated in memory context 'mctx'.
 969  *
 970  * Requires:
 971  *
 972  *\li   'mctx' is a valid memory context.
 973  *
 974  *\li   'managerp' points to a NULL isc_socketmgr_t.
 975  *
 976  *\li   'actx' is a valid application context (for createinctx()).
 977  *
 978  * Ensures:
 979  *
 980  *\li   '*managerp' is a valid isc_socketmgr_t.
 981  *
 982  * Returns:
 983  *
 984  *\li   #ISC_R_SUCCESS
 985  *\li   #ISC_R_NOMEMORY
 986  *\li   #ISC_R_UNEXPECTED
 987  *\li   #ISC_R_NOTIMPLEMENTED
 988  */
 989
 990 isc_result_t
 991 isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp);
 992 /*%<
 993  * Returns in "*nsockp" the maximum number of sockets this manager may open.
 994  *
 995  * Requires:
 996  *
 997  *\li   '*manager' is a valid isc_socketmgr_t.
 998  *\li   'nsockp' is not NULL.
 999  *
1000  * Returns:
1001  *
1002  *\li   #ISC_R_SUCCESS
1003  *\li   #ISC_R_NOTIMPLEMENTED
1004  */
1005
1006 void
1007 isc_socketmgr_setstats(isc_socketmgr_t *manager, isc_stats_t *stats);
1008 /*%<
1009  * Set a general socket statistics counter set 'stats' for 'manager'.
1010  *
1011  * Requires:
1012  * \li  'manager' is valid, hasn't opened any socket, and doesn't have
1013  *      stats already set.
1014  *
1015  *\li   stats is a valid statistics supporting socket statistics counters
1016  *      (see above).
1017  */
1018
1019 void
1020 isc_socketmgr_destroy(isc_socketmgr_t **managerp);
1021 /*%<
1022  * Destroy a socket manager.
1023  *
1024  * Notes:
1025  *
1026  *\li   This routine blocks until there are no sockets left in the manager,
1027  *      so if the caller holds any socket references using the manager, it
1028  *      must detach them before calling isc_socketmgr_destroy() or it will
1029  *      block forever.
1030  *
1031  * Requires:
1032  *
1033  *\li   '*managerp' is a valid isc_socketmgr_t.
1034  *
1035  *\li   All sockets managed by this manager are fully detached.
1036  *
1037  * Ensures:
1038  *
1039  *\li   *managerp == NULL
1040  *
1041  *\li   All resources used by the manager have been freed.
1042  */
1043
1044 isc_sockettype_t
1045 isc_socket_gettype(isc_socket_t *sock);
1046 /*%<
1047  * Returns the socket type for "sock."
1048  *
1049  * Requires:
1050  *
1051  *\li   "sock" is a valid socket.
1052  */
1053
1054 /*@{*/
1055 isc_boolean_t
1056 isc_socket_isbound(isc_socket_t *sock);
1057
1058 void
1059 isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
1060 /*%<
1061  * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
1062  * option if the host OS supports this option.
1063  *
1064  * Requires:
1065  *\li   'sock' is a valid socket.
1066  */
1067 /*@}*/
1068
1069 void
1070 isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);
1071
1072 /*%<
1073  * Cleanup UNIX domain sockets in the file-system.  If 'active' is true
1074  * then just unlink the socket.  If 'active' is false try to determine
1075  * if there is a listener of the socket or not.  If no listener is found
1076  * then unlink socket.
1077  *
1078  * Prior to unlinking the path is tested to see if it a socket.
1079  *
1080  * Note: there are a number of race conditions which cannot be avoided
1081  *       both in the filesystem and any application using UNIX domain
1082  *       sockets (e.g. socket is tested between bind() and listen(),
1083  *       the socket is deleted and replaced in the file-system between
1084  *       stat() and unlink()).
1085  */
1086
1087 isc_result_t
1088 isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
1089                     isc_uint32_t owner, isc_uint32_t group);
1090 /*%<
1091  * Set ownership and file permissions on the UNIX domain socket.
1092  *
1093  * Note: On Solaris and SunOS this secures the directory containing
1094  *       the socket as Solaris and SunOS do not honour the filesystem
1095  *       permissions on the socket.
1096  *
1097  * Requires:
1098  * \li  'sockaddr' to be a valid UNIX domain sockaddr.
1099  *
1100  * Returns:
1101  * \li  #ISC_R_SUCCESS
1102  * \li  #ISC_R_FAILURE
1103  */
1104
1105 void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag);
1106 /*%<
1107  * Set the name and optional tag for a socket.  This allows tracking of the
1108  * owner or purpose for this socket, and is useful for tracing and statistics
1109  * reporting.
1110  */
1111
1112 const char *isc_socket_getname(isc_socket_t *socket);
1113 /*%<
1114  * Get the name associated with a socket, if any.
1115  */
1116
1117 void *isc_socket_gettag(isc_socket_t *socket);
1118 /*%<
1119  * Get the tag associated with a socket, if any.
1120  */
1121
1122 int isc_socket_getfd(isc_socket_t *socket);
1123 /*%<
1124  * Get the file descriptor associated with a socket
1125  */
1126
1127 void
1128 isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
1129 /*%<
1130  * Temporary.  For use by named only.
1131  */
1132
1133 void
1134 isc__socketmgr_maxudp(isc_socketmgr_t *mgr, int maxudp);
1135 /*%<
1136  * Test interface. Drop UDP packet > 'maxudp'.
1137  */
1138
1139 #ifdef HAVE_LIBXML2
1140
1141 int
1142 isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer);
1143 /*%<
1144  * Render internal statistics and other state into the XML document.
1145  */
1146
1147 #endif /* HAVE_LIBXML2 */
1148
1149 #ifdef USE_SOCKETIMPREGISTER
1150 /*%<
1151  * See isc_socketmgr_create() above.
1152  */
1153 typedef isc_result_t
1154 (*isc_socketmgrcreatefunc_t)(isc_mem_t *mctx, isc_socketmgr_t **managerp);
1155
1156 isc_result_t
1157 isc_socket_register(isc_socketmgrcreatefunc_t createfunc);
1158 /*%<
1159  * Register a new socket I/O implementation and add it to the list of
1160  * supported implementations.  This function must be called when a different
1161  * event library is used than the one contained in the ISC library.
1162  */
1163
1164 isc_result_t
1165 isc__socket_register(void);
1166 /*%<
1167  * A short cut function that specifies the socket I/O module in the ISC
1168  * library for isc_socket_register().  An application that uses the ISC library
1169  * usually do not have to care about this function: it would call
1170  * isc_lib_register(), which internally calls this function.
1171  */
1172 #endif /* USE_SOCKETIMPREGISTER */
1173
1174 ISC_LANG_ENDDECLS
1175
1176 #endif /* ISC_SOCKET_H */