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