socket.h 24.6 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
Automatic Updater's avatar
Automatic Updater committed
2
 * Copyright (C) 2004-2009  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1998-2002  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
Bob Halley committed
16
 */
17

Automatic Updater's avatar
Automatic Updater committed
18
/* $Id: socket.h,v 1.87 2009/01/18 23:48:14 tbox Exp $ */
David Lawrence's avatar
David Lawrence committed
19

20 21 22 23 24 25 26
#ifndef ISC_SOCKET_H
#define ISC_SOCKET_H 1

/*****
 ***** Module Info
 *****/

27
/*! \file isc/socket.h
28
 * \brief Provides TCP and UDP sockets for network I/O.  The sockets are event
29 30 31 32 33
 * sources in the task system.
 *
 * When I/O completes, a completion event for the socket is posted to the
 * event queue of the task which requested the I/O.
 *
34
 * \li MP:
35 36 37 38 39 40 41 42
 *	The module ensures appropriate synchronization of data structures it
 *	creates and manipulates.
 *	Clients of this module must not be holding a socket's task's lock when
 *	making a call that affects that socket.  Failure to follow this rule
 *	can result in deadlock.
 *	The caller must ensure that isc_socketmgr_destroy() is called only
 *	once for a given manager.
 *
43
 * \li Reliability:
44 45
 *	No anticipated impact.
 *
46 47
 * \li Resources:
 *	TBS
48
 *
49
 * \li Security:
50 51
 *	No anticipated impact.
 *
52
 * \li Standards:
53 54 55 56 57 58 59
 *	None.
 */

/***
 *** Imports
 ***/

Bob Halley's avatar
Bob Halley committed
60
#include <isc/lang.h>
Bob Halley's avatar
Bob Halley committed
61
#include <isc/types.h>
Michael Graff's avatar
Michael Graff committed
62
#include <isc/event.h>
Bob Halley's avatar
Bob Halley committed
63
#include <isc/eventclass.h>
Michael Graff's avatar
Michael Graff committed
64
#include <isc/time.h>
65
#include <isc/region.h>
Bob Halley's avatar
Bob Halley committed
66
#include <isc/sockaddr.h>
67
#include <isc/xml.h>
68

Bob Halley's avatar
Bob Halley committed
69 70
ISC_LANG_BEGINDECLS

71 72 73 74
/***
 *** Constants
 ***/

75
/*%
76 77
 * Maximum number of buffers in a scatter/gather read/write.  The operating
 * system in use must support at least this number (plus one on some.)
78 79 80
 */
#define ISC_SOCKET_MAXSCATTERGATHER	8

81 82 83 84 85 86
/*%
 * In isc_socket_bind() set socket option SO_REUSEADDR prior to calling
 * bind() if a non zero port is specified (AF_INET and AF_INET6).
 */
#define ISC_SOCKET_REUSEADDRESS		0x01U

87 88 89 90
/***
 *** Types
 ***/

91
struct isc_socketevent {
92
	ISC_EVENT_COMMON(isc_socketevent_t);
93 94 95 96 97 98 99 100 101 102
	isc_result_t		result;		/*%< OK, EOF, whatever else */
	unsigned int		minimum;	/*%< minimum i/o for event */
	unsigned int		n;		/*%< bytes read or written */
	unsigned int		offset;		/*%< offset into buffer list */
	isc_region_t		region;		/*%< for single-buffer i/o */
	isc_bufferlist_t	bufferlist;	/*%< list of buffers */
	isc_sockaddr_t		address;	/*%< source address */
	isc_time_t		timestamp;	/*%< timestamp of packet recv */
	struct in6_pktinfo	pktinfo;	/*%< ipv6 pktinfo */
	isc_uint32_t		attributes;	/*%< see below */
103
	isc_eventdestructor_t   destroy;	/*%< original destructor */
104
};
105

106 107 108
typedef struct isc_socket_newconnev isc_socket_newconnev_t;
struct isc_socket_newconnev {
	ISC_EVENT_COMMON(isc_socket_newconnev_t);
Bob Halley's avatar
Bob Halley committed
109
	isc_socket_t *		newsocket;
110 111
	isc_result_t		result;		/*%< OK, EOF, whatever else */
	isc_sockaddr_t		address;	/*%< source address */
112
};
Michael Graff's avatar
Michael Graff committed
113

