diff options
| -rw-r--r-- | share/man/man9/accept_filter.9 | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/share/man/man9/accept_filter.9 b/share/man/man9/accept_filter.9 new file mode 100644 index 0000000..a683651 --- /dev/null +++ b/share/man/man9/accept_filter.9 @@ -0,0 +1,133 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" " +.Dd June 25, 2000 +.Os +.Dt ACCEPT_FILTER 9 +.Sh NAME +.Nm accept_filter , +.Nm accept_filt_add , +.Nm accept_filt_del , +.Nm accept_filt_generic_mod_event , +.Nm accept_filt_get +.Nd filter incoming connections +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/socket.h> +.Fd #include <sys/socketvar.h> +.Ft int +.Fn accept_filt_add "struct accept_filter *filt" +.Ft int +.Fn accept_filt_del "char *name" +.Ft int +.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data" +.Ft struct accept_filter * +.Fn accept_filt_get "char *name" +.Sh DESCRIPTION +Accept filters allow an application to request +that the kernel pre-process incoming connections. +An accept filter is requested via the +.Xr setsockopt 2 +system call, passing in an +.Fa optname +of +.Dv SO_ACCEPTFILTER . +.Sh IMPLEMENTATION NOTES +A module that wants to be an accept filter +must provide a struct accept_filter to the system: +.Bd -literal +struct accept_filter { + char accf_name[16]; + void (*accf_callback) + __P((struct socket *so, void *arg, int waitflag)); + void * (*accf_create) + __P((struct socket *so, char *arg)); + void (*accf_destroy) + __P((struct socket *so)); + SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ +}; +.Ed +.Pp +The module should register it with the function +.Fn accept_filt_add , +passing a pointer to a struct accept_filter, allocated with +.Xr MALLOC 9 +.Pp +The fields of +.Fa struct accept_filter +are as follows: +.Bl -tag -width accf_callbackXXX +.It accf_name +Name of the filter; +this is how it will be accessed from userland. +.It accf_callback +The callback that the kernel will do +once the connection is established. +It is the same as a socket upcall +and will be called when the connection is established +and whenever new data arrives on the socket, +unless the callback modifies the socket's flags. +.It accf_create +Called whenever a +.Xr setsockopt 2 +installs the filter onto +a listening socket. +.It accf_destroy +Called whenever the user removes the accept filter on the socket. +.El +.Pp +.Fn accept_filt_del +passed the same string used in accept_filter.accf_name during registration +with +.Fn accept_filt_add , +the kernel will then disallow and further userland use of the filter. +.Pp +.Fn accept_filt_get +is used internally to locate which accept filter to use via the +.Fn setsocketopt +syscall. +.Pp +.Fn accept_filt_generic_mod_event +provides a simple way to avoid duplicate +code for accept filters which don't use +argument field to load and unload +themselves. It is a function that can be +put in the load/unload struct +for the +.Fn DECLARE_MODULE +macro. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr malloc 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page has been written by +.An Alfred Perlstein . +The accept filter concept was pioneered by engineers at Yahoo.com +and refined to be a loadable module system by Alfred Perlstein. |
