'\" te .\" Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved. .TH sofop_attach_active 9E "9 May 2012" "SunOS 5.11" "Driver Entry Points" .SH NAME sofop_attach_active, sofop_attach_passive, sofop_detach \- attach or detach a socket filter .SH SYNOPSIS .LP .nf #include sof_rval_t prefix_attach_active(sof_handle_t \fIhdl\fR, int \fIfamily\fR, int \fItype\fR, int \fIprotocol\fR, cred_t *\fIcr\fR, void **\fIcookiep\fR); .fi .LP .nf sof_rval_t prefix_attach_passive(sof_handle_t \fIhdl\fR, sof_handle_t \fIphdl\fR, void *\fIpcookie\fR, struct sockaddr *\fIladdr\fR, socklen_t \fIladdrlen\fR, struct sockaddr *\fIpaddr\fR, socklen_t \fIpaddrlen\fR, void **\fIcookiep\fR); .fi .LP .nf void prefix_detach(sof_handle_t \fIhdl\fR, void *\fIcookie\fR, cred_t *\fIcr\fR); .fi .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIhdl\fR\fR .ad .RS 12n .rt per-socket filter handle .RE .sp .ne 2 .mk .na \fB\fIcookie\fR\fR .ad .RS 12n .rt per-socket filter-private data .RE .sp .ne 2 .mk .na \fB\fIfamily\fR\fR .ad .RS 12n .rt protocol family .RE .sp .ne 2 .mk .na \fB\fItype\fR\fR .ad .RS 12n .rt socket type .RE .sp .ne 2 .mk .na \fB\fIprotocol\fR\fR .ad .RS 12n .rt protocol number .RE .sp .ne 2 .mk .na \fB\fIphdl\fR\fR .ad .RS 12n .rt filter handle of the parent socket .RE .sp .ne 2 .mk .na \fB\fIpcookie\fR\fR .ad .RS 12n .rt filter-private data of the parent socket .RE .sp .ne 2 .mk .na \fB\fIladdr\fR\fR .ad .RS 12n .rt pointer to local address of the new connection .RE .sp .ne 2 .mk .na \fB\fIladdrlen\fR\fR .ad .RS 12n .rt length of the local address, in bytes .RE .sp .ne 2 .mk .na \fB\fIpaddr\fR\fR .ad .RS 12n .rt pointer to peer address of the new connection .RE .sp .ne 2 .mk .na \fB\fIpaddrlen\fR\fR .ad .RS 12n .rt length of the peer address, in bytes .RE .sp .ne 2 .mk .na \fB\fIcookiep\fR\fR .ad .RS 12n .rt result parameter, modified on return to point to the filter-private data for the socket to which the filter is attaching .RE .sp .ne 2 .mk .na \fB\fIcr\fR\fR .ad .RS 12n .rt pointer to the user credential structure for the operation .RE .SH DESCRIPTION .sp .LP The \fBsofop_attach_active()\fR and \fBsofop_attach_passive()\fR entry points are the filter-specific initialization entry points. The \fBsofop_attach_active()\fR entry point is called when the filter is attached to a socket that is actively opened via \fBsocket\fR(3SOCKET) and that match the requirements that were established when the filter was configured with \fBsoconfig\fR(1M). The \fBsofop_attach_passive()\fR 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. .sp .LP The filter may update \fIcookiep\fR to point to filter-private state for the socket. Any resources allocated during attach should be release in \fBsofop_detach()\fR. The \fBsofop_attach_passive()\fR entry point can modify both the peer and local address. .sp .LP Returning an error from \fBsofop_attach_active()\fR or \fBsofop_attach_passive()\fR will cause the socket creation to fail, and in the case of \fBsofop_attach_active()\fR, return an error to \fBsocket()\fR. .sp .LP The \fBsofop_attach_passive()\fR entry point can defer the notification of the new connection by returning \fBSOF_RVAL_DEFER\fR. The connection is unavailable to \fBsocket\fR(3SOCKET) while it is deferred, but data and other protocol events can still call into entry points. The deferred connection is made available using \fBsof_newconn_ready\fR(9F), or discarded using \fBsof_newconn_close\fR(9F). .sp .LP The \fBsofop_detach()\fR 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 \fBsofop_notify\fR(9E), when the \fBSOF_EV_CLOSING\fR event is received. .sp .LP Socket filter functions (such as \fBsof_inject_data_in\fR(9F)) may not be called by \fBsofop_attach_active()\fR, \fBsofop_attach_passive()\fR, or \fBsofop_detach()\fR. .SH RETURN VALUES .sp .LP The \fBsofop_attach_active()\fR and \fBsofop_attach_passive()\fR entry points return: .sp .ne 2 .mk .na \fB\fBSOF_RVAL_CONTINUE\fR\fR .ad .RS 21n .rt Filter attached successfully. .RE .sp .ne 2 .mk .na \fB\fBSOF_RVAL_DETACH\fR\fR .ad .RS 21n .rt Filter will be detached from the socket immediately and no additional callbacks will be received. .RE .sp .ne 2 .mk .na \fB\fBSOF_RVAL_EPERM\fR\fR .ad .RS 21n .rt Permission denied. .RE .sp .ne 2 .mk .na \fB\fBSOF_RVAL_ENOMEM\fR\fR .ad .RS 21n .rt There was insufficient memory for the operation to complete. .RE .sp .LP The \fBsofop_attach_passive()\fR entry point may also return: .sp .ne 2 .mk .na \fB\fBSOF_RVAL_DEFER\fR\fR .ad .RS 18n .rt The new connection will be deferred. .RE .SH CONTEXT .sp .LP All of the above entry points can be called from kernel or user context. In addition, the \fBsofop_attach_passive()\fR and \fBsofop_detach()\fR entry points can be called from interrupt context. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Availabilitysystem/kernel _ Interface StabilityUncommitted .TE .SH SEE ALSO .sp .LP \fBsoconfig\fR(1M), \fBaccept\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBsof_bypass\fR(9F), \fBsof_inject_data_in\fR(9F), \fBsof_newconn_close\fR(9F), \fBsof_newconn_ready\fR(9F), \fBsofop_notify\fR(9E), \fBsof_ops\fR(9S)