114 115 116
typedef struct isc_socket_connev isc_socket_connev_t;
struct isc_socket_connev {
	ISC_EVENT_COMMON(isc_socket_connev_t);
117
	isc_result_t		result;		/*%< OK, EOF, whatever else */
118
};
Michael Graff's avatar
Michael Graff committed
119

120 121
/*@{*/
/*!
Michael Graff's avatar
Michael Graff committed
122 123 124 125 126 127 128
 * _ATTACHED:	Internal use only.
 * _TRUNC:	Packet was truncated on receive.
 * _CTRUNC:	Packet control information was truncated.  This can
 *		indicate that the packet is not complete, even though
 *		all the data is valid.
 * _TIMESTAMP:	The timestamp member is valid.
 * _PKTINFO:	The pktinfo member is valid.
129
 * _MULTICAST:	The UDP packet was received via a multicast transmission.
Michael Graff's avatar
Michael Graff committed
130
 */
131 132 133 134 135
#define ISC_SOCKEVENTATTR_ATTACHED		0x80000000U /* internal */
#define ISC_SOCKEVENTATTR_TRUNC			0x00800000U /* public */
#define ISC_SOCKEVENTATTR_CTRUNC		0x00400000U /* public */
#define ISC_SOCKEVENTATTR_TIMESTAMP		0x00200000U /* public */
#define ISC_SOCKEVENTATTR_PKTINFO		0x00100000U /* public */
136
#define ISC_SOCKEVENTATTR_MULTICAST		0x00080000U /* public */
137
/*@}*/
138

139
#define ISC_SOCKEVENT_ANYEVENT  (0)
Michael Graff's avatar
Michael Graff committed
140 141 142
#define ISC_SOCKEVENT_RECVDONE	(ISC_EVENTCLASS_SOCKET + 1)
#define ISC_SOCKEVENT_SENDDONE	(ISC_EVENTCLASS_SOCKET + 2)
#define ISC_SOCKEVENT_NEWCONN	(ISC_EVENTCLASS_SOCKET + 3)
Michael Graff's avatar
Michael Graff committed
143
#define ISC_SOCKEVENT_CONNECT	(ISC_EVENTCLASS_SOCKET + 4)
Michael Graff's avatar
Michael Graff committed
144 145 146 147

/*
 * Internal events.
 */
148 149
#define ISC_SOCKEVENT_INTR	(ISC_EVENTCLASS_SOCKET + 256)
#define ISC_SOCKEVENT_INTW	(ISC_EVENTCLASS_SOCKET + 257)
150 151

typedef enum {
152
	isc_sockettype_udp = 1,
153
	isc_sockettype_tcp = 2,
154
	isc_sockettype_unix = 3,
155
	isc_sockettype_fdwatch = 4
156 157
} isc_sockettype_t;

158 159
/*@{*/
/*!
Michael Graff's avatar
Michael Graff committed
160 161
 * How a socket should be shutdown in isc_socket_shutdown() calls.
 */
162 163 164 165
#define ISC_SOCKSHUT_RECV	0x00000001	/*%< close read side */
#define ISC_SOCKSHUT_SEND	0x00000002	/*%< close write side */
#define ISC_SOCKSHUT_ALL	0x00000003	/*%< close them all */
/*@}*/
Michael Graff's avatar
Michael Graff committed
166

167 168
/*@{*/
/*!
Michael Graff's avatar
Michael Graff committed
169 170
 * What I/O events to cancel in isc_socket_cancel() calls.
 */
171 172 173 174 175 176 177 178 179
#define ISC_SOCKCANCEL_RECV	0x00000001	/*%< cancel recv */
#define ISC_SOCKCANCEL_SEND	0x00000002	/*%< cancel send */
#define ISC_SOCKCANCEL_ACCEPT	0x00000004	/*%< cancel accept */
#define ISC_SOCKCANCEL_CONNECT	0x00000008	/*%< cancel connect */
#define ISC_SOCKCANCEL_ALL	0x0000000f	/*%< cancel everything */
/*@}*/

/*@{*/
/*!
180 181
 * Flags for isc_socket_send() and isc_socket_recv() calls.
 */
