sofop_attach_active

, sofop_attach_passive

, sofop_detach

- attach or detach a socket filter

Synopsis

#include <sys/sockfilter.h>

sof_rval_t prefix_attach_active(sof_handle_t hdl, int family,
     int type, int protocol, cred_t *cr, void **cookiep);

sof_rval_t prefix_attach_passive(sof_handle_t hdl,
     sof_handle_t phdl, void *pcookie, struct sockaddr *laddr,
     socklen_t laddrlen, struct sockaddr *paddr, socklen_t paddrlen,
     void **cookiep);

void prefix_detach(sof_handle_t hdl, void *cookie, cred_t *cr);

Parameters

hdl

per-socket filter handle

cookie

per-socket filter-private data

family

protocol family

type

socket type

protocol

protocol number

phdl

filter handle of the parent socket

pcookie

filter-private data of the parent socket

laddr

pointer to local address of the new connection

laddrlen

length of the local address, in bytes

paddr

pointer to peer address of the new connection

paddrlen

length of the peer address, in bytes

cookiep

result parameter, modified on return to point to the filter-private data for the socket to which the filter is attaching

cr

pointer to the user credential structure for the operation

Description

The sofop_attach_active() and sofop_attach_passive() entry points are the filter-specific initialization entry points. The sofop_attach_active() entry point is called when the filter is attached to a socket that is actively opened via socket(3SOCKET) and that match the requirements that were established when the filter was configured with soconfig(1M). The sofop_attach_passive() entry point is called when a listening socket, to which the filter is already attached, creates a socket in response to an incoming connection request. The framework ensures that no other filter entry point will be called for the socket until the filter has returned from the attach entry point.

The filter may update cookiep to point to filter-private state for the socket. Any resources allocated during attach should be release in sofop_detach(). The sofop_attach_passive() entry point can modify both the peer and local address.

Returning an error from sofop_attach_active() or sofop_attach_passive() will cause the socket creation to fail, and in the case of sofop_attach_active(), return an error to socket().

The sofop_attach_passive() entry point can defer the notification of the new connection by returning SOF_RVAL_DEFER. The connection is unavailable to socket(3SOCKET) while it is deferred, but data and other protocol events can still call into entry points. The deferred connection is made available using sof_newconn_ready(9F), or discarded using sof_newconn_close(9F).

The sofop_detach() entry point is called when the filter is being detached from a socket, and it is the last entry point that is called. The filter can use the entry point to free any socket specific resources that was allocated. A filter that must wait, for example, for an asynchronous task to complete, should do so in sofop_notify(9E), when the SOF_EV_CLOSING event is received.

Socket filter functions (such as sof_inject_data_in(9F)) may not be called by sofop_attach_active(), sofop_attach_passive(), or sofop_detach().

Return Values

The sofop_attach_active() and sofop_attach_passive() entry points return:

SOF_RVAL_CONTINUE

Filter attached successfully.

SOF_RVAL_DETACH

Filter will be detached from the socket immediately and no additional callbacks will be received.

SOF_RVAL_EPERM

Permission denied.

SOF_RVAL_ENOMEM

There was insufficient memory for the operation to complete.

The sofop_attach_passive() entry point may also return:

SOF_RVAL_DEFER

The new connection will be deferred.

Context

All of the above entry points can be called from kernel or user context. In addition, the sofop_attach_passive() and sofop_detach() entry points can be called from interrupt context.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

soconfig(1M), accept(3SOCKET), socket(3SOCKET), attributes(5), sof_bypass(9F), sof_inject_data_in(9F), sof_newconn_close(9F), sof_newconn_ready(9F), sofop_notify(9E), sof_ops(9S)