1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<table class="head">
<tr>
<td class="head-ltitle">NG_KSOCKET(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">NG_KSOCKET(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ng_ksocket</code> —
<span class="Nd">kernel socket netgraph node type</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/types.h</a>></code>
<br/>
<code class="In">#include
<<a class="In">netgraph/ng_ksocket.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">A <code class="Nm">ksocket</code> node is both a netgraph node and
a <span class="Ux">BSD</span> socket. The <code class="Nm">ng_ksocket</code>
node type allows one to open a socket inside the kernel and have it appear
as a Netgraph node. The <code class="Nm">ng_ksocket</code> node type is the
reverse of the socket node type (see <a class="Xr">ng_socket(4)</a>):
whereas the socket node type enables the user-level manipulation (via a
socket) of what is normally a kernel-level entity (the associated Netgraph
node), the <code class="Nm">ng_ksocket</code> node type enables the
kernel-level manipulation (via a Netgraph node) of what is normally a
user-level entity (the associated socket).</p>
<p class="Pp">A <code class="Nm">ng_ksocket</code> node allows at most one hook
connection. Connecting to the node is equivalent to opening the associated
socket. The name given to the hook determines what kind of socket the node
will open (see below). When the hook is disconnected and/or the node is
shutdown, the associated socket is closed.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1>
<p class="Pp">This node type supports a single hook connection at a time. The
name of the hook must be of the form
<a class="permalink" href="#_family_/_type_/_proto_"><i class="Em" id="_family_/_type_/_proto_"><family>/<type>/<proto></i></a>,
where the
<a class="permalink" href="#family"><i class="Em" id="family">family</i></a>,
<a class="permalink" href="#type"><i class="Em" id="type">type</i></a>, and
<a class="permalink" href="#proto"><i class="Em" id="proto">proto</i></a>
are the decimal equivalent of the same arguments to
<a class="Xr">socket(2)</a>. Alternately, aliases for the commonly used
values are accepted as well. For example
<code class="Dv">inet/dgram/udp</code> is a more readable but equivalent
version of <code class="Dv">2/2/17</code>.</p>
<p class="Pp">Data received into socket is sent out via hook. Data received on
hook is sent out from socket, if the latter is connected (an
<code class="Dv">NGM_KSOCKET_CONNECT</code> was sent to node before). If
socket is not connected, destination <var class="Vt">struct sockaddr</var>
must be supplied in an mbuf tag with cookie
<code class="Dv">NGM_KSOCKET_COOKIE</code> and type
<code class="Dv">NG_KSOCKET_TAG_SOCKADDR</code> attached to data. Otherwise
<code class="Nm">ng_ksocket</code> will return
<code class="Er">ENOTCONN</code> to sender.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL
MESSAGES</a></h1>
<p class="Pp">This node type supports the generic control messages, plus the
following:</p>
<dl class="Bl-tag">
<dt id="NGM_KSOCKET_BIND"><a class="permalink" href="#NGM_KSOCKET_BIND"><code class="Dv">NGM_KSOCKET_BIND</code></a>
(<code class="Ic">bind</code>)</dt>
<dd>This functions exactly like the <a class="Xr">bind(2)</a> system call. The
<var class="Vt">struct sockaddr</var> socket address parameter should be
supplied as an argument.</dd>
<dt id="NGM_KSOCKET_LISTEN"><a class="permalink" href="#NGM_KSOCKET_LISTEN"><code class="Dv">NGM_KSOCKET_LISTEN</code></a>
(<code class="Ic">listen</code>)</dt>
<dd>This functions exactly like the <a class="Xr">listen(2)</a> system call.
The backlog parameter (a single 32 bit <code class="Dv">int</code>) should
be supplied as an argument.</dd>
<dt id="NGM_KSOCKET_CONNECT"><a class="permalink" href="#NGM_KSOCKET_CONNECT"><code class="Dv">NGM_KSOCKET_CONNECT</code></a>
(<code class="Ic">connect</code>)</dt>
<dd>This functions exactly like the <a class="Xr">connect(2)</a> system call.
The <var class="Vt">struct sockaddr</var> destination address parameter
should be supplied as an argument.</dd>
<dt id="NGM_KSOCKET_ACCEPT"><a class="permalink" href="#NGM_KSOCKET_ACCEPT"><code class="Dv">NGM_KSOCKET_ACCEPT</code></a>
(<code class="Ic">accept</code>)</dt>
<dd>Equivalent to the <a class="Xr">accept(2)</a> system call on a
non-blocking socket. If there is a pending connection on the queue, a new
socket and a corresponding cloned node are created. Returned are the
cloned node's ID and a peer name (as <var class="Vt">struct
sockaddr</var>). If there are no pending connections, this control message
returns nothing, and a connected node will receive the above message
asynchronously, when a connection is established.
<p class="Pp">A cloned node supports a single hook with an arbitrary name.
If not connected, a node disappears when its parent node is destroyed.
Once connected, it becomes an independent node.</p>
</dd>
<dt id="NGM_KSOCKET_GETNAME"><a class="permalink" href="#NGM_KSOCKET_GETNAME"><code class="Dv">NGM_KSOCKET_GETNAME</code></a>
(<code class="Ic">getname</code>)</dt>
<dd>Equivalent to the <a class="Xr">getsockname(2)</a> system call. The name
is returned as a <var class="Vt">struct sockaddr</var> in the arguments
field of the reply.</dd>
<dt id="NGM_KSOCKET_GETPEERNAME"><a class="permalink" href="#NGM_KSOCKET_GETPEERNAME"><code class="Dv">NGM_KSOCKET_GETPEERNAME</code></a>
(<code class="Ic">getpeername</code>)</dt>
<dd>Equivalent to the <a class="Xr">getpeername(2)</a> system call. The name
is returned as a <var class="Vt">struct sockaddr</var> in the arguments
field of the reply.</dd>
<dt id="NGM_KSOCKET_SETOPT"><a class="permalink" href="#NGM_KSOCKET_SETOPT"><code class="Dv">NGM_KSOCKET_SETOPT</code></a>
(<code class="Ic">setopt</code>)</dt>
<dd>Equivalent to the <a class="Xr">setsockopt(2)</a> system call, except that
the option name, level, and value are passed in a <var class="Vt">struct
ng_ksocket_sockopt</var>.</dd>
<dt id="NGM_KSOCKET_GETOPT"><a class="permalink" href="#NGM_KSOCKET_GETOPT"><code class="Dv">NGM_KSOCKET_GETOPT</code></a>
(<code class="Ic">getopt</code>)</dt>
<dd>Equivalent to the <a class="Xr">getsockopt(2)</a> system call, except that
the option is passed in a <var class="Vt">struct ng_ksocket_sockopt</var>.
When sending this command, the <code class="Dv">value</code> field should
be empty; upon return, it will contain the retrieved value.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="ASCII_FORM_CONTROL_MESSAGES"><a class="permalink" href="#ASCII_FORM_CONTROL_MESSAGES">ASCII
FORM CONTROL MESSAGES</a></h1>
<p class="Pp">For control messages that pass a <var class="Vt">struct
sockaddr</var> in the argument field, the normal ASCII equivalent of the C
structure is an acceptable form. For the <code class="Dv">PF_INET</code>,
<code class="Dv">PF_INET6</code> and <code class="Dv">PF_LOCAL</code>
address families, a more convenient form is also used, which is the protocol
family name, followed by a slash, followed by the actual address. For
<code class="Dv">PF_INET</code>, the address is an IPv4 address followed by
an optional colon and port number. For <code class="Dv">PF_INET6</code>, the
address is an IPv6 address enclosed in square brackets followed by an
optional colon and port number. For <code class="Dv">PF_LOCAL</code>, the
address is the pathname as a doubly quoted string.</p>
<p class="Pp">Examples:</p>
<dl class="Bl-tag">
<dt id="PF_LOCAL"><a class="permalink" href="#PF_LOCAL"><code class="Dv">PF_LOCAL</code></a></dt>
<dd>local/"/tmp/foo.socket"</dd>
<dt id="PF_INET"><a class="permalink" href="#PF_INET"><code class="Dv">PF_INET</code></a></dt>
<dd>inet/192.168.1.1:1234</dd>
<dt id="PF_INET6"><a class="permalink" href="#PF_INET6"><code class="Dv">PF_INET6</code></a></dt>
<dd>inet6/[2001::1]:1234</dd>
<dt id="_">Other</dt>
<dd><a class="permalink" href="#_"><code class="Dv">{ family=16 len=16
data=[0x70 0x00 0x01 0x23] }</code></a></dd>
</dl>
<p class="Pp">For control messages that pass a <var class="Vt">struct
ng_ksocket_sockopt</var>, the normal ASCII form for that structure is used.
In the future, more convenient encoding of the more common socket options
may be supported.</p>
<p class="Pp">Setting socket options example:</p>
<dl class="Bl-tag">
<dt id="setopt">Set FIB 2 for a socket (SOL_SOCKET, SO_SETFIB):</dt>
<dd><a class="permalink" href="#setopt"><code class="Dv">setopt { level=0xffff
name=0x1014 data=[ 2 ] }</code></a></dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1>
<p class="Pp">This node shuts down upon receipt of a
<code class="Dv">NGM_SHUTDOWN</code> control message, or when the hook is
disconnected. Shutdown of the node closes the associated socket.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">socket(2)</a>, <a class="Xr">netgraph(4)</a>,
<a class="Xr">ng_socket(4)</a>, <a class="Xr">ngctl(8)</a>,
<a class="Xr">mbuf_tags(9)</a>, <a class="Xr">socket(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">ng_ksocket</code> node type was implemented
in <span class="Ux">FreeBSD 4.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Archie Cobbs</span>
<<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 9, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