182 183 184
#define ISC_SOCKFLAG_IMMEDIATE	0x00000001	/*%< send event only if needed */
#define ISC_SOCKFLAG_NORETRY	0x00000002	/*%< drop failed UDP sends */
/*@}*/
185

186 187 188 189 190 191 192 193
/*@{*/
/*!
 * Flags for fdwatchcreate.
 */
#define ISC_SOCKFDWATCH_READ	0x00000001	/*%< watch for readable */
#define ISC_SOCKFDWATCH_WRITE	0x00000002	/*%< watch for writable */
/*@}*/

194 195 196 197 198 199 200
/***
 *** Socket and Socket Manager Functions
 ***
 *** Note: all Ensures conditions apply only if the result is success for
 *** those functions which return an isc_result.
 ***/

201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
isc_result_t
isc_socket_fdwatchcreate(isc_socketmgr_t *manager,
			 int fd,
			 int flags,
			 isc_sockfdwatch_t callback,
			 void *cbarg,
			 isc_task_t *task,
			 isc_socket_t **socketp);
/*%<
 * Create a new file descriptor watch socket managed by 'manager'.
 *
 * Note:
 *
 *\li   'fd' is the already-opened file descriptor.
 *\li	This function is not available on Windows.
 *\li	The callback function is called "in-line" - this means the function
 *	needs to return as fast as possible, as all other I/O will be suspended
 *	until the callback completes.
 *
 * Requires:
 *
 *\li	'manager' is a valid manager
 *
 *\li	'socketp' is a valid pointer, and *socketp == NULL
 *
 *\li	'fd' be opened.
 *
 * Ensures:
 *
 *	'*socketp' is attached to the newly created fdwatch socket
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_NORESOURCES
 *\li	#ISC_R_UNEXPECTED
 */

240
isc_result_t
Bob Halley's avatar
Bob Halley committed
241
isc_socket_create(isc_socketmgr_t *manager,
Bob Halley's avatar
Bob Halley committed
242
		  int pf,
243
		  isc_sockettype_t type,
Bob Halley's avatar
Bob Halley committed
244
		  isc_socket_t **socketp);
245
/*%<
246 247
 * Create a new 'type' socket managed by 'manager'.
 *
248 249 250
 * For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate()
 * rather than isc_socket_create().
 *
Bob Halley's avatar
Bob Halley committed
251 252
 * Note:
 *
253
 *\li	'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.
Bob Halley's avatar
Bob Halley committed
254
 *
255 256
 * Requires:
 *
257
 *\li	'manager' is a valid manager
258
 *
259
 *\li	'socketp' is a valid pointer, and *socketp == NULL
260
 *
261 262
 *\li	'type' is not isc_sockettype_fdwatch
 *
263 264 265 266 267 268
 * Ensures:
 *
 *	'*socketp' is attached to the newly created socket
 *
 * Returns:
 *
269 270 271 272
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_NORESOURCES
 *\li	#ISC_R_UNEXPECTED
273 274
 */

Michael Graff's avatar
Michael Graff committed
275
void
Bob Halley's avatar
Bob Halley committed
276
isc_socket_cancel(isc_socket_t *sock, isc_task_t *task,
Michael Graff's avatar
Michael Graff committed
277
		  unsigned int how);
278
/*%<
Michael Graff's avatar
Michael Graff committed
279 280 281 282 283 284 285
 * Cancel pending I/O of the type specified by "how".
 *
 * Note: if "task" is NULL, then the cancel applies to all tasks using the
 * socket.
 *
 * Requires:
 *
286
 * \li	"socket" is a valid socket
Michael Graff's avatar
Michael Graff committed
287
 *
288
 * \li	"task" is NULL or a valid task
Michael Graff's avatar
Michael Graff committed
289 290 291 292 293
 *
 * "how" is a bitmask describing the type of cancelation to perform.
 * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this
 * socket.
 *
294
 * \li ISC_SOCKCANCEL_RECV:
Michael Graff's avatar
Michael Graff committed
295 296
 *	Cancel pending isc_socket_recv() calls.
 *
297
 * \li ISC_SOCKCANCEL_SEND:
Michael Graff's avatar
Michael Graff committed
298 299
 *	Cancel pending isc_socket_send() and isc_socket_sendto() calls.
 *
300
 * \li ISC_SOCKCANCEL_ACCEPT:
Michael Graff's avatar
Michael Graff committed
301 302
 *	Cancel pending isc_socket_accept() calls.
 *
303
 * \li ISC_SOCKCANCEL_CONNECT:
Michael Graff's avatar
Michael Graff committed
304
 *	Cancel pending isc_socket_connect() call.
Michael Graff's avatar
Michael Graff committed
305
 */
