socket_api.c File Reference

#include <config.h>
#include <isc/app.h>
#include <isc/magic.h>
#include <isc/mutex.h>
#include <isc/once.h>
#include <isc/socket.h>
#include <isc/util.h>

Go to the source code of this file.

Functions
static void	initialize (void)
isc_result_t	isc_socket_register (isc_socketmgrcreatefunc_t createfunc)
	Register a new socket I/O implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.
isc_result_t	isc_socketmgr_createinctx (isc_mem_t *mctx, isc_appctx_t *actx, isc_socketmgr_t **managerp)
isc_result_t	isc_socketmgr_create (isc_mem_t *mctx, isc_socketmgr_t **managerp)
void	isc_socketmgr_destroy (isc_socketmgr_t **managerp)
	Destroy a socket manager.
isc_result_t	isc_socket_create (isc_socketmgr_t *manager, int pf, isc_sockettype_t type, isc_socket_t **socketp)
	Create a new 'type' socket managed by 'manager'.
void	isc_socket_attach (isc_socket_t *sock, isc_socket_t **socketp)
	Attach *socketp to socket.
void	isc_socket_detach (isc_socket_t **socketp)
	Detach *socketp from its socket.
isc_result_t	isc_socket_bind (isc_socket_t *sock, isc_sockaddr_t *sockaddr, unsigned int options)
	Bind 'socket' to '*addressp'.
isc_result_t	isc_socket_sendto (isc_socket_t *sock, isc_region_t *region, isc_task_t *task, isc_taskaction_t action, void *arg, isc_sockaddr_t *address, struct in6_pktinfo *pktinfo)
isc_result_t	isc_socket_connect (isc_socket_t *sock, isc_sockaddr_t *addr, isc_task_t *task, isc_taskaction_t action, void *arg)
	Connect 'socket' to peer with address *saddr. When the connection succeeds, or when an error occurs, a CONNECT event with action 'action' and arg 'arg' will be posted to the event queue for 'task'.
isc_result_t	isc_socket_recv (isc_socket_t *sock, isc_region_t *region, unsigned int minimum, isc_task_t *task, isc_taskaction_t action, void *arg)
void	isc_socket_cancel (isc_socket_t *sock, isc_task_t *task, unsigned int how)
	Cancel pending I/O of the type specified by "how".
isc_result_t	isc_socket_getsockname (isc_socket_t *sock, isc_sockaddr_t *addressp)
	Get the name of 'socket'.
void	isc_socket_ipv6only (isc_socket_t *sock, isc_boolean_t yes)
	Intended for internal use in BIND9 only.
void	isc_socket_dscp (isc_socket_t *sock, isc_dscp_t dscp)
	Sets the Differentiated Services Code Point (DSCP) field for packets transmitted on this socket. If 'dscp' is -1, return immediately.
isc_sockettype_t	isc_socket_gettype (isc_socket_t *sock)
	Returns the socket type for "sock.".
void	isc_socket_setname (isc_socket_t *sock, 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.
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'.
isc_result_t	isc_socket_fdwatchpoke (isc_socket_t *sock, int flags)
	Poke a file descriptor watch socket informing the manager that it should restart watching the socket.
isc_result_t	isc_socket_dup (isc_socket_t *sock, isc_socket_t **socketp)
	Duplicate an existing socket, reusing its file descriptor.
int	isc_socket_getfd (isc_socket_t *sock)
	Get the file descriptor associated with a socket.
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 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.
isc_result_t	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 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.
isc_result_t	isc_socketmgr_create2 (isc_mem_t *mctx, isc_socketmgr_t **managerp, unsigned int maxsocks)
	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. isc_socketmgr_createinctx() also associates the new manager with the specified application context.
isc_result_t	isc_socket_recvv (isc_socket_t *sock, isc_bufferlist_t *buflist, unsigned int minimum, isc_task_t *task, isc_taskaction_t action, void *arg)
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)
isc_result_t	isc_socket_send (isc_socket_t *sock, isc_region_t *region, isc_task_t *task, isc_taskaction_t action, void *arg)
isc_result_t	isc_socket_sendv (isc_socket_t *sock, isc_bufferlist_t *buflist, isc_task_t *task, isc_taskaction_t action, void *arg)
isc_result_t	isc_socket_sendtov (isc_socket_t *sock, isc_bufferlist_t *buflist, isc_task_t *task, isc_taskaction_t action, void *arg, isc_sockaddr_t *address, struct in6_pktinfo *pktinfo)
isc_result_t	isc_socket_sendtov2 (isc_socket_t *sock, isc_bufferlist_t *buflist, isc_task_t *task, isc_taskaction_t action, void *arg, isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, unsigned int flags)
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)
void	isc_socket_cleanunix (isc_sockaddr_t *sockaddr, isc_boolean_t active)
	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.
