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

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