306

307
void
Bob Halley's avatar
Bob Halley committed
308
isc_socket_shutdown(isc_socket_t *sock, unsigned int how);
309
/*%<
310 311 312 313
 * Shutdown 'socket' according to 'how'.
 *
 * Requires:
 *
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
 *
Michael Graff's avatar
Michael Graff committed
320
 *		The read queue must be empty.
321 322 323
 *
 *		No further read requests may be made.
 *
324
 * \li	If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then
325
 *
Michael Graff's avatar
Michael Graff committed
326
 *		The write queue must be empty.
327 328 329 330 331
 *
 *		No further write requests may be made.
 */

void
Bob Halley's avatar
Bob Halley committed
332
isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp);
333
/*%<
334 335 336 337
 * Attach *socketp to socket.
 *
 * Requires:
 *
338
 * \li	'socket' is a valid socket.
339
 *
340
 * \li	'socketp' points to a NULL socket.
341 342 343
 *
 * Ensures:
 *
344
 * \li	*socketp is attached to socket.
345 346
 */

347
void
Bob Halley's avatar
Bob Halley committed
348
isc_socket_detach(isc_socket_t **socketp);
349
/*%<
350 351 352 353
 * Detach *socketp from its socket.
 *
 * Requires:
 *
354
 * \li	'socketp' points to a valid socket.
355
 *
356
 * \li	If '*socketp' is the last reference to the socket,
357 358 359 360
 *	then:
 *
 *		There must be no pending I/O requests.
 *
361 362
 * Ensures:
 *
363
 * \li	*socketp is NULL.
364
 *
365
 * \li	If '*socketp' is the last reference to the socket,
366 367 368 369 370 371 372 373
 *	then:
 *
 *		The socket will be shutdown (both reading and writing)
 *		for all tasks.
 *
 *		All resources used by the socket have been freed
 */

374 375 376 377 378 379 380 381 382
isc_result_t
isc_socket_open(isc_socket_t *sock);
/*%<
 * Open a new socket file descriptor of the given socket structure.  It simply
 * opens a new descriptor; all of the other parameters including the socket
 * type are inherited from the existing socket.  This function is provided to
 * avoid overhead of destroying and creating sockets when many short-lived
 * sockets are frequently opened and closed.  When the efficiency is not an
 * issue, it should be safer to detach the unused socket and re-create a new
383 384
 * one.  This optimization may not be available for some systems, in which
 * case this function will return ISC_R_NOTIMPLEMENTED and must not be used.
385
 *
386 387 388
 * isc_socket_open() should not be called on sockets created by
 * isc_socket_fdwatchcreate().
 *
389 390 391 392 393 394
 * Requires:
 *
 * \li	there must be no other reference to this socket.
 *
 * \li	'socket' is a valid and previously closed by isc_socket_close()
 *
395 396
 * \li  'sock->type' is not isc_sockettype_fdwatch
 *
397 398
 * Returns:
 *	Same as isc_socket_create().
399
 * \li	ISC_R_NOTIMPLEMENTED
400 401
 */

402
isc_result_t
403 404 405 406 407
isc_socket_close(isc_socket_t *sock);
/*%<
 * Close a socket file descriptor of the given socket structure.  This function
 * is provided as an alternative to destroying an unused socket when overhead
 * destroying/re-creating sockets can be significant, and is expected to be
408 409 410
 * used with isc_socket_open().  This optimization may not be available for some
 * systems, in which case this function will return ISC_R_NOTIMPLEMENTED and
 * must not be used.
411
 *
412 413 414
 * isc_socket_close() should not be called on sockets created by
 * isc_socket_fdwatchcreate().
 *
415 416 417 418 419 420 421
 * Requires:
 *
 * \li	The socket must have a valid descriptor.
 *
 * \li	There must be no other reference to this socket.
 *
 * \li	There must be no pending I/O requests.
Automatic Updater's avatar
Automatic Updater committed
422
 *
423 424
 * \li  'sock->type' is not isc_sockettype_fdwatch
 *
425 426
 * Returns:
 * \li	#ISC_R_NOTIMPLEMENTED
427 428
 */

