File:  [DragonFly] / src / share / man / man9 / accept_filter.9
Revision 1.2: download - view: text, annotated - select for diffs
Tue Jun 17 04:37:01 2003 UTC (11 years, 1 month ago) by dillon
Branches: MAIN
CVS tags: HEAD
Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids.  Most
ids have been removed from !lint sections and moved into comment sections.

    1: .\"
    2: .\" Copyright (c) 2000 Alfred Perlstein
    3: .\"
    4: .\" All rights reserved.
    5: .\"
    6: .\" Redistribution and use in source and binary forms, with or without
    7: .\" modification, are permitted provided that the following conditions
    8: .\" are met:
    9: .\" 1. Redistributions of source code must retain the above copyright
   10: .\"    notice, this list of conditions and the following disclaimer.
   11: .\" 2. Redistributions in binary form must reproduce the above copyright
   12: .\"    notice, this list of conditions and the following disclaimer in the
   13: .\"    documentation and/or other materials provided with the distribution.
   14: .\"
   15: .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
   16: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   17: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   18: .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
   19: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
   20: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   21: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   22: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   23: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   24: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   25: .\"
   26: .\" $FreeBSD: src/share/man/man9/accept_filter.9,v 1.2.2.6 2002/12/29 16:35:39 schweikh Exp $
   27: .\" $DragonFly: src/share/man/man9/accept_filter.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
   28: .\" "
   29: .Dd June 25, 2000
   30: .Os
   31: .Dt ACCEPT_FILTER 9
   32: .Sh NAME
   33: .Nm accept_filter ,
   34: .Nm accept_filt_add ,
   35: .Nm accept_filt_del ,
   36: .Nm accept_filt_generic_mod_event ,
   37: .Nm accept_filt_get
   38: .Nd filter incoming connections
   39: .Sh SYNOPSIS
   40: .In sys/types.h
   41: .In sys/socket.h
   42: .In sys/socketvar.h
   43: .Ft int
   44: .Fn accept_filt_add "struct accept_filter *filt"
   45: .Ft int
   46: .Fn accept_filt_del "char *name"
   47: .Ft int
   48: .Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data"
   49: .Ft struct accept_filter *
   50: .Fn accept_filt_get "char *name"
   51: .Sh DESCRIPTION
   52: Accept filters allow an application to request
   53: that the kernel pre-process incoming connections.
   54: An accept filter is requested via the
   55: .Xr setsockopt 2
   56: system call, passing in an
   57: .Fa optname
   58: of
   59: .Dv SO_ACCEPTFILTER .
   60: .Sh IMPLEMENTATION NOTES
   61: A module that wants to be an accept filter
   62: must provide a struct accept_filter to the system:
   63: .Bd -literal
   64: struct accept_filter {
   65: 	char	accf_name[16];
   66: 	void	(*accf_callback)
   67: 		__P((struct socket *so, void *arg, int waitflag));
   68: 	void *	(*accf_create)
   69: 		__P((struct socket *so, char *arg));
   70: 	void	(*accf_destroy)
   71: 		__P((struct socket *so));
   72: 	SLIST_ENTRY(accept_filter) accf_next;	/* next on the list */
   73: };
   74: .Ed
   75: .Pp
   76: The module should register it with the function
   77: .Fn accept_filt_add ,
   78: passing a pointer to a struct accept_filter, allocated with
   79: .Xr MALLOC 9
   80: .Pp
   81: The fields of
   82: .Fa struct accept_filter
   83: are as follows:
   84: .Bl -tag -width accf_callbackXXX
   85: .It accf_name
   86: Name of the filter;
   87: this is how it will be accessed from userland.
   88: .It accf_callback
   89: The callback that the kernel will do
   90: once the connection is established.
   91: It is the same as a socket upcall
   92: and will be called when the connection is established
   93: and whenever new data arrives on the socket,
   94: unless the callback modifies the socket's flags.
   95: .It accf_create
   96: Called whenever a
   97: .Xr setsockopt 2
   98: installs the filter onto
   99: a listening socket.
  100: .It accf_destroy
  101: Called whenever the user removes the accept filter on the socket.
  102: .El
  103: .Pp
  104: .Fn accept_filt_del
  105: passed the same string used in accept_filter.accf_name during registration
  106: with
  107: .Fn accept_filt_add ,
  108: the kernel will then disallow and further userland use of the filter.
  109: .Pp
  110: .Fn accept_filt_get
  111: is used internally to locate which accept filter to use via the
  112: .Fn setsockopt
  113: syscall.
  114: .Pp
  115: .Fn accept_filt_generic_mod_event
  116: provides a simple way to avoid duplicate
  117: code for accept filters which don't use
  118: argument field to load and unload
  119: themselves.  It is a function that can be
  120: put in the load/unload struct
  121: for the
  122: .Fn DECLARE_MODULE
  123: macro.
  124: .Sh SEE ALSO
  125: .Xr setsockopt 2 ,
  126: .Xr accf_data 9 ,
  127: .Xr accf_http 9 ,
  128: .Xr malloc 9
  129: .Sh HISTORY
  130: The accept filter mechanism was introduced in
  131: .Fx 4.0 .
  132: .Sh AUTHORS
  133: This manual page was written by
  134: .An Alfred Perlstein ,
  135: Sheldon Hearn and Jeroen Ruigrok van der Werven.
  136: The accept filter concept was pioneered by David Filo at Yahoo!
  137: and refined to be a loadable module system by Alfred Perlstein.