Add a man page describing the fuctions directly related to network domains.
Reviewed by: alfred
This commit is contained in:
parent
14752b2a05
commit
f4af1f0785
@ -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
|
||||
|
225
share/man/man9/domain.9
Normal file
225
share/man/man9/domain.9
Normal file
@ -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 .
|
Loading…
x
Reference in New Issue
Block a user