diff options
author | davidc <davidc@FreeBSD.org> | 2001-12-07 20:58:07 +0000 |
---|---|---|
committer | davidc <davidc@FreeBSD.org> | 2001-12-07 20:58:07 +0000 |
commit | be29456bc43b8c5ac3ee45ea4f345a65df0637ff (patch) | |
tree | 72110d41f4230e363f9284ec3ac374780c53c884 | |
parent | f65d8046100200d4b8305bc9e21bcd1eff107c78 (diff) | |
download | FreeBSD-src-be29456bc43b8c5ac3ee45ea4f345a65df0637ff.zip FreeBSD-src-be29456bc43b8c5ac3ee45ea4f345a65df0637ff.tar.gz |
Add a man page describing the fuctions directly related to network domains.
Reviewed by: alfred
-rw-r--r-- | share/man/man9/Makefile | 9 | ||||
-rw-r--r-- | share/man/man9/domain.9 | 225 |
2 files changed, 234 insertions, 0 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index d6a13e5..3f644de 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -37,6 +37,7 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \ device_ids.9 \ device_probe_and_attach.9 device_quiet.9 device_set_desc.9 \ device_set_flags.9 devstat.9 devsw.9 devtoname.9 driver.9 \ + domain.9 \ extattr.9 \ fetch.9 \ get_cyclecounter.9 \ @@ -232,6 +233,14 @@ MLINKS+=device_set_desc.9 device_set_desc_copy.9 MLINKS+=device_set_flags.9 device_get_flags.9 MLINKS+=devclass_add_driver.9 devclass_delete_driver.9 MLINKS+=devclass_add_driver.9 devclass_find_driver.9 + +MLINKS+=domain.9 net_add_domain.9 +MLINKS+=domain.9 pfctlinput.9 +MLINKS+=domain.9 pfctlinput2.9 +MLINKS+=domain.9 pffindproto.9 +MLINKS+=domain.9 pffindtype.9 +MLINKS+=domain.9 DOMAIN_SET.9 + MLINKS+=BUS_READ_IVAR.9 BUS_WRITE_IVAR.9 MLINKS+=BUS_SETUP_INTR.9 bus_setup_intr.9 MLINKS+=BUS_SETUP_INTR.9 BUS_TEARDOWN_INTR.9 diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9 new file mode 100644 index 0000000..28b5ab7 --- /dev/null +++ b/share/man/man9/domain.9 @@ -0,0 +1,225 @@ +.\" +.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 December 7, 2001 +.Dt DOMAIN 9 +.Os +.Sh NAME +.Nm net_add_domain , +.Nm pfctlinput , +.Nm pfctlinput2 , +.Nm pffindproto , +.Nm pffindtype , +.Nm DOMAIN_SET +.Nd "network domain management" +.Sh SYNOPSIS +.In sys/param.h +.In sys/protosw.h +.In sys/domain.h +.Ft void +.Fn net_add_domain "void *data" +.Ft void +.Fn pfctlinput "int cmd" "struct sockaddr *sa" +.Ft void +.Fn pfctlinput2 "int cmd" "struct sockaddr *sa" "void *ctlparam" +.Ft struct protosw * +.Fn pffindproto "int family" "int protocol" "int type" +.Ft struct protosw * +.Fn pffindtype "int family" "int type" +.Ft void +.Fn DOMAIN_SET "name" +.Sh DESCRIPTION +Network protocols installed in the system are maintained within what +are called domains +.Pq for example the inetdomain and localdomain . +.Bd -literal + +struct domain { + int dom_family; /* AF_xxx */ + char *dom_name; + void (*dom_init) /* initialize domain data structures */ + __P((void)); + int (*dom_externalize) /* externalize access rights */ + __P((struct mbuf *, struct mbuf **)); + void (*dom_dispose) /* dispose of internalized rights */ + __P((struct mbuf *)); + struct protosw *dom_protosw, *dom_protoswNPROTOSW; + struct domain *dom_next; + int (*dom_rtattach) /* initialize routing table */ + __P((void **, int)); + int dom_rtoffset; /* an arg to rtattach, in bits */ + int dom_maxrtkey; /* for routing layer */ +}; +.Ed +.Pp +Each domain contains an array of protocol switch structures +.Pq Vt struct protosw * , +one for each socket type supported. +.Bd -literal + +struct protosw { + short pr_type; /* socket type used for */ + struct domain *pr_domain; /* domain protocol a member of */ + short pr_protocol; /* protocol number */ + short pr_flags; /* see below */ +/* protocol-protocol hooks */ + pr_input_t *pr_input; /* input to protocol (from below) */ + pr_output_t *pr_output; /* output to protocol (from above) */ + pr_ctlinput_t *pr_ctlinput; /* control input (from below) */ + pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ +/* user-protocol hook */ + pr_usrreq_t *pr_ousrreq; +/* utility hooks */ + pr_init_t *pr_init; + pr_fasttimo_t *pr_fasttimo; /* fast timeout (200ms) */ + pr_slowtimo_t *pr_slowtimo; /* slow timeout (500ms) */ + pr_drain_t *pr_drain; /* flush any excess space possible */ + + struct pr_usrreqs *pr_usrreqs; /* supersedes pr_usrreq() */ + struct pfil_head pr_pfh; +}; +.Ed +.Pp +The following functions handle the registration of a new domain, +lookups of specific protocols and protocol types within those domains, +and handle control messages from the system. +.Pp +.Fn pfctlinput +is called by the system whenever an event occurs that could affect every +domain. +Examples of those types of events are routing table changes, interface +shutdowns or certain +.Dv ICMP +message types. +When called, +.Fn pfctlinput +calls the protocol specific +.Fn pr_ctlinput +function for each protocol in that has defined one, in every domain. +.Pp +.Fn pfctlinput2 +provides that same functionality of +.Fn pfctlinput , +but with a few additional checks and a new +.Vt void * +argument that is passed directly to the protocols +.Fn pr_ctlinput +function. +Unlike +.Fn pfctlinput , +.Fn pfctlinput2 +verifies that +.Fa sa +is not +.Dv NULL , +and that only the protocol families that are the same as +.Fa sa +have their +.Fn pr_ctlinput +function called. +.Pp +.Fn net_add_domain +adds a new protocol domain to the system. +The argument +.Fa data +is cast directly to +.Vt struct domain * +within the function, but is declared +.Vt void * +in order to prevent compiler warnings when new domains are registered with +.Fn SYSINIT . +In most cases +.Fn net_add_domain +is not called directly, instead +.Fn DOMAIN_SET +is used. +.Pp +If the new domain has defined an initialization routine it is called by +.Fn net_add_domain ; +as well, each of the protocols within the domain that have defined an +initialization routine will have theirs called. +.Pp +Once a domain is added it cannot be unloaded. This is because there is +no reference counting system in place to determine if there are any +active references from sockets within that domain. +.Pp +.Fn pffindtype +and +.Fn pffindproto +lookup a protocol by its number or by its type. +In most cases if the protocol or type cannot be found +.Dv NULL +is returned, but +.Fn pffindproto +may return the default if the requested type is +.Dv SOCK_RAW , +a protocol switch type of +.Dv SOCK_RAW +is found, and the domain has a default raw protocol. +.Pp +Both functions are called by +.Fn socreate +in order to resolve the protocol for the socket currently being created. +.Pp +.Fn DOMAIN_SET +is a macro that simplifies the registration of a domain via SYSINIT. +The code resulting from the macro expects there to be a domain structure +named +.Vt namedomain +where name is the argument +.Fa name . +.Bd -literal + + struct domain localdomain = + { AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose, + localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] }; + + DOMAIN_SET(local); + +.Ed +.Sh RETURN VALUES +Both +.Fn pffindtype +and +.Fn pffindproto +return a +.Vt struct protosw * +for the protocol requested. +If the protocol or socket type is not found +.Dv NULL +is returned. +In the case of +.Fn pffindproto +the default protocol may be returned for +.Dv SOCK_RAW +types if the domain has a default raw protocol. +.Sh SEE ALSO +.Xr socket 2 +.Sh AUTHORS +This man page was written by +.An Chad David Aq davidc@acns.ab.ca . |