xref: /freebsd/share/man/man4/ng_ksocket.4 (revision 000d56193c05f97e88fa54b5b8482ff18bebf42a)
1f7045ac0SArchie Cobbs.\" Copyright (c) 1999 Whistle Communications, Inc.
2f7045ac0SArchie Cobbs.\" All rights reserved.
3f7045ac0SArchie Cobbs.\"
4f7045ac0SArchie Cobbs.\" Subject to the following obligations and disclaimer of warranty, use and
5f7045ac0SArchie Cobbs.\" redistribution of this software, in source or object code forms, with or
6f7045ac0SArchie Cobbs.\" without modifications are expressly permitted by Whistle Communications;
7f7045ac0SArchie Cobbs.\" provided, however, that:
8f7045ac0SArchie Cobbs.\" 1. Any and all reproductions of the source or object code must include the
9f7045ac0SArchie Cobbs.\"    copyright notice above and the following disclaimer of warranties; and
10f7045ac0SArchie Cobbs.\" 2. No rights are granted, in any manner or form, to use Whistle
11f7045ac0SArchie Cobbs.\"    Communications, Inc. trademarks, including the mark "WHISTLE
12f7045ac0SArchie Cobbs.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
13f7045ac0SArchie Cobbs.\"    such appears in the above copyright notice or in the software.
14f7045ac0SArchie Cobbs.\"
15f7045ac0SArchie Cobbs.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
16f7045ac0SArchie Cobbs.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
17f7045ac0SArchie Cobbs.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
18f7045ac0SArchie Cobbs.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
19f7045ac0SArchie Cobbs.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
20f7045ac0SArchie Cobbs.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
21f7045ac0SArchie Cobbs.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
22f7045ac0SArchie Cobbs.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
23f7045ac0SArchie Cobbs.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
24f7045ac0SArchie Cobbs.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
25f7045ac0SArchie Cobbs.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
26f7045ac0SArchie Cobbs.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
27f7045ac0SArchie Cobbs.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
28f7045ac0SArchie Cobbs.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29f7045ac0SArchie Cobbs.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30f7045ac0SArchie Cobbs.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
31f7045ac0SArchie Cobbs.\" OF SUCH DAMAGE.
32f7045ac0SArchie Cobbs.\"
33eddc45e7SJeroen Ruigrok van der Werven.\" Author: Archie Cobbs <archie@FreeBSD.org>
34f7045ac0SArchie Cobbs.\"
35f7045ac0SArchie Cobbs.\" $FreeBSD$
36f7045ac0SArchie Cobbs.\"
37f7045ac0SArchie Cobbs.Dd November 15, 1999
38bec35b9aSArchie Cobbs.Dt NG_KSOCKET 4
39f7045ac0SArchie Cobbs.Os FreeBSD
40f7045ac0SArchie Cobbs.Sh NAME
41f7045ac0SArchie Cobbs.Nm ng_ksocket
42f7045ac0SArchie Cobbs.Nd kernel socket netgraph node type
43f7045ac0SArchie Cobbs.Sh SYNOPSIS
44f7045ac0SArchie Cobbs.Fd #include <netgraph/ng_ksocket.h>
45f7045ac0SArchie Cobbs.Sh DESCRIPTION
46f7045ac0SArchie CobbsA
47f7045ac0SArchie Cobbs.Nm ksocket
48f7045ac0SArchie Cobbsnode is both a netgraph node and a BSD socket.  The
4951291597SJulian Elischer.Nm
50f7045ac0SArchie Cobbsnode type allows one to open a socket inside the kernel and have
51f7045ac0SArchie Cobbsit appear as a Netgraph node.  The
5251291597SJulian Elischer.Nm
53f7045ac0SArchie Cobbsnode type is the reverse of the socket node type (see
54bec35b9aSArchie Cobbs.Xr ng_socket 4 ) :
55f7045ac0SArchie Cobbswhereas the socket node type enables the user-level manipulation (via
568e078873SArchie Cobbsa socket) of what is normally a kernel-level entity (the associated
578e078873SArchie CobbsNetgraph node), the
5851291597SJulian Elischer.Nm
59f7045ac0SArchie Cobbsnode type enables the kernel-level manipulation (via a Netgraph node) of
608e078873SArchie Cobbswhat is normally a user-level entity (the associated socket).
61f7045ac0SArchie Cobbs.Pp
62f7045ac0SArchie CobbsA
6351291597SJulian Elischer.Nm
64f7045ac0SArchie Cobbsnode allows at most one hook connection.  Connecting to the node is
65f7045ac0SArchie Cobbsequivalent to opening the associated socket.  The name given to the hook
668e078873SArchie Cobbsdetermines what kind of socket the node will open (see below).
67f7045ac0SArchie CobbsWhen the hook is disconnected and/or the node is shutdown, the
68f7045ac0SArchie Cobbsassociated socket is closed.
69f7045ac0SArchie Cobbs.Sh HOOKS
70f7045ac0SArchie CobbsThis node type supports a single hook connection at a time.
71f7045ac0SArchie CobbsThe name of the hook must be of the form
72c2d03ea8SRuslan Ermilov.Em <family>/<type>/<proto> ,
73f7045ac0SArchie Cobbswhere the
74c2d03ea8SRuslan Ermilov.Em family ,
75c2d03ea8SRuslan Ermilov.Em type ,
76f7045ac0SArchie Cobbsand
77c2d03ea8SRuslan Ermilov.Em proto
78f7045ac0SArchie Cobbsare the decimal equivalent of the same arguments to
79f7045ac0SArchie Cobbs.Xr socket 2 .
80f7045ac0SArchie CobbsAlternately, aliases for the commonly used values are accepted as
81f7045ac0SArchie Cobbswell.  For example
82f7045ac0SArchie Cobbs.Dv inet/dgram/udp
83f7045ac0SArchie Cobbsis a more readable but equivalent version of
84f7045ac0SArchie Cobbs.Dv 2/2/17 .
85f7045ac0SArchie Cobbs.Sh CONTROL MESSAGES
86f7045ac0SArchie CobbsThis node type supports the generic control messages, plus the following:
87f7045ac0SArchie Cobbs.Bl -tag -width foo
88f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_BIND
89f7045ac0SArchie CobbsThis functions exactly like the
90f7045ac0SArchie Cobbs.Xr bind 2
91f7045ac0SArchie Cobbssystem call.  The
92f7045ac0SArchie Cobbs.Dv "struct sockaddr"
93f7045ac0SArchie Cobbssocket address parameter should be supplied as an argument.
94f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_LISTEN
95f7045ac0SArchie CobbsThis functions exactly like the
96f7045ac0SArchie Cobbs.Xr listen 2
978e078873SArchie Cobbssystem call.  The backlog paramter (a single 32 bit
98f7045ac0SArchie Cobbs.Dv int )
99f7045ac0SArchie Cobbsshould be supplied as an argument.
100f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_CONNECT
101f7045ac0SArchie CobbsThis functions exactly like the
102f7045ac0SArchie Cobbs.Xr connect 2
103f7045ac0SArchie Cobbssystem call.  The
104f7045ac0SArchie Cobbs.Dv "struct sockaddr"
1058e078873SArchie Cobbsdestination address parameter should be supplied as an argument.
106f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_ACCEPT
107f7045ac0SArchie CobbsCurrently unimplemented.
108f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_GETNAME
1098e078873SArchie CobbsEquivalent to the
110000d5619SMaxim Sobolev.Xr getsockname 2
1118e078873SArchie Cobbssystem call.  The name is returned as a
1128e078873SArchie Cobbs.Dv "struct sockaddr"
1138e078873SArchie Cobbsin the arguments field of the reply.
114f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_GETPEERNAME
1158e078873SArchie CobbsEquivalent to the
1168e078873SArchie Cobbs.Xr getpeername 2
1178e078873SArchie Cobbssystem call.  The name is returned as a
1188e078873SArchie Cobbs.Dv "struct sockaddr"
1198e078873SArchie Cobbsin the arguments field of the reply.
120f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_SETOPT
1218e078873SArchie CobbsEquivalent to the
1228e078873SArchie Cobbs.Xr setsockopt 2
1238e078873SArchie Cobbssystem call, except that the option name, level, and value are passed in a
1248e078873SArchie Cobbs.Dv "struct ng_ksocket_sockopt" .
125f7045ac0SArchie Cobbs.It Dv NGM_KSOCKET_GETOPT
1268e078873SArchie CobbsEquivalent to the
1278e078873SArchie Cobbs.Xr getsockopt 2
1288e078873SArchie Cobbssystem call, except that the option is passed in a
1298e078873SArchie Cobbs.Dv "struct ng_ksocket_sockopt" .
1308e078873SArchie CobbsWhen sending this command, the
1318e078873SArchie Cobbs.Dv value
1328e078873SArchie Cobbsfield should be empty; upon return, it will contain the
1338e078873SArchie Cobbsretrieved value.
134f7045ac0SArchie Cobbs.El
135f7045ac0SArchie Cobbs.Pp
1368e078873SArchie Cobbs.Sh ASCII FORM CONTROL MESSAGES
1378e078873SArchie CobbsFor control messages that pass a
1388e078873SArchie Cobbs.Dv "struct sockaddr"
13951291597SJulian Elischerin the argument field, the normal
14051291597SJulian Elischer.Tn ASCII
14151291597SJulian Elischerequivalent of the C structure
1428e078873SArchie Cobbsis an acceptable form.  For the
1438e078873SArchie Cobbs.Dv PF_INET
1448e078873SArchie Cobbsand
1458e078873SArchie Cobbs.Dv PF_LOCAL
1468e078873SArchie Cobbsaddress families, a more convenient form is also used, which is
1478e078873SArchie Cobbsthe protocol family name, followed by a slash, followed by the actual
1488e078873SArchie Cobbsaddress.  For
1498e078873SArchie Cobbs.Dv PF_INET ,
1508e078873SArchie Cobbsthe address is an IP address followed by an optional colon and port number.
1518e078873SArchie CobbsFor
1528e078873SArchie Cobbs.Dv PF_LOCAL ,
1538e078873SArchie Cobbsthe address is the pathname as a doubly quoted string.
1548e078873SArchie Cobbs.Pp
1558e078873SArchie CobbsExamples:
1568e078873SArchie Cobbs.Bl -tag -width XXXXXXXXXX
1578e078873SArchie Cobbs.It Dv PF_LOCAL
1588e078873SArchie Cobbslocal/"/tmp/foo.socket"
159ef02c1e5SArchie Cobbs.It Dv PF_INET
160ef02c1e5SArchie Cobbsinet/192.168.1.1:1234
1618e078873SArchie Cobbs.It Other
162ef02c1e5SArchie Cobbs.Dv "\&{ family=16 len=16 data=[0x70 0x00 0x01 0x23] \&}"
1638e078873SArchie Cobbs.El
1648e078873SArchie Cobbs.Pp
1658e078873SArchie CobbsFor control messages that pass a
1668e078873SArchie Cobbs.Dv "struct ng_ksocket_sockopt" ,
16751291597SJulian Elischerthe normal
16851291597SJulian Elischer.Tn ASCII
16951291597SJulian Elischerform for that structure is used.  In the future, more
1708e078873SArchie Cobbsconvenient encoding of the more common socket options may be supported.
171f7045ac0SArchie Cobbs.Sh SHUTDOWN
172f7045ac0SArchie CobbsThis node shuts down upon receipt of a
173f7045ac0SArchie Cobbs.Dv NGM_SHUTDOWN
174f7045ac0SArchie Cobbscontrol message, or when the hook is disconnected.
175f7045ac0SArchie CobbsShutdown of the node closes the associated socket.
176f7045ac0SArchie Cobbs.Sh SEE ALSO
177f7045ac0SArchie Cobbs.Xr socket 2 ,
178f7045ac0SArchie Cobbs.Xr netgraph 4 ,
179bec35b9aSArchie Cobbs.Xr ng_socket 4 ,
180bec35b9aSArchie Cobbs.Xr ngctl 8
18151291597SJulian Elischer.Sh HISTORY
18251291597SJulian ElischerThe
18351291597SJulian Elischer.Nm
18451291597SJulian Elischernode type was implemented in
18551291597SJulian Elischer.Fx 4.0 .
18651291597SJulian Elischer.Sh AUTHORS
187eddc45e7SJeroen Ruigrok van der Werven.An Archie Cobbs Aq archie@FreeBSD.org
188