429
isc_result_t
430
isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp,
Automatic Updater's avatar
Automatic Updater committed
431
		unsigned int options);
432
/*%<
433 434 435 436
 * Bind 'socket' to '*addressp'.
 *
 * Requires:
 *
437
 * \li	'socket' is a valid socket
438
 *
439
 * \li	'addressp' points to a valid isc_sockaddr.
440 441 442
 *
 * Returns:
 *
443 444 445 446 447 448
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_NOPERM
 * \li	ISC_R_ADDRNOTAVAIL
 * \li	ISC_R_ADDRINUSE
 * \li	ISC_R_BOUND
 * \li	ISC_R_UNEXPECTED
449 450
 */

451 452
isc_result_t
isc_socket_filter(isc_socket_t *sock, const char *filter);
453
/*%<
454 455 456 457
 * Inform the kernel that it should perform accept filtering.
 * If filter is NULL the current filter will be removed.:w
 */

458
isc_result_t
Bob Halley's avatar
Bob Halley committed
459
isc_socket_listen(isc_socket_t *sock, unsigned int backlog);
460
/*%<
461 462
 * Set listen mode on the socket.  After this call, the only function that
 * can be used (other than attach and detach) is isc_socket_accept().
463 464 465
 *
 * Notes:
 *
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 471
 *	SOMAXCONN.
 *
472 473
 * Requires:
 *
474
 * \li	'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.
475 476 477
 *
 * Returns:
 *
478 479
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_UNEXPECTED
480 481 482
 */

isc_result_t
Bob Halley's avatar
Bob Halley committed
483
isc_socket_accept(isc_socket_t *sock,
David Lawrence's avatar
David Lawrence committed
484
		  isc_task_t *task, isc_taskaction_t action, const void *arg);
485
/*%<
486 487 488 489
 * Queue accept event.  When a new connection is received, the task will
 * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen
 * socket.  The new socket structure is sent inside the isc_socket_newconnev_t
 * 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 501 502
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_NOMEMORY
 * \li	ISC_R_UNEXPECTED
503 504 505
 */

isc_result_t
Bob Halley's avatar
Bob Halley committed
506
isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp,
Bob Halley's avatar
Bob Halley committed
507
		   isc_task_t *task, isc_taskaction_t action,
David Lawrence's avatar
David Lawrence committed
508
		   const void *arg);
509
/*%<
510
 * Connect 'socket' to peer with address *saddr.  When the connection
Michael Graff's avatar
Michael Graff committed
511
 * succeeds, or when an error occurs, a CONNECT event with action 'action'
512 513 514 515
 * and arg 'arg' will be posted to the event queue for 'task'.
 *
 * Requires:
 *
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 525
 *
 * Returns:
 *
526 527 528
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_NOMEMORY
 * \li	ISC_R_UNEXPECTED
529 530 531
 *
 * Posted event's result code:
 *
532 533 534 535 536
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_TIMEDOUT
 * \li	ISC_R_CONNREFUSED
 * \li	ISC_R_NETUNREACH
 * \li	ISC_R_UNEXPECTED
537 538 539
 */

isc_result_t
Bob Halley's avatar
Bob Halley committed
540
isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp);
541
/*%<
542 543 544 545
 * Get the name of the peer connected to 'socket'.
 *
 * Requires:
 *
546
 * \li	'socket' is a valid TCP socket.
547 548 549
 *
 * Returns:
 *
550 551 552
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_TOOSMALL
 * \li	ISC_R_UNEXPECTED
553 554 555
 */

isc_result_t
Bob Halley's avatar
Bob Halley committed
556
isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp);
557
/*%<
558 559 560 561
 * Get the name of 'socket'.
 *
 * Requires:
 *
562
 * \li	'socket' is a valid socket.
563 564 565
 *
 * Returns:
 *
566 567 568
 * \li	ISC_R_SUCCESS
 * \li	ISC_R_TOOSMALL
 * \li	ISC_R_UNEXPECTED
569 570
 */

