PageRenderTime 38ms CodeModel.GetById 12ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 0ms

/lib/isc/include/isc/socket.h

https://bitbucket.org/Gradwell/bind9-clone
C++ Header | 925 lines | 176 code | 62 blank | 687 comment | 0 complexity | b82746e0c7f09cc0944523a25572a459 MD5 | raw file
  1/*
  2 * Copyright (C) 2004-2008  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: socket.h,v 1.72.128.12 2008/09/04 07:58:07 marka Exp $ */
 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
 69ISC_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 *** Types
 89 ***/
 90
 91struct isc_socketevent {
 92	ISC_EVENT_COMMON(isc_socketevent_t);
 93	isc_result_t		result;		/*%< OK, EOF, whatever else */
 94	unsigned int		minimum;	/*%< minimum i/o for event */
 95	unsigned int		n;		/*%< bytes read or written */
 96	unsigned int		offset;		/*%< offset into buffer list */
 97	isc_region_t		region;		/*%< for single-buffer i/o */
 98	isc_bufferlist_t	bufferlist;	/*%< list of buffers */
 99	isc_sockaddr_t		address;	/*%< source address */
100	isc_time_t		timestamp;	/*%< timestamp of packet recv */
101	struct in6_pktinfo	pktinfo;	/*%< ipv6 pktinfo */
102	isc_uint32_t		attributes;	/*%< see below */
103	isc_eventdestructor_t   destroy;	/*%< original destructor */
104};
105
106typedef struct isc_socket_newconnev isc_socket_newconnev_t;
107struct isc_socket_newconnev {
108	ISC_EVENT_COMMON(isc_socket_newconnev_t);
109	isc_socket_t *		newsocket;
110	isc_result_t		result;		/*%< OK, EOF, whatever else */
111	isc_sockaddr_t		address;	/*%< source address */
112};
113
114typedef struct isc_socket_connev isc_socket_connev_t;
115struct isc_socket_connev {
116	ISC_EVENT_COMMON(isc_socket_connev_t);
117	isc_result_t		result;		/*%< OK, EOF, whatever else */
118};
119
120/*@{*/
121/*!
122 * _ATTACHED:	Internal use only.
123 * _TRUNC:	Packet was truncated on receive.
124 * _CTRUNC:	Packet control information was truncated.  This can
125 *		indicate that the packet is not complete, even though
126 *		all the data is valid.
127 * _TIMESTAMP:	The timestamp member is valid.
128 * _PKTINFO:	The pktinfo member is valid.
129 * _MULTICAST:	The UDP packet was received via a multicast transmission.
130 */
131#define ISC_SOCKEVENTATTR_ATTACHED		0x80000000U /* internal */
132#define ISC_SOCKEVENTATTR_TRUNC			0x00800000U /* public */
133#define ISC_SOCKEVENTATTR_CTRUNC		0x00400000U /* public */
134#define ISC_SOCKEVENTATTR_TIMESTAMP		0x00200000U /* public */
135#define ISC_SOCKEVENTATTR_PKTINFO		0x00100000U /* public */
136#define ISC_SOCKEVENTATTR_MULTICAST		0x00080000U /* public */
137/*@}*/
138
139#define ISC_SOCKEVENT_ANYEVENT  (0)
140#define ISC_SOCKEVENT_RECVDONE	(ISC_EVENTCLASS_SOCKET + 1)
141#define ISC_SOCKEVENT_SENDDONE	(ISC_EVENTCLASS_SOCKET + 2)
142#define ISC_SOCKEVENT_NEWCONN	(ISC_EVENTCLASS_SOCKET + 3)
143#define ISC_SOCKEVENT_CONNECT	(ISC_EVENTCLASS_SOCKET + 4)
144
145/*
146 * Internal events.
147 */
148#define ISC_SOCKEVENT_INTR	(ISC_EVENTCLASS_SOCKET + 256)
149#define ISC_SOCKEVENT_INTW	(ISC_EVENTCLASS_SOCKET + 257)
150
151typedef enum {
152	isc_sockettype_udp = 1,
153	isc_sockettype_tcp = 2,
154	isc_sockettype_unix = 3,
155	isc_sockettype_fdwatch = 4
156} isc_sockettype_t;
157
158/*@{*/
159/*!
160 * How a socket should be shutdown in isc_socket_shutdown() calls.
161 */
162#define ISC_SOCKSHUT_RECV	0x00000001	/*%< close read side */
163#define ISC_SOCKSHUT_SEND	0x00000002	/*%< close write side */
164#define ISC_SOCKSHUT_ALL	0x00000003	/*%< close them all */
165/*@}*/
166
167/*@{*/
168/*!
169 * What I/O events to cancel in isc_socket_cancel() calls.
170 */
171#define ISC_SOCKCANCEL_RECV	0x00000001	/*%< cancel recv */
172#define ISC_SOCKCANCEL_SEND	0x00000002	/*%< cancel send */
173#define ISC_SOCKCANCEL_ACCEPT	0x00000004	/*%< cancel accept */
174#define ISC_SOCKCANCEL_CONNECT	0x00000008	/*%< cancel connect */
175#define ISC_SOCKCANCEL_ALL	0x0000000f	/*%< cancel everything */
176/*@}*/
177
178/*@{*/
179/*!
180 * Flags for isc_socket_send() and isc_socket_recv() calls.
181 */
182#define ISC_SOCKFLAG_IMMEDIATE	0x00000001	/*%< send event only if needed */
183#define ISC_SOCKFLAG_NORETRY	0x00000002	/*%< drop failed UDP sends */
184/*@}*/
185
186/*@{*/
187/*!
188 * Flags for fdwatchcreate.
189 */
190#define ISC_SOCKFDWATCH_READ	0x00000001	/*%< watch for readable */
191#define ISC_SOCKFDWATCH_WRITE	0x00000002	/*%< watch for writable */
192/*@}*/
193
194/***
195 *** Socket and Socket Manager Functions
196 ***
197 *** Note: all Ensures conditions apply only if the result is success for
198 *** those functions which return an isc_result.
199 ***/
200
201isc_result_t
202isc_socket_fdwatchcreate(isc_socketmgr_t *manager,
203			 int fd,
204			 int flags,
205			 isc_sockfdwatch_t callback,
206			 void *cbarg,
207			 isc_task_t *task,
208			 isc_socket_t **socketp);
209/*%<
210 * Create a new file descriptor watch socket managed by 'manager'.
211 *
212 * Note:
213 *
214 *\li   'fd' is the already-opened file descriptor.
215 *\li	This function is not available on Windows.
216 *\li	The callback function is called "in-line" - this means the function
217 *	needs to return as fast as possible, as all other I/O will be suspended
218 *	until the callback completes.
219 *
220 * Requires:
221 *
222 *\li	'manager' is a valid manager
223 *
224 *\li	'socketp' is a valid pointer, and *socketp == NULL
225 *
226 *\li	'fd' be opened.
227 *
228 * Ensures:
229 *
230 *	'*socketp' is attached to the newly created fdwatch socket
231 *
232 * Returns:
233 *
234 *\li	#ISC_R_SUCCESS
235 *\li	#ISC_R_NOMEMORY
236 *\li	#ISC_R_NORESOURCES
237 *\li	#ISC_R_UNEXPECTED
238 */
239
240isc_result_t
241isc_socket_create(isc_socketmgr_t *manager,
242		  int pf,
243		  isc_sockettype_t type,
244		  isc_socket_t **socketp);
245/*%<
246 * Create a new 'type' socket managed by 'manager'.
247 *
248 * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate()
249 * rather than isc_socket_create().
250 *
251 * Note:
252 *
253 *\li	'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
254 *
255 * Requires:
256 *
257 *\li	'manager' is a valid manager
258 *
259 *\li	'socketp' is a valid pointer, and *socketp == NULL
260 *
261 *\li	'type' is not isc_sockettype_fdwatch
262 *
263 * Ensures:
264 *
265 *	'*socketp' is attached to the newly created socket
266 *
267 * Returns:
268 *
269 *\li	#ISC_R_SUCCESS
270 *\li	#ISC_R_NOMEMORY
271 *\li	#ISC_R_NORESOURCES
272 *\li	#ISC_R_UNEXPECTED
273 */
274
275void
276isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
277		  unsigned int how);
278/*%<
279 * Cancel pending I/O of the type specified by "how".
280 *
281 * Note: if "task" is NULL, then the cancel applies to all tasks using the
282 * socket.
283 *
284 * Requires:
285 *
286 * \li	"socket" is a valid socket
287 *
288 * \li	"task" is NULL or a valid task
289 *
290 * "how" is a bitmask describing the type of cancelation to perform.
291 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
292 * socket.
293 *
294 * \li ISC_SOCKCANCEL_RECV:
295 *	Cancel pending isc_socket_recv() calls.
296 *
297 * \li ISC_SOCKCANCEL_SEND:
298 *	Cancel pending isc_socket_send() and isc_socket_sendto() calls.
299 *
300 * \li ISC_SOCKCANCEL_ACCEPT:
301 *	Cancel pending isc_socket_accept() calls.
302 *
303 * \li ISC_SOCKCANCEL_CONNECT:
304 *	Cancel pending isc_socket_connect() call.
305 */
306
307void
308isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
309/*%<
310 * Shutdown 'socket' according to 'how'.
311 *
312 * Requires:
313 *
314 * \li	'socket' is a valid socket.
315 *
316 * \li	'task' is NULL or is a valid task.
317 *
318 * \li	If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then
319 *
320 *		The read queue must be empty.
321 *
322 *		No further read requests may be made.
323 *
324 * \li	If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
325 *
326 *		The write queue must be empty.
327 *
328 *		No further write requests may be made.
329 */
330
331void
332isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
333/*%<
334 * Attach *socketp to socket.
335 *
336 * Requires:
337 *
338 * \li	'socket' is a valid socket.
339 *
340 * \li	'socketp' points to a NULL socket.
341 *
342 * Ensures:
343 *
344 * \li	*socketp is attached to socket.
345 */
346
347void
348isc_socket_detach(isc_socket_t **socketp);
349/*%<
350 * Detach *socketp from its socket.
351 *
352 * Requires:
353 *
354 * \li	'socketp' points to a valid socket.
355 *
356 * \li	If '*socketp' is the last reference to the socket,
357 *	then:
358 *
359 *		There must be no pending I/O requests.
360 *
361 * Ensures:
362 *
363 * \li	*socketp is NULL.
364 *
365 * \li	If '*socketp' is the last reference to the socket,
366 *	then:
367 *
368 *		The socket will be shutdown (both reading and writing)
369 *		for all tasks.
370 *
371 *		All resources used by the socket have been freed
372 */
373
374isc_result_t
375isc_socket_open(isc_socket_t *sock);
376/*%<
377 * Open a new socket file descriptor of the given socket structure.  It simply
378 * opens a new descriptor; all of the other parameters including the socket
379 * type are inherited from the existing socket.  This function is provided to
380 * avoid overhead of destroying and creating sockets when many short-lived
381 * sockets are frequently opened and closed.  When the efficiency is not an
382 * issue, it should be safer to detach the unused socket and re-create a new
383 * one.  This optimization may not be available for some systems, in which
384 * case this function will return ISC_R_NOTIMPLEMENTED and must not be used.
385 *
386 * isc_socket_open() should not be called on sockets created by
387 * isc_socket_fdwatchcreate().
388 *
389 * Requires:
390 *
391 * \li	there must be no other reference to this socket.
392 *
393 * \li	'socket' is a valid and previously closed by isc_socket_close()
394 *
395 * \li  'sock->type' is not isc_sockettype_fdwatch
396 *
397 * Returns:
398 *	Same as isc_socket_create().
399 * \li	ISC_R_NOTIMPLEMENTED
400 */
401
402isc_result_t
403isc_socket_close(isc_socket_t *sock);
404/*%<
405 * Close a socket file descriptor of the given socket structure.  This function
406 * is provided as an alternative to destroying an unused socket when overhead
407 * destroying/re-creating sockets can be significant, and is expected to be
408 * used with isc_socket_open().  This optimization may not be available for some
409 * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and
410 * must not be used.
411 *
412 * isc_socket_close() should not be called on sockets created by
413 * isc_socket_fdwatchcreate().
414 *
415 * Requires:
416 *
417 * \li	The socket must have a valid descriptor.
418 *
419 * \li	There must be no other reference to this socket.
420 *
421 * \li	There must be no pending I/O requests.
422 *
423 * \li  'sock->type' is not isc_sockettype_fdwatch
424 *
425 * Returns:
426 * \li	#ISC_R_NOTIMPLEMENTED
427 */
428
429isc_result_t
430isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
431		unsigned int options);
432/*%<
433 * Bind 'socket' to '*addressp'.
434 *
435 * Requires:
436 *
437 * \li	'socket' is a valid socket
438 *
439 * \li	'addressp' points to a valid isc_sockaddr.
440 *
441 * Returns:
442 *
443 * \li	ISC_R_SUCCESS
444 * \li	ISC_R_NOPERM
445 * \li	ISC_R_ADDRNOTAVAIL
446 * \li	ISC_R_ADDRINUSE
447 * \li	ISC_R_BOUND
448 * \li	ISC_R_UNEXPECTED
449 */
450
451isc_result_t
452isc_socket_filter(isc_socket_t *sock, const char *filter);
453/*%<
454 * Inform the kernel that it should perform accept filtering.
455 * If filter is NULL the current filter will be removed.:w
456 */
457
458isc_result_t
459isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
460/*%<
461 * Set listen mode on the socket.  After this call, the only function that
462 * can be used (other than attach and detach) is isc_socket_accept().
463 *
464 * Notes:
465 *
466 * \li	'backlog' is as in the UNIX system call listen() and may be
467 *	ignored by non-UNIX implementations.
468 *
469 * \li	If 'backlog' is zero, a reasonable system default is used, usually
470 *	SOMAXCONN.
471 *
472 * Requires:
473 *
474 * \li	'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
475 *
476 * Returns:
477 *
478 * \li	ISC_R_SUCCESS
479 * \li	ISC_R_UNEXPECTED
480 */
481
482isc_result_t
483isc_socket_accept(isc_socket_t *sock,
484		  isc_task_t *task, isc_taskaction_t action, const void *arg);
485/*%<
486 * Queue accept event.  When a new connection is received, the task will
487 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
488 * socket.  The new socket structure is sent inside the isc_socket_newconnev_t
489 * event type, and is attached to the task 'task'.
490 *
491 * REQUIRES:
492 * \li	'socket' is a valid TCP socket that isc_socket_listen() was called
493 *	on.
494 *
495 * \li	'task' is a valid task
496 *
497 * \li	'action' is a valid action
498 *
499 * RETURNS:
500 * \li	ISC_R_SUCCESS
501 * \li	ISC_R_NOMEMORY
502 * \li	ISC_R_UNEXPECTED
503 */
504
505isc_result_t
506isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
507		   isc_task_t *task, isc_taskaction_t action,
508		   const void *arg);
509/*%<
510 * Connect 'socket' to peer with address *saddr.  When the connection
511 * succeeds, or when an error occurs, a CONNECT event with action 'action'
512 * and arg 'arg' will be posted to the event queue for 'task'.
513 *
514 * Requires:
515 *
516 * \li	'socket' is a valid TCP socket
517 *
518 * \li	'addressp' points to a valid isc_sockaddr
519 *
520 * \li	'task' is a valid task
521 *
522 * \li	'action' is a valid action
523 *
524 * Returns:
525 *
526 * \li	ISC_R_SUCCESS
527 * \li	ISC_R_NOMEMORY
528 * \li	ISC_R_UNEXPECTED
529 *
530 * Posted event's result code:
531 *
532 * \li	ISC_R_SUCCESS
533 * \li	ISC_R_TIMEDOUT
534 * \li	ISC_R_CONNREFUSED
535 * \li	ISC_R_NETUNREACH
536 * \li	ISC_R_UNEXPECTED
537 */
538
539isc_result_t
540isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
541/*%<
542 * Get the name of the peer connected to 'socket'.
543 *
544 * Requires:
545 *
546 * \li	'socket' is a valid TCP socket.
547 *
548 * Returns:
549 *
550 * \li	ISC_R_SUCCESS
551 * \li	ISC_R_TOOSMALL
552 * \li	ISC_R_UNEXPECTED
553 */
554
555isc_result_t
556isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
557/*%<
558 * Get the name of 'socket'.
559 *
560 * Requires:
561 *
562 * \li	'socket' is a valid socket.
563 *
564 * Returns:
565 *
566 * \li	ISC_R_SUCCESS
567 * \li	ISC_R_TOOSMALL
568 * \li	ISC_R_UNEXPECTED
569 */
570
571/*@{*/
572isc_result_t
573isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
574		unsigned int minimum,
575		isc_task_t *task, isc_taskaction_t action, const void *arg);
576isc_result_t
577isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
578		 unsigned int minimum,
579		 isc_task_t *task, isc_taskaction_t action, const void *arg);
580
581isc_result_t
582isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
583		 unsigned int minimum, isc_task_t *task,
584		 isc_socketevent_t *event, unsigned int flags);
585
586/*!
587 * Receive from 'socket', storing the results in region.
588 *
589 * Notes:
590 *
591 *\li	Let 'length' refer to the length of 'region' or to the sum of all
592 *	available regions in the list of buffers '*buflist'.
593 *
594 *\li	If 'minimum' is non-zero and at least that many bytes are read,
595 *	the completion event will be posted to the task 'task.'  If minimum
596 *	is zero, the exact number of bytes requested in the region must
597 * 	be read for an event to be posted.  This only makes sense for TCP
598 *	connections, and is always set to 1 byte for UDP.
599 *
600 *\li	The read will complete when the desired number of bytes have been
601 *	read, if end-of-input occurs, or if an error occurs.  A read done
602 *	event with the given 'action' and 'arg' will be posted to the
603 *	event queue of 'task'.
604 *
605 *\li	The caller may not modify 'region', the buffers which are passed
606 *	into this function, or any data they refer to until the completion
607 *	event is received.
608 *
609 *\li	For isc_socket_recvv():
610 *	On successful completion, '*buflist' will be empty, and the list of
611 *	all buffers will be returned in the done event's 'bufferlist'
612 *	member.  On error return, '*buflist' will be unchanged.
613 *
614 *\li	For isc_socket_recv2():
615 *	'event' is not NULL, and the non-socket specific fields are
616 *	expected to be initialized.
617 *
618 *\li	For isc_socket_recv2():
619 *	The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE.  If
620 *	set and the operation completes, the return value will be
621 *	ISC_R_SUCCESS and the event will be filled in and not sent.  If the
622 *	operation does not complete, the return value will be
623 *	ISC_R_INPROGRESS and the event will be sent when the operation
624 *	completes.
625 *
626 * Requires:
627 *
628 *\li	'socket' is a valid, bound socket.
629 *
630 *\li	For isc_socket_recv():
631 *	'region' is a valid region
632 *
633 *\li	For isc_socket_recvv():
634 *	'buflist' is non-NULL, and '*buflist' contain at least one buffer.
635 *
636 *\li	'task' is a valid task
637 *
638 *\li	For isc_socket_recv() and isc_socket_recvv():
639 *	action != NULL and is a valid action
640 *
641 *\li	For isc_socket_recv2():
642 *	event != NULL
643 *
644 * Returns:
645 *
646 *\li	#ISC_R_SUCCESS
647 *\li	#ISC_R_INPROGRESS
648 *\li	#ISC_R_NOMEMORY
649 *\li	#ISC_R_UNEXPECTED
650 *
651 * Event results:
652 *
653 *\li	#ISC_R_SUCCESS
654 *\li	#ISC_R_UNEXPECTED
655 *\li	XXX needs other net-type errors
656 */
657/*@}*/
658
659/*@{*/
660isc_result_t
661isc_socket_send(isc_socket_t *sock, isc_region_t *region,
662		isc_task_t *task, isc_taskaction_t action, const void *arg);
663isc_result_t
664isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
665		  isc_task_t *task, isc_taskaction_t action, const void *arg,
666		  isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
667isc_result_t
668isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
669		 isc_task_t *task, isc_taskaction_t action, const void *arg);
670isc_result_t
671isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
672		   isc_task_t *task, isc_taskaction_t action, const void *arg,
673		   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
674isc_result_t
675isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
676		   isc_task_t *task,
677		   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
678		   isc_socketevent_t *event, unsigned int flags);
679
680/*!
681 * Send the contents of 'region' to the socket's peer.
682 *
683 * Notes:
684 *
685 *\li	Shutting down the requestor's task *may* result in any
686 *	still pending writes being dropped or completed, depending on the
687 *	underlying OS implementation.
688 *
689 *\li	If 'action' is NULL, then no completion event will be posted.
690 *
691 *\li	The caller may not modify 'region', the buffers which are passed
692 *	into this function, or any data they refer to until the completion
693 *	event is received.
694 *
695 *\li	For isc_socket_sendv() and isc_socket_sendtov():
696 *	On successful completion, '*buflist' will be empty, and the list of
697 *	all buffers will be returned in the done event's 'bufferlist'
698 *	member.  On error return, '*buflist' will be unchanged.
699 *
700 *\li	For isc_socket_sendto2():
701 *	'event' is not NULL, and the non-socket specific fields are
702 *	expected to be initialized.
703 *
704 *\li	For isc_socket_sendto2():
705 *	The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
706 *	and ISC_SOCKFLAG_NORETRY.
707 *
708 *\li	If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
709 *	return value will be ISC_R_SUCCESS and the event will be filled
710 *	in and not sent.  If the operation does not complete, the return
711 *	value will be ISC_R_INPROGRESS and the event will be sent when
712 *	the operation completes.
713 *
714 *\li	ISC_SOCKFLAG_NORETRY can only be set for UDP sockets.  If set
715 *	and the send operation fails due to a transient error, the send
716 *	will not be retried and the error will be indicated in the event.
717 *	Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
718 *	to specify a region that is allocated on the stack.
719 *
720 * Requires:
721 *
722 *\li	'socket' is a valid, bound socket.
723 *
724 *\li	For isc_socket_send():
725 *	'region' is a valid region
726 *
727 *\li	For isc_socket_sendv() and isc_socket_sendtov():
728 *	'buflist' is non-NULL, and '*buflist' contain at least one buffer.
729 *
730 *\li	'task' is a valid task
731 *
732 *\li	For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and
733 *	isc_socket_sendto():
734 *	action == NULL or is a valid action
735 *
736 *\li	For isc_socket_sendto2():
737 *	event != NULL
738 *
739 * Returns:
740 *
741 *\li	#ISC_R_SUCCESS
742 *\li	#ISC_R_INPROGRESS
743 *\li	#ISC_R_NOMEMORY
744 *\li	#ISC_R_UNEXPECTED
745 *
746 * Event results:
747 *
748 *\li	#ISC_R_SUCCESS
749 *\li	#ISC_R_UNEXPECTED
750 *\li	XXX needs other net-type errors
751 */
752/*@}*/
753
754isc_result_t
755isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
756
757isc_result_t
758isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp,
759		      unsigned int maxsocks);
760/*%<
761 * Create a socket manager.  If "maxsocks" is non-zero, it specifies the
762 * maximum number of sockets that the created manager should handle.
763 * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with
764 * "maxsocks" being zero.
765 *
766 * Notes:
767 *
768 *\li	All memory will be allocated in memory context 'mctx'.
769 *
770 * Requires:
771 *
772 *\li	'mctx' is a valid memory context.
773 *
774 *\li	'managerp' points to a NULL isc_socketmgr_t.
775 *
776 * Ensures:
777 *
778 *\li	'*managerp' is a valid isc_socketmgr_t.
779 *
780 * Returns:
781 *
782 *\li	#ISC_R_SUCCESS
783 *\li	#ISC_R_NOMEMORY
784 *\li	#ISC_R_UNEXPECTED
785 *\li	#ISC_R_NOTIMPLEMENTED
786 */
787
788isc_result_t
789isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp);
790/*%<
791 * Returns in "*nsockp" the maximum number of sockets this manager may open.
792 *
793 * Requires:
794 *
795 *\li	'*manager' is a valid isc_socketmgr_t.
796 *\li	'nsockp' is not NULL.
797 *
798 * Returns:
799 *
800 *\li	#ISC_R_SUCCESS
801 *\li	#ISC_R_NOTIMPLEMENTED
802 */
803
804void
805isc_socketmgr_destroy(isc_socketmgr_t **managerp);
806/*%<
807 * Destroy a socket manager.
808 *
809 * Notes:
810 *
811 *\li	This routine blocks until there are no sockets left in the manager,
812 *	so if the caller holds any socket references using the manager, it
813 *	must detach them before calling isc_socketmgr_destroy() or it will
814 *	block forever.
815 *
816 * Requires:
817 *
818 *\li	'*managerp' is a valid isc_socketmgr_t.
819 *
820 *\li	All sockets managed by this manager are fully detached.
821 *
822 * Ensures:
823 *
824 *\li	*managerp == NULL
825 *
826 *\li	All resources used by the manager have been freed.
827 */
828
829isc_sockettype_t
830isc_socket_gettype(isc_socket_t *sock);
831/*%<
832 * Returns the socket type for "sock."
833 *
834 * Requires:
835 *
836 *\li	"sock" is a valid socket.
837 */
838
839/*@{*/
840isc_boolean_t
841isc_socket_isbound(isc_socket_t *sock);
842
843void
844isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
845/*%<
846 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
847 * option if the host OS supports this option.
848 *
849 * Requires:
850 *\li	'sock' is a valid socket.
851 */
852/*@}*/
853
854void
855isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);
856
857/*%<
858 * Cleanup UNIX domain sockets in the file-system.  If 'active' is true
859 * then just unlink the socket.  If 'active' is false try to determine
860 * if there is a listener of the socket or not.  If no listener is found
861 * then unlink socket.
862 *
863 * Prior to unlinking the path is tested to see if it a socket.
864 *
865 * Note: there are a number of race conditions which cannot be avoided
866 *       both in the filesystem and any application using UNIX domain
867 *	 sockets (e.g. socket is tested between bind() and listen(),
868 *	 the socket is deleted and replaced in the file-system between
869 *	 stat() and unlink()).
870 */
871
872isc_result_t
873isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
874		    isc_uint32_t owner, isc_uint32_t group);
875/*%<
876 * Set ownership and file permissions on the UNIX domain socket.
877 *
878 * Note: On Solaris and SunOS this secures the directory containing
879 *       the socket as Solaris and SunOS do not honour the filesytem
880 *	 permissions on the socket.
881 *
882 * Requires:
883 * \li	'sockaddr' to be a valid UNIX domain sockaddr.
884 *
885 * Returns:
886 * \li	#ISC_R_SUCCESS
887 * \li	#ISC_R_FAILURE
888 */
889
890void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag);
891/*%<
892 * Set the name and optional tag for a socket.  This allows tracking of the
893 * owner or purpose for this socket, and is useful for tracing and statistics
894 * reporting.
895 */
896
897const char *isc_socket_getname(isc_socket_t *socket);
898/*%<
899 * Get the name associated with a socket, if any.
900 */
901
902void *isc_socket_gettag(isc_socket_t *socket);
903/*%<
904 * Get the tag associated with a socket, if any.
905 */
906
907void
908isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
909/*%<
910 * Temporary.  For use by named only.
911 */
912
913#ifdef HAVE_LIBXML2
914
915void
916isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer);
917/*%<
918 * Render internal statistics and other state into the XML document.
919 */
920
921#endif /* HAVE_LIBXML2 */
922
923ISC_LANG_ENDDECLS
924
925#endif /* ISC_SOCKET_H */