isc_result_t	isc_socket_permunix (isc_sockaddr_t *sockaddr, isc_uint32_t perm, isc_uint32_t owner, isc_uint32_t group)
	Set ownership and file permissions on the UNIX domain socket.
isc_result_t	isc_socket_filter (isc_socket_t *sock, const char *filter)
	Inform the kernel that it should perform accept filtering. If filter is NULL the current filter will be removed.:w.
isc_result_t	isc_socket_listen (isc_socket_t *sock, unsigned int backlog)
	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().
isc_result_t	isc_socket_accept (isc_socket_t *sock, isc_task_t *task, isc_taskaction_t action, void *arg)
	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'.
isc_result_t	isc_socket_getpeername (isc_socket_t *sock, isc_sockaddr_t *addressp)
	Get the name of the peer connected to 'socket'.
Variables
static isc_mutex_t	createlock
static isc_once_t	once = ISC_ONCE_INIT
static isc_socketmgrcreatefunc_t	socketmgr_createfunc = NULL

---

Function Documentation

static void initialize

(

void

)

[static]

Definition at line 33 of file socket_api.c.

References createlock, isc_mutex_init, ISC_R_SUCCESS, and RUNTIME_CHECK.

isc_result_t isc_socket_register

(

isc_socketmgrcreatefunc_t

createfunc

)

Register a new socket I/O implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

Definition at line 38 of file socket_api.c.

References createlock, initialize(), isc_once_do, ISC_R_EXISTS, ISC_R_SUCCESS, LOCK, once, RUNTIME_CHECK, socketmgr_createfunc, and UNLOCK.

Referenced by isc__socket_getfd().

isc_result_t isc_socketmgr_createinctx	(	isc_mem_t *	mctx,
		isc_appctx_t *	actx,
		isc_socketmgr_t **	managerp
	)

Send the contents of 'region' to the socket's peer.

Notes:

• Shutting down the requestor's task *may* result in any still pending writes being dropped or completed, depending on the underlying OS implementation.

• If 'action' is NULL, then no completion event will be posted.

• The caller may not modify 'region', the buffers which are passed into this function, or any data they refer to until the completion event is received.

• For isc_socket_sendv() and isc_socket_sendtov(): 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.

• For isc_socket_sendto2(): 'event' is not NULL, and the non-socket specific fields are expected to be initialized.

• For isc_socket_sendto2(): The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE and ISC_SOCKFLAG_NORETRY.

• If ISC_SOCKFLAG_IMMEDIATE is 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.

• ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set 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.

Requires:

• 'socket' is a valid, bound socket.

• For isc_socket_send(): 'region' is a valid region

• For isc_socket_sendv() and isc_socket_sendtov(): 'buflist' is non-NULL, and '*buflist' contain at least one buffer.

• 'task' is a valid task

• For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and isc_socket_sendto(): action == NULL or is a valid action

• For isc_socket_sendto2(): event != NULL

Returns:

• ISC_R_SUCCESS
• ISC_R_INPROGRESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED

Event results:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED
• XXX needs other net-type errors

Definition at line 54 of file socket_api.c.

References createlock, isc_appctx_setsocketmgr(), ISC_R_SUCCESS, LOCK, REQUIRE, socketmgr_createfunc, and UNLOCK.

Referenced by dns_client_create().

isc_result_t isc_socketmgr_create	(	isc_mem_t *	mctx,
		isc_socketmgr_t **	managerp
	)

Definition at line 73 of file socket_api.c.

References createlock, isc__socketmgr_create(), isc_bind9, LOCK, REQUIRE, socketmgr_createfunc, and UNLOCK.