571
/*@{*/
572
isc_result_t
Bob Halley's avatar
Bob Halley committed
573
isc_socket_recv(isc_socket_t *sock, isc_region_t *region,
574
		unsigned int minimum,
David Lawrence's avatar
David Lawrence committed
575
		isc_task_t *task, isc_taskaction_t action, const void *arg);
576 577 578
isc_result_t
isc_socket_recvv(isc_socket_t *sock, isc_bufferlist_t *buflist,
		 unsigned int minimum,
David Lawrence's avatar
David Lawrence committed
579
		 isc_task_t *task, isc_taskaction_t action, const void *arg);
580 581 582 583 584 585

isc_result_t
isc_socket_recv2(isc_socket_t *sock, isc_region_t *region,
		 unsigned int minimum, isc_task_t *task,
		 isc_socketevent_t *event, unsigned int flags);

586
/*!
587 588 589 590
 * Receive from 'socket', storing the results in region.
 *
 * Notes:
 *
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 598 599
 * 	be read for an event to be posted.  This only makes sense for TCP
 *	connections, and is always set to 1 byte for UDP.
 *
600
 *\li	The read will complete when the desired number of bytes have been
601 602 603 604
 *	read, if end-of-input occurs, or if an error occurs.  A read done
 *	event with the given 'action' and 'arg' will be posted to the
 *	event queue of 'task'.
 *
605
 *\li	The caller may not modify 'region', the buffers which are passed
606 607 608
 *	into this function, or any data they refer to until the completion
 *	event is received.
 *
609
 *\li	For isc_socket_recvv():
610 611 612 613
 *	On successful completion, '*buflist' will be empty, and the list of
 *	all buffers will be returned in the done event's 'bufferlist'
 *	member.  On error return, '*buflist' will be unchanged.
 *
614
 *\li	For isc_socket_recv2():
615 616 617
 *	'event' is not NULL, and the non-socket specific fields are
 *	expected to be initialized.
 *
618
 *\li	For isc_socket_recv2():
619 620 621 622 623 624 625
 *	The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE.  If
 *	set and the operation completes, the return value will be
 *	ISC_R_SUCCESS and the event will be filled in and not sent.  If the
 *	operation does not complete, the return value will be
 *	ISC_R_INPROGRESS and the event will be sent when the operation
 *	completes.
 *
626 627
 * Requires:
 *
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 640
 *	action != NULL and is a valid action
 *
641
 *\li	For isc_socket_recv2():
642 643
 *	event != NULL
 *
644 645
 * Returns:
 *
646 647 648 649
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_INPROGRESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_UNEXPECTED
650 651 652
 *
 * Event results:
 *
653 654 655
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_UNEXPECTED
 *\li	XXX needs other net-type errors
656
 */
657
/*@}*/
658

659
/*@{*/
660
isc_result_t
Bob Halley's avatar
Bob Halley committed
661
isc_socket_send(isc_socket_t *sock, isc_region_t *region,
David Lawrence's avatar
David Lawrence committed
662
		isc_task_t *task, isc_taskaction_t action, const void *arg);
Michael Graff's avatar
Michael Graff committed
663
isc_result_t
Bob Halley's avatar
Bob Halley committed
664
isc_socket_sendto(isc_socket_t *sock, isc_region_t *region,
David Lawrence's avatar
David Lawrence committed
665
		  isc_task_t *task, isc_taskaction_t action, const void *arg,
Michael Graff's avatar
Michael Graff committed
666
		  isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
667 668
isc_result_t
isc_socket_sendv(isc_socket_t *sock, isc_bufferlist_t *buflist,
David Lawrence's avatar
David Lawrence committed
669
		 isc_task_t *task, isc_taskaction_t action, const void *arg);
670 671
isc_result_t
isc_socket_sendtov(isc_socket_t *sock, isc_bufferlist_t *buflist,
David Lawrence's avatar
David Lawrence committed
672
		   isc_task_t *task, isc_taskaction_t action, const void *arg,
Michael Graff's avatar
Michael Graff committed
673
		   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo);
674 675 676 677 678 679
isc_result_t
isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region,
		   isc_task_t *task,
		   isc_sockaddr_t *address, struct in6_pktinfo *pktinfo,
		   isc_socketevent_t *event, unsigned int flags);

