2 * Copyright (C) 2004-2006, 2008 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2002 Internet Software Consortium.
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.
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.
18 /* $Id: socket.h,v 1.57.18.6.46.4 2008/07/23 23:16:43 marka Exp $ */
21 #define ISC_SOCKET_H 1
28 * \brief Provides TCP and UDP sockets for network I/O. The sockets are event
29 * sources in the task system.
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.
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.
44 * No anticipated impact.
50 * No anticipated impact.
61 #include <isc/types.h>
62 #include <isc/event.h>
63 #include <isc/eventclass.h>
65 #include <isc/region.h>
66 #include <isc/sockaddr.h>
75 * Maximum number of buffers in a scatter/gather read/write. The operating
76 * system in use must support at least this number (plus one on some.)
78 #define ISC_SOCKET_MAXSCATTERGATHER 8
81 * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling
82 * bind() if a non zero port is specified (AF_INET and AF_INET6).
84 #define ISC_SOCKET_REUSEADDRESS 0x01U
90 struct isc_socketevent {
91 ISC_EVENT_COMMON(isc_socketevent_t);
92 isc_result_t result; /*%< OK, EOF, whatever else */
93 unsigned int minimum; /*%< minimum i/o for event */
94 unsigned int n; /*%< bytes read or written */
95 unsigned int offset; /*%< offset into buffer list */
96 isc_region_t region; /*%< for single-buffer i/o */
97 isc_bufferlist_t bufferlist; /*%< list of buffers */
98 isc_sockaddr_t address; /*%< source address */
99 isc_time_t timestamp; /*%< timestamp of packet recv */
100 struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */
101 isc_uint32_t attributes; /*%< see below */
102 isc_eventdestructor_t destroy; /*%< original destructor */
105 typedef struct isc_socket_newconnev isc_socket_newconnev_t;
106 struct isc_socket_newconnev {
107 ISC_EVENT_COMMON(isc_socket_newconnev_t);
108 isc_socket_t * newsocket;
109 isc_result_t result; /*%< OK, EOF, whatever else */
110 isc_sockaddr_t address; /*%< source address */
113 typedef struct isc_socket_connev isc_socket_connev_t;
114 struct isc_socket_connev {
115 ISC_EVENT_COMMON(isc_socket_connev_t);
116 isc_result_t result; /*%< OK, EOF, whatever else */
121 * _ATTACHED: Internal use only.
122 * _TRUNC: Packet was truncated on receive.
123 * _CTRUNC: Packet control information was truncated. This can
124 * indicate that the packet is not complete, even though
125 * all the data is valid.
126 * _TIMESTAMP: The timestamp member is valid.
127 * _PKTINFO: The pktinfo member is valid.
128 * _MULTICAST: The UDP packet was received via a multicast transmission.
130 #define ISC_SOCKEVENTATTR_ATTACHED 0x80000000U /* internal */
131 #define ISC_SOCKEVENTATTR_TRUNC 0x00800000U /* public */
132 #define ISC_SOCKEVENTATTR_CTRUNC 0x00400000U /* public */
133 #define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */
134 #define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */
135 #define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */
138 #define ISC_SOCKEVENT_ANYEVENT (0)
139 #define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1)
140 #define ISC_SOCKEVENT_SENDDONE (ISC_EVENTCLASS_SOCKET + 2)
141 #define ISC_SOCKEVENT_NEWCONN (ISC_EVENTCLASS_SOCKET + 3)
142 #define ISC_SOCKEVENT_CONNECT (ISC_EVENTCLASS_SOCKET + 4)
147 #define ISC_SOCKEVENT_INTR (ISC_EVENTCLASS_SOCKET + 256)
148 #define ISC_SOCKEVENT_INTW (ISC_EVENTCLASS_SOCKET + 257)
151 isc_sockettype_udp = 1,
152 isc_sockettype_tcp = 2,
153 isc_sockettype_unix = 3
158 * How a socket should be shutdown in isc_socket_shutdown() calls.
160 #define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */
161 #define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */
162 #define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */
167 * What I/O events to cancel in isc_socket_cancel() calls.
169 #define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */
170 #define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */
171 #define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */
172 #define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */
173 #define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */
178 * Flags for isc_socket_send() and isc_socket_recv() calls.
180 #define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */
181 #define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */
185 *** Socket and Socket Manager Functions
187 *** Note: all Ensures conditions apply only if the result is success for
188 *** those functions which return an isc_result.
192 isc_socket_create(isc_socketmgr_t *manager,
194 isc_sockettype_t type,
195 isc_socket_t **socketp);
197 * Create a new 'type' socket managed by 'manager'.
201 *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
205 *\li 'manager' is a valid manager
207 *\li 'socketp' is a valid pointer, and *socketp == NULL
211 * '*socketp' is attached to the newly created socket
217 *\li #ISC_R_NORESOURCES
218 *\li #ISC_R_UNEXPECTED
222 isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
225 * Cancel pending I/O of the type specified by "how".
227 * Note: if "task" is NULL, then the cancel applies to all tasks using the
232 * \li "socket" is a valid socket
234 * \li "task" is NULL or a valid task
236 * "how" is a bitmask describing the type of cancelation to perform.
237 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
240 * \li ISC_SOCKCANCEL_RECV:
241 * Cancel pending isc_socket_recv() calls.
243 * \li ISC_SOCKCANCEL_SEND:
244 * Cancel pending isc_socket_send() and isc_socket_sendto() calls.
246 * \li ISC_SOCKCANCEL_ACCEPT:
247 * Cancel pending isc_socket_accept() calls.
249 * \li ISC_SOCKCANCEL_CONNECT:
250 * Cancel pending isc_socket_connect() call.
254 isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
256 * Shutdown 'socket' according to 'how'.
260 * \li 'socket' is a valid socket.
262 * \li 'task' is NULL or is a valid task.
264 * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then
266 * The read queue must be empty.
268 * No further read requests may be made.
270 * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
272 * The write queue must be empty.
274 * No further write requests may be made.
278 isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
280 * Attach *socketp to socket.
284 * \li 'socket' is a valid socket.
286 * \li 'socketp' points to a NULL socket.
290 * \li *socketp is attached to socket.
294 isc_socket_detach(isc_socket_t **socketp);
296 * Detach *socketp from its socket.
300 * \li 'socketp' points to a valid socket.
302 * \li If '*socketp' is the last reference to the socket,
305 * There must be no pending I/O requests.
309 * \li *socketp is NULL.
311 * \li If '*socketp' is the last reference to the socket,
314 * The socket will be shutdown (both reading and writing)
317 * All resources used by the socket have been freed
321 isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
322 unsigned int options);
324 * Bind 'socket' to '*addressp'.
328 * \li 'socket' is a valid socket
330 * \li 'addressp' points to a valid isc_sockaddr.
336 * \li ISC_R_ADDRNOTAVAIL
337 * \li ISC_R_ADDRINUSE
339 * \li ISC_R_UNEXPECTED
343 isc_socket_filter(isc_socket_t *sock, const char *filter);
345 * Inform the kernel that it should perform accept filtering.
346 * If filter is NULL the current filter will be removed.:w
350 isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
352 * Set listen mode on the socket. After this call, the only function that
353 * can be used (other than attach and detach) is isc_socket_accept().
357 * \li 'backlog' is as in the UNIX system call listen() and may be
358 * ignored by non-UNIX implementations.
360 * \li If 'backlog' is zero, a reasonable system default is used, usually
365 * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
370 * \li ISC_R_UNEXPECTED
374 isc_socket_accept(isc_socket_t *sock,
375 isc_task_t *task, isc_taskaction_t action, const void *arg);
377 * Queue accept event. When a new connection is received, the task will
378 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
379 * socket. The new socket structure is sent inside the isc_socket_newconnev_t
380 * event type, and is attached to the task 'task'.
383 * \li 'socket' is a valid TCP socket that isc_socket_listen() was called
386 * \li 'task' is a valid task
388 * \li 'action' is a valid action
393 * \li ISC_R_UNEXPECTED
397 isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
398 isc_task_t *task, isc_taskaction_t action,
401 * Connect 'socket' to peer with address *saddr. When the connection
402 * succeeds, or when an error occurs, a CONNECT event with action 'action'
403 * and arg 'arg' will be posted to the event queue for 'task'.
407 * \li 'socket' is a valid TCP socket
409 * \li 'addressp' points to a valid isc_sockaddr
411 * \li 'task' is a valid task
413 * \li 'action' is a valid action
419 * \li ISC_R_UNEXPECTED
421 * Posted event's result code:
425 * \li ISC_R_CONNREFUSED
426 * \li ISC_R_NETUNREACH
427 * \li ISC_R_UNEXPECTED
431 isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
433 * Get the name of the peer connected to 'socket'.
437 * \li 'socket' is a valid TCP socket.
443 * \li ISC_R_UNEXPECTED
447 isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
449 * Get the name of 'socket'.
453 * \li 'socket' is a valid socket.
459 * \li ISC_R_UNEXPECTED
464 isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
465 unsigned int minimum,
466 isc_task_t *task, isc_taskaction_t action, const void *arg);
468 isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
469 unsigned int minimum,
470 isc_task_t *task, isc_taskaction_t action, const void *arg);
473 isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
474 unsigned int minimum, isc_task_t *task,
475 isc_socketevent_t *event, unsigned int flags);
478 * Receive from 'socket', storing the results in region.
482 *\li Let 'length' refer to the length of 'region' or to the sum of all
483 * available regions in the list of buffers '*buflist'.
485 *\li If 'minimum' is non-zero and at least that many bytes are read,
486 * the completion event will be posted to the task 'task.' If minimum
487 * is zero, the exact number of bytes requested in the region must
488 * be read for an event to be posted. This only makes sense for TCP
489 * connections, and is always set to 1 byte for UDP.
491 *\li The read will complete when the desired number of bytes have been
492 * read, if end-of-input occurs, or if an error occurs. A read done
493 * event with the given 'action' and 'arg' will be posted to the
494 * event queue of 'task'.
496 *\li The caller may not modify 'region', the buffers which are passed
497 * into this function, or any data they refer to until the completion
500 *\li For isc_socket_recvv():
501 * On successful completion, '*buflist' will be empty, and the list of
502 * all buffers will be returned in the done event's 'bufferlist'
503 * member. On error return, '*buflist' will be unchanged.
505 *\li For isc_socket_recv2():
506 * 'event' is not NULL, and the non-socket specific fields are
507 * expected to be initialized.
509 *\li For isc_socket_recv2():
510 * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If
511 * set and the operation completes, the return value will be
512 * ISC_R_SUCCESS and the event will be filled in and not sent. If the
513 * operation does not complete, the return value will be
514 * ISC_R_INPROGRESS and the event will be sent when the operation
519 *\li 'socket' is a valid, bound socket.
521 *\li For isc_socket_recv():
522 * 'region' is a valid region
524 *\li For isc_socket_recvv():
525 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer.
527 *\li 'task' is a valid task
529 *\li For isc_socket_recv() and isc_socket_recvv():
530 * action != NULL and is a valid action
532 *\li For isc_socket_recv2():
538 *\li #ISC_R_INPROGRESS
540 *\li #ISC_R_UNEXPECTED
545 *\li #ISC_R_UNEXPECTED
546 *\li XXX needs other net-type errors
552 isc_socket_send(isc_socket_t *sock, isc_region_t *region,
553 isc_task_t *task, isc_taskaction_t action, const void *arg);
555 isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
556 isc_task_t *task, isc_taskaction_t action, const void *arg,
557 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
559 isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
560 isc_task_t *task, isc_taskaction_t action, const void *arg);
562 isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
563 isc_task_t *task, isc_taskaction_t action, const void *arg,
564 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
566 isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
568 isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
569 isc_socketevent_t *event, unsigned int flags);
572 * Send the contents of 'region' to the socket's peer.
576 *\li Shutting down the requestor's task *may* result in any
577 * still pending writes being dropped or completed, depending on the
578 * underlying OS implementation.
580 *\li If 'action' is NULL, then no completion event will be posted.
582 *\li The caller may not modify 'region', the buffers which are passed
583 * into this function, or any data they refer to until the completion
586 *\li For isc_socket_sendv() and isc_socket_sendtov():
587 * On successful completion, '*buflist' will be empty, and the list of
588 * all buffers will be returned in the done event's 'bufferlist'
589 * member. On error return, '*buflist' will be unchanged.
591 *\li For isc_socket_sendto2():
592 * 'event' is not NULL, and the non-socket specific fields are
593 * expected to be initialized.
595 *\li For isc_socket_sendto2():
596 * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
597 * and ISC_SOCKFLAG_NORETRY.
599 *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
600 * return value will be ISC_R_SUCCESS and the event will be filled
601 * in and not sent. If the operation does not complete, the return
602 * value will be ISC_R_INPROGRESS and the event will be sent when
603 * the operation completes.
605 *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set
606 * and the send operation fails due to a transient error, the send
607 * will not be retried and the error will be indicated in the event.
608 * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
609 * to specify a region that is allocated on the stack.
613 *\li 'socket' is a valid, bound socket.
615 *\li For isc_socket_send():
616 * 'region' is a valid region
618 *\li For isc_socket_sendv() and isc_socket_sendtov():
619 * 'buflist' is non-NULL, and '*buflist' contain at least one buffer.
621 *\li 'task' is a valid task
623 *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and
624 * isc_socket_sendto():
625 * action == NULL or is a valid action
627 *\li For isc_socket_sendto2():
633 *\li #ISC_R_INPROGRESS
635 *\li #ISC_R_UNEXPECTED
640 *\li #ISC_R_UNEXPECTED
641 *\li XXX needs other net-type errors
646 isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
648 * Create a socket manager.
652 *\li All memory will be allocated in memory context 'mctx'.
656 *\li 'mctx' is a valid memory context.
658 *\li 'managerp' points to a NULL isc_socketmgr_t.
662 *\li '*managerp' is a valid isc_socketmgr_t.
668 *\li #ISC_R_UNEXPECTED
672 isc_socketmgr_destroy(isc_socketmgr_t **managerp);
674 * Destroy a socket manager.
678 *\li This routine blocks until there are no sockets left in the manager,
679 * so if the caller holds any socket references using the manager, it
680 * must detach them before calling isc_socketmgr_destroy() or it will
685 *\li '*managerp' is a valid isc_socketmgr_t.
687 *\li All sockets managed by this manager are fully detached.
691 *\li *managerp == NULL
693 *\li All resources used by the manager have been freed.
697 isc_socket_gettype(isc_socket_t *sock);
699 * Returns the socket type for "sock."
703 *\li "sock" is a valid socket.
708 isc_socket_isbound(isc_socket_t *sock);
711 isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
713 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
714 * option if the host OS supports this option.
717 *\li 'sock' is a valid socket.
722 isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);
725 * Cleanup UNIX domain sockets in the file-system. If 'active' is true
726 * then just unlink the socket. If 'active' is false try to determine
727 * if there is a listener of the socket or not. If no listener is found
728 * then unlink socket.
730 * Prior to unlinking the path is tested to see if it a socket.
732 * Note: there are a number of race conditions which cannot be avoided
733 * both in the filesystem and any application using UNIX domain
734 * sockets (e.g. socket is tested between bind() and listen(),
735 * the socket is deleted and replaced in the file-system between
736 * stat() and unlink()).
740 isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
741 isc_uint32_t owner, isc_uint32_t group);
743 * Set ownership and file permissions on the UNIX domain socket.
745 * Note: On Solaris and SunOS this secures the directory containing
746 * the socket as Solaris and SunOS do not honour the filesytem
747 * permissions on the socket.
750 * \li 'sockaddr' to be a valid UNIX domain sockaddr.
758 isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
760 * Temporary. For use by named only.
765 #endif /* ISC_SOCKET_H */