Referenced by create_managers(), main(), setup_libs(), and setup_system().

void isc_socketmgr_destroy

(

isc_socketmgr_t **

managerp

)

Destroy a socket manager.

Notes:

• This routine blocks until there are no sockets left in the manager, 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:

• '*managerp' is a valid isc_socketmgr_t.

• All sockets managed by this manager are fully detached.

Ensures:

• *managerp == NULL

• All resources used by the manager have been freed.

Definition at line 90 of file socket_api.c.

References ENSURE, isc__socketmgr_destroy(), isc_bind9, ISCAPI_SOCKETMGR_VALID, and REQUIRE.

Referenced by cleanup(), cleanup_managers(), destroy_libs(), destroy_managers(), destroyclient(), dns_client_create(), and main().

isc_result_t isc_socket_create	(	isc_socketmgr_t *	manager,
		int	pf,
		isc_sockettype_t	type,
		isc_socket_t **	socketp
	)

Create a new 'type' socket managed by 'manager'.

For isc_sockettype_fdwatch sockets you should use isc_socket_fdwatchcreate() rather than isc_socket_create().

Note:

• 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6.

Requires:

• 'manager' is a valid manager

• 'socketp' is a valid pointer, and *socketp == NULL

• 'type' is not isc_sockettype_fdwatch

Ensures:

'*socketp' is attached to the newly created socket

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_NORESOURCES
• ISC_R_UNEXPECTED

Definition at line 102 of file socket_api.c.

References isc__socket_create(), isc_bind9, ISCAPI_SOCKETMGR_VALID, isc_socketmgr::methods, REQUIRE, and isc_socketmgrmethods::socketcreate.

Referenced by add_listener(), ATF_TC_BODY(), create_tcp_dispatch(), fctx_query(), listener_bind(), ns_interface_accepttcp(), ns_interfacemgr_create(), open_socket(), rndc_startconnect(), send_tcp_connect(), send_udp(), and xfrin_start().

void isc_socket_attach	(	isc_socket_t *	sock,
		isc_socket_t **	socketp
	)

Attach *socketp to socket.

Requires:

• 'socket' is a valid socket.

• 'socketp' points to a NULL socket.

Ensures:

• *socketp is attached to socket.

Definition at line 114 of file socket_api.c.