680
/*!
681 682 683 684
 * Send the contents of 'region' to the socket's peer.
 *
 * Notes:
 *
685
 *\li	Shutting down the requestor's task *may* result in any
686 687
 *	still pending writes being dropped or completed, depending on the
 *	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 693 694
 *	into this function, or any data they refer to until the completion
 *	event is received.
 *
695
 *\li	For isc_socket_sendv() and isc_socket_sendtov():
696 697 698
 *	On successful completion, '*buflist' will be empty, and the list of
 *	all buffers will be returned in the done event's 'bufferlist'
 *	member.  On error return, '*buflist' will be unchanged.
699
 *
700
 *\li	For isc_socket_sendto2():
701 702 703
 *	'event' is not NULL, and the non-socket specific fields are
 *	expected to be initialized.
 *
704
 *\li	For isc_socket_sendto2():
705 706 707
 *	The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE
 *	and ISC_SOCKFLAG_NORETRY.
 *
708
 *\li	If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the
709 710 711 712 713
 *	return value will be ISC_R_SUCCESS and the event will be filled
 *	in and not sent.  If the operation does not complete, the return
 *	value will be ISC_R_INPROGRESS and the event will be sent when
 *	the operation completes.
 *
714
 *\li	ISC_SOCKFLAG_NORETRY can only be set for UDP sockets.  If set
715 716 717 718
 *	and the send operation fails due to a transient error, the send
 *	will not be retried and the error will be indicated in the event.
 *	Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller
 *	to specify a region that is allocated on the stack.
719
 *
720 721
 * Requires:
 *
722
 *\li	'socket' is a valid, bound socket.
723
 *
724
 *\li	For isc_socket_send():
725 726
 *	'region' is a valid region
 *
727
 *\li	For isc_socket_sendv() and isc_socket_sendtov():
728 729
 *	'buflist' is non-NULL, and '*buflist' contain at least one buffer.
 *
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 735
 *	action == NULL or is a valid action
 *
736
 *\li	For isc_socket_sendto2():
737 738
 *	event != NULL
 *
739 740
 * Returns:
 *
741 742 743 744
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_INPROGRESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_UNEXPECTED
745 746 747
 *
 * Event results:
 *
748 749 750
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_UNEXPECTED
 *\li	XXX needs other net-type errors
751
 */
752
/*@}*/
753 754

isc_result_t
Bob Halley's avatar
Bob Halley committed
755
isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp);
756 757 758 759

isc_result_t
isc_socketmgr_create2(isc_mem_t *mctx, isc_socketmgr_t **managerp,
		      unsigned int maxsocks);
760
/*%<
761 762 763 764
 * Create a socket manager.  If "maxsocks" is non-zero, it specifies the
 * maximum number of sockets that the created manager should handle.
 * isc_socketmgr_create() is equivalent of isc_socketmgr_create2() with
 * "maxsocks" being zero.
765 766 767
 *
 * Notes:
 *
768
 *\li	All memory will be allocated in memory context 'mctx'.
769 770 771
 *
 * Requires:
 *
772
 *\li	'mctx' is a valid memory context.
773
 *
774
 *\li	'managerp' points to a NULL isc_socketmgr_t.
775 776 777
 *
 * Ensures:
 *
778
 *\li	'*managerp' is a valid isc_socketmgr_t.
779 780 781
 *
 * Returns:
 *
782 783 784
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_UNEXPECTED
785
 *\li	#ISC_R_NOTIMPLEMENTED
786 787
 */

788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
isc_result_t
isc_socketmgr_getmaxsockets(isc_socketmgr_t *manager, unsigned int *nsockp);
/*%<
 * Returns in "*nsockp" the maximum number of sockets this manager may open.
 *
 * Requires:
 *
 *\li	'*manager' is a valid isc_socketmgr_t.
 *\li	'nsockp' is not NULL.
 *
 * Returns:
 *
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOTIMPLEMENTED
 */