References isc_socketmethods::attach, ENSURE, isc__socket_attach(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by connect_done(), dns_dispatch_createtcp2(), get_client(), get_worker(), isc_httpdmgr_create(), listener_copysock(), ns_lwdclientmgr_create(), and send_tcp_connect().

void isc_socket_detach

(

isc_socket_t **

socketp

)

Detach *socketp from its socket.

Requires:

• 'socketp' points to a valid socket.

• If '*socketp' is the last reference to the socket, then:

There must be no pending I/O requests.

Ensures:

• *socketp is NULL.

• If '*socketp' is the last reference to the socket, then:

The socket will be shutdown (both reading and writing) for all tasks.

All resources used by the socket have been freed

Definition at line 127 of file socket_api.c.

References ENSURE, isc__socket_detach(), isc_bind9, ISCAPI_SOCKET_VALID, and REQUIRE.

Referenced by add_listener(), ATF_TC_BODY(), clear_query(), connect_done(), control_newconn(), control_recvmessage(), control_senddone(), create_tcp_dispatch(), destroy_client(), destroy_disp(), destroy_dispsocket(), destroy_libs(), dispatch_createudp(), dns_dispatch_createtcp2(), exit_check(), fctx_query(), flush_lookup_list(), free_listener(), get_dispsocket(), get_udpsocket(), httpdmgr_destroy(), isc_httpd_accept(), isc_httpdmgr_create(), launch_next_query(), listener_bind(), lwdclientmgr_destroy(), maybe_free(), ns_interface_accepttcp(), ns_interface_destroy(), ns_interfacemgr_create(), ns_interfacemgr_destroy(), ns_interfacemgr_shutdown(), ns_lwreslistener_detach(), open_socket(), process_sendevent(), recv_done(), resquery_connected(), rndc_connected(), rndc_recvdone(), rndc_senddone(), tcp_length_done(), and xfrin_reset().

isc_result_t isc_socket_bind	(	isc_socket_t *	sock,
		isc_sockaddr_t *	addressp,
		unsigned int	options
	)

Bind 'socket' to '*addressp'.

Requires:

• 'socket' is a valid socket

• 'addressp' points to a valid isc_sockaddr.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOPERM
• ISC_R_ADDRNOTAVAIL
• ISC_R_ADDRINUSE
• ISC_R_BOUND
• ISC_R_UNEXPECTED

Definition at line 139 of file socket_api.c.

References isc_socketmethods::bind, isc__socket_bind(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by add_listener(), ATF_TC_BODY(), create_tcp_dispatch(), fctx_query(), listener_bind(), ns_interface_accepttcp(), open_socket(), rndc_startconnect(), send_tcp_connect(), send_udp(), and xfrin_start().

isc_result_t isc_socket_sendto	(	isc_socket_t *	sock,
		isc_region_t *	region,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg,
		isc_sockaddr_t *	address,
		struct in6_pktinfo *	pktinfo
	)

Definition at line 151 of file socket_api.c.

References isc__socket_sendto(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, REQUIRE, and isc_socketmethods::sendto.

Referenced by ATF_TC_BODY(), and ns_lwdclient_sendreply().

isc_result_t isc_socket_connect	(	isc_socket_t *	sock,
		isc_sockaddr_t *	addressp,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Connect 'socket' to peer with address *saddr. When the connection succeeds, or when an error occurs, a CONNECT event with action 'action' and arg 'arg' will be posted to the event queue for 'task'.

Requires:

• 'socket' is a valid TCP socket

• 'addressp' points to a valid isc_sockaddr

• 'task' is a valid task

• 'action' is a valid action

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED

Posted event's result code:

• ISC_R_SUCCESS
• ISC_R_TIMEDOUT
• ISC_R_CONNREFUSED
• ISC_R_NETUNREACH
• ISC_R_UNEXPECTED

Definition at line 166 of file socket_api.c.

References isc_socketmethods::connect, isc__socket_connect(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by ATF_TC_BODY(), dns_request_createraw4(), dns_request_createvia4(), fctx_query(), resquery_send(), rndc_startconnect(), send_tcp_connect(), and xfrin_start().

isc_result_t isc_socket_recv	(	isc_socket_t *	sock,
		isc_region_t *	region,
		unsigned int	minimum,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Definition at line 178 of file socket_api.c.

References isc__socket_recv(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, isc_socketmethods::recv, and REQUIRE.

Referenced by ATF_TC_BODY(), dns_tcpmsg_readmessage(), isc_httpd_accept(), isc_httpd_recvdone(), isc_httpd_senddone(), isccc_ccmsg_readmessage(), ns_interfacemgr_create(), ns_lwdclient_startrecv(), and recv_length().

void isc_socket_cancel	(	isc_socket_t *	sock,
		isc_task_t *	task,
		unsigned int	how
	)

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:

• "socket" is a valid socket

• "task" is NULL or a valid task

"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.

• ISC_SOCKCANCEL_RECV: Cancel pending isc_socket_recv() calls.

• ISC_SOCKCANCEL_SEND: Cancel pending isc_socket_send() and isc_socket_sendto() calls.

• ISC_SOCKCANCEL_ACCEPT: Cancel pending isc_socket_accept() calls.

• ISC_SOCKCANCEL_CONNECT: Cancel pending isc_socket_connect() call.

Definition at line 191 of file socket_api.c.

References isc_socketmethods::cancel, isc__socket_cancel(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by cancel_all(), cancel_lookup(), connect_timeout(), dns_dispatch_changeattributes(), dns_dispatch_detach(), dns_dispatch_getudp_dup(), dns_dispatch_removeresponse(), dns_dispatchset_cancelall(), dns_tcpmsg_cancelread(), exit_check(), fctx_cancelquery(), flush_lookup_list(), isc_httpdmgr_shutdown(), isccc_ccmsg_cancelread(), lwdclientmgr_shutdown_callback(), main(), maybe_free_connection(), ns_interfacemgr_shutdown(), req_cancel(), shutdown_listener(), xfrin_cancelio(), and xfrout_maybe_destroy().

isc_result_t isc_socket_getsockname	(	isc_socket_t *	sock,
		isc_sockaddr_t *	addressp
	)

Get the name of 'socket'.

Requires:

• 'socket' is a valid socket.

Returns:

• ISC_R_SUCCESS
• ISC_R_TOOSMALL
• ISC_R_UNEXPECTED

Definition at line 201 of file socket_api.c.

References isc_socketmethods::getsockname, isc__socket_getsockname(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by client_request(), dns_dispatch_gettcp(), dns_dispatch_gettcp2(), local_addr_match(), portavailable(), and xfrin_connect_done().

void isc_socket_ipv6only	(	isc_socket_t *	sock,
		isc_boolean_t	yes
	)

Intended for internal use in BIND9 only.

If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket option if the host OS supports this option.

Requires:

• 'sock' is a valid socket.

Definition at line 211 of file socket_api.c.

References isc_socketmethods::ipv6only, isc__socket_ipv6only(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by add_listener(), ns_interface_accepttcp(), and open_socket().

void isc_socket_dscp	(	isc_socket_t *	sock,
		isc_dscp_t	dscp
	)

Sets the Differentiated Services Code Point (DSCP) field for packets transmitted on this socket. If 'dscp' is -1, return immediately.

Requires:

• 'sock' is a valid socket.

Definition at line 221 of file socket_api.c.

References isc_socketmethods::dscp, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by ATF_TC_BODY(), create_tcp_dispatch(), fctx_query(), ns_interface_accepttcp(), resquery_send(), send_tcp_connect(), send_udp(), and xfrin_start().

isc_sockettype_t isc_socket_gettype

(

isc_socket_t *

sock

)

Returns the socket type for "sock.".

Requires:

• "sock" is a valid socket.

Definition at line 228 of file socket_api.c.

References isc_socketmethods::gettype, isc__socket_gettype(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by dns_dispatch_createtcp2().

void isc_socket_setname	(	isc_socket_t *	sock,
		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.

Definition at line 238 of file socket_api.c.

References ISCAPI_SOCKET_VALID, REQUIRE, and UNUSED.

Referenced by add_listener(), client_newconn(), control_newconn(), get_worker(), isc_httpd_accept(), ns_interface_accepttcp(), open_socket(), and xfrin_start().

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:

• 'fd' is the already-opened file descriptor.
• This function is not available on Windows.
• 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:

• 'manager' is a valid manager

• 'socketp' is a valid pointer, and *socketp == NULL

• 'fd' be opened.

Ensures:

'*socketp' is attached to the newly created fdwatch socket

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_NORESOURCES
• ISC_R_UNEXPECTED

Definition at line 247 of file socket_api.c.

References isc_socketmgrmethods::fdwatchcreate, isc__socket_fdwatchcreate(), isc_bind9, ISCAPI_SOCKETMGR_VALID, isc_socketmgr::methods, and REQUIRE.

isc_result_t isc_socket_fdwatchpoke	(	isc_socket_t *	sock,
		int	flags
	)

Poke a file descriptor watch socket informing the manager that it should restart watching the socket.

Note:

• 'sock' is the socket returned by isc_socket_fdwatchcreate

• 'flags' indicates what the manager should watch for on the socket in addition to what it may already be watching. It can be one or both of ISC_SOCKFDWATCH_READ and ISC_SOCKFDWATCH_WRITE. To temporarily disable watching on a socket the value indicating no more data should be returned from the call back routine.

• This function is not available on Windows.

Requires:

• 'sock' is a valid isc socket

Returns:

• ISC_R_SUCCESS

Definition at line 264 of file socket_api.c.

References isc_socketmethods::fdwatchpoke, isc__socket_fdwatchpoke(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

isc_result_t isc_socket_dup	(	isc_socket_t *	sock,
		isc_socket_t **	socketp
	)

Duplicate an existing socket, reusing its file descriptor.

Definition at line 275 of file socket_api.c.

References isc_socketmethods::dup, isc__socket_dup(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by ATF_TC_BODY(), and open_socket().

int isc_socket_getfd

(

isc_socket_t *

sock

)

Get the file descriptor associated with a socket.

Definition at line 286 of file socket_api.c.

References isc_socketmethods::getfd, isc__socket_getfd(), isc_bind9, ISCAPI_SOCKET_VALID, isc_socket::methods, and REQUIRE.

Referenced by dispatch_createudp().

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 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.

isc_socket_open() should not be called on sockets created by isc_socket_fdwatchcreate().

Requires:

• there must be no other reference to this socket.

• 'socket' is a valid and previously closed by isc_socket_close()

• 'sock->type' is not isc_sockettype_fdwatch

Returns: Same as isc_socket_create().

• ISC_R_NOTIMPLEMENTED

Definition at line 296 of file socket_api.c.

References isc__socket_open().

Referenced by open_socket().

isc_result_t 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 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.

isc_socket_close() should not be called on sockets created by isc_socket_fdwatchcreate().

Requires:

• The socket must have a valid descriptor.

• There must be no other reference to this socket.

• There must be no pending I/O requests.

• 'sock->type' is not isc_sockettype_fdwatch

Returns:

• ISC_R_NOTIMPLEMENTED

Definition at line 301 of file socket_api.c.

References isc__socket_close().

Referenced by deactivate_dispsocket(), and open_socket().

isc_result_t isc_socketmgr_create2	(	isc_mem_t *	mctx,
		isc_socketmgr_t **	managerp,
		unsigned int	maxsocks
	)

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. isc_socketmgr_createinctx() also associates the new manager with the specified application context.

Notes:

• All memory will be allocated in memory context 'mctx'.

Requires:

• 'mctx' is a valid memory context.

• 'managerp' points to a NULL isc_socketmgr_t.

• 'actx' is a valid application context (for createinctx()).

Ensures:

• '*managerp' is a valid isc_socketmgr_t.

Returns:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED
• ISC_R_NOTIMPLEMENTED

Definition at line 306 of file socket_api.c.

References isc__socketmgr_create2().

Referenced by create_managers().

isc_result_t isc_socket_recvv	(	isc_socket_t *	sock,
		isc_bufferlist_t *	buflist,
		unsigned int	minimum,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Definition at line 313 of file socket_api.c.

References isc__socket_recvv().

Referenced by launch_next_query(), recv_done(), send_udp(), and tcp_length_done().

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
	)

Definition at line 321 of file socket_api.c.

References isc__socket_recv2().

Referenced by client_udprecv(), and startrecv().

isc_result_t isc_socket_send	(	isc_socket_t *	sock,
		isc_region_t *	region,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Receive from 'socket', storing the results in region.

Notes:

• Let 'length' refer to the length of 'region' or to the sum of all available regions in the list of buffers '*buflist'.

• If 'minimum' is non-zero and at least that many bytes are read, the completion event will be posted to the task 'task.' If minimum is zero, the exact number of bytes requested in the region must be read for an event to be posted. This only makes sense for TCP connections, and is always set to 1 byte for UDP.

• The read will complete when the desired number of bytes have been 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'.

• The caller may not modify 'region', the buffers which are passed into this function, or any data they refer to until the completion event is received.

• For isc_socket_recvv(): 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.

• For isc_socket_recv2(): 'event' is not NULL, and the non-socket specific fields are expected to be initialized.

• For isc_socket_recv2(): 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.

Requires:

• 'socket' is a valid, bound socket.

• For isc_socket_recv(): 'region' is a valid region

• For isc_socket_recvv(): 'buflist' is non-NULL, and '*buflist' contain at least one buffer.

• 'task' is a valid task

• For isc_socket_recv() and isc_socket_recvv(): action != NULL and is a valid action

• For isc_socket_recv2(): event != NULL

Returns:

• ISC_R_SUCCESS
• ISC_R_INPROGRESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED

Event results:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED
• XXX needs other net-type errors

Definition at line 329 of file socket_api.c.

References isc__socket_send().

Referenced by control_recvmessage(), rndc_connected(), rndc_recvnonce(), sendstream(), and xfrin_send_request().

isc_result_t isc_socket_sendv	(	isc_socket_t *	sock,
		isc_bufferlist_t *	buflist,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Definition at line 336 of file socket_api.c.

References isc__socket_sendv().

Referenced by isc_httpd_recvdone(), and launch_next_query().

isc_result_t isc_socket_sendtov	(	isc_socket_t *	sock,
		isc_bufferlist_t *	buflist,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg,
		isc_sockaddr_t *	address,
		struct in6_pktinfo *	pktinfo
	)

Definition at line 343 of file socket_api.c.

References isc__socket_sendtov().

isc_result_t isc_socket_sendtov2	(	isc_socket_t *	sock,
		isc_bufferlist_t *	buflist,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg,
		isc_sockaddr_t *	address,
		struct in6_pktinfo *	pktinfo,
		unsigned int	flags
	)

Definition at line 352 of file socket_api.c.

References isc__socket_sendtov2().

Referenced by send_udp().

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
	)

Definition at line 362 of file socket_api.c.

References isc__socket_sendto2().

Referenced by ATF_TC_BODY(), client_sendpkg(), req_send(), and resquery_send().

void isc_socket_cleanunix	(	isc_sockaddr_t *	addr,
		isc_boolean_t	active
	)

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()).

Definition at line 372 of file socket_api.c.

References isc__socket_cleanunix().

Referenced by add_listener(), and shutdown_listener().

isc_result_t isc_socket_permunix	(	isc_sockaddr_t *	sockaddr,
		isc_uint32_t	perm,
		isc_uint32_t	owner,
		isc_uint32_t	group
	)

Set ownership and file permissions on the UNIX domain socket.

Note: On Solaris and SunOS this secures the directory containing the socket as Solaris and SunOS do not honour the filesystem permissions on the socket.

Requires:

• 'sockaddr' to be a valid UNIX domain sockaddr.

Returns:

• ISC_R_SUCCESS
• ISC_R_FAILURE

Definition at line 377 of file socket_api.c.

References isc__socket_permunix().

Referenced by add_listener(), and update_listener().

isc_result_t isc_socket_filter	(	isc_socket_t *	sock,
		const char *	filter
	)

Inform the kernel that it should perform accept filtering. If filter is NULL the current filter will be removed.:w.

Definition at line 384 of file socket_api.c.

References isc__socket_filter().

Referenced by isc_httpdmgr_create(), and ns_interface_accepttcp().

isc_result_t isc_socket_listen	(	isc_socket_t *	sock,
		unsigned int	backlog
	)

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().

Notes:

• 'backlog' is as in the UNIX system call listen() and may be ignored by non-UNIX implementations.

• If 'backlog' is zero, a reasonable system default is used, usually SOMAXCONN.

Requires:

• 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket.

Returns:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED

Definition at line 389 of file socket_api.c.

References isc__socket_listen().

Referenced by ATF_TC_BODY(), control_listen(), isc_httpdmgr_create(), and ns_interface_accepttcp().

isc_result_t isc_socket_accept	(	isc_socket_t *	sock,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

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'.

REQUIRES:

• 'socket' is a valid TCP socket that isc_socket_listen() was called on.

• 'task' is a valid task

• 'action' is a valid action

RETURNS:

• ISC_R_SUCCESS
• ISC_R_NOMEMORY
• ISC_R_UNEXPECTED

Definition at line 394 of file socket_api.c.

References isc__socket_accept().

Referenced by ATF_TC_BODY(), client_accept(), control_accept(), isc_httpd_accept(), and isc_httpdmgr_create().

isc_result_t isc_socket_getpeername	(	isc_socket_t *	sock,
		isc_sockaddr_t *	addressp
	)

Get the name of the peer connected to 'socket'.

Requires:

• 'socket' is a valid TCP socket.

Returns:

• ISC_R_SUCCESS
• ISC_R_TOOSMALL
• ISC_R_UNEXPECTED

Definition at line 401 of file socket_api.c.

References isc__socket_getpeername().

Referenced by client_newconn(), control_newconn(), control_senddone(), dns_dispatch_gettcp(), dns_dispatch_gettcp2(), get_worker(), isc_httpd_accept(), and log_invalid().

---

Variable Documentation

isc_mutex_t createlock [static]

Definition at line 28 of file socket_api.c.

isc_once_t once = ISC_ONCE_INIT [static]

Definition at line 29 of file socket_api.c.

isc_socketmgrcreatefunc_t socketmgr_createfunc = NULL [static]

Definition at line 30 of file socket_api.c.

Referenced by isc_socket_register(), isc_socketmgr_create(), and isc_socketmgr_createinctx().

---