804
void
Bob Halley's avatar
Bob Halley committed
805
isc_socketmgr_destroy(isc_socketmgr_t **managerp);
806
/*%<
807 808 809
 * Destroy a socket manager.
 *
 * Notes:
810
 *
811
 *\li	This routine blocks until there are no sockets left in the manager,
812 813 814 815 816 817
 *	so if the caller holds any socket references using the manager, it
 *	must detach them before calling isc_socketmgr_destroy() or it will
 *	block forever.
 *
 * Requires:
 *
818
 *\li	'*managerp' is a valid isc_socketmgr_t.
819
 *
820
 *\li	All sockets managed by this manager are fully detached.
821
 *
822 823
 * Ensures:
 *
824
 *\li	*managerp == NULL
825
 *
826
 *\li	All resources used by the manager have been freed.
827 828
 */

Michael Graff's avatar
Michael Graff committed
829 830
isc_sockettype_t
isc_socket_gettype(isc_socket_t *sock);
831
/*%<
Michael Graff's avatar
Michael Graff committed
832 833 834 835
 * Returns the socket type for "sock."
 *
 * Requires:
 *
836
 *\li	"sock" is a valid socket.
Michael Graff's avatar
Michael Graff committed
837 838
 */

839
/*@{*/
Michael Graff's avatar
Michael Graff committed
840 841 842
isc_boolean_t
isc_socket_isbound(isc_socket_t *sock);

843 844
void
isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes);
845
/*%<
846 847 848 849
 * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket
 * option if the host OS supports this option.
 *
 * Requires:
850
 *\li	'sock' is a valid socket.
851
 */
852
/*@}*/
853

854 855 856
void
isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active);

Mark Andrews's avatar
Mark Andrews committed
857
/*%<
858 859 860 861 862 863 864 865 866 867 868 869 870 871
 * Cleanup UNIX domain sockets in the file-system.  If 'active' is true
 * then just unlink the socket.  If 'active' is false try to determine
 * if there is a listener of the socket or not.  If no listener is found
 * then unlink socket.
 *
 * Prior to unlinking the path is tested to see if it a socket.
 *
 * Note: there are a number of race conditions which cannot be avoided
 *       both in the filesystem and any application using UNIX domain
 *	 sockets (e.g. socket is tested between bind() and listen(),
 *	 the socket is deleted and replaced in the file-system between
 *	 stat() and unlink()).
 */

Mark Andrews's avatar
Mark Andrews committed
872
isc_result_t
873
isc_socket_permunix(isc_sockaddr_t *sockaddr, isc_uint32_t perm,
Automatic Updater's avatar
Automatic Updater committed
874
		    isc_uint32_t owner, isc_uint32_t group);
Mark Andrews's avatar
Mark Andrews committed
875
/*%<
876 877 878
 * Set ownership and file permissions on the UNIX domain socket.
 *
 * Note: On Solaris and SunOS this secures the directory containing
Francis Dupont's avatar
Francis Dupont committed
879
 *       the socket as Solaris and SunOS do not honour the filesystem
880 881 882
 *	 permissions on the socket.
 *
 * Requires:
Mark Andrews's avatar
Mark Andrews committed
883
 * \li	'sockaddr' to be a valid UNIX domain sockaddr.
884 885
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
886 887
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_FAILURE
888 889
 */

890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907
void isc_socket_setname(isc_socket_t *socket, const char *name, void *tag);
/*%<
 * Set the name and optional tag for a socket.  This allows tracking of the
 * owner or purpose for this socket, and is useful for tracing and statistics
 * reporting.
 */

const char *isc_socket_getname(isc_socket_t *socket);
/*%<
 * Get the name associated with a socket, if any.
 */

void *isc_socket_gettag(isc_socket_t *socket);
/*%<
 * Get the tag associated with a socket, if any.
 */

void
908
isc__socketmgr_setreserved(isc_socketmgr_t *mgr, isc_uint32_t);
909
/*%<
910
 * Temporary.  For use by named only.
911 912
 */

913 914
#ifdef HAVE_LIBXML2

915
void
916
isc_socketmgr_renderxml(isc_socketmgr_t *mgr, xmlTextWriterPtr writer);
917
/*%<
918
 * Render internal statistics and other state into the XML document.
919 920
 */

921 922
#endif /* HAVE_LIBXML2 */

Bob Halley's avatar
Bob Halley committed
923 924
ISC_LANG_ENDDECLS

925
#endif /* ISC_SOCKET_H */