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
|
<table class="head">
<tr>
<td class="head-ltitle">NG_SOCKET(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">NG_SOCKET(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_socket</code> —
<span class="Nd">netgraph socket 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_socket.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">socket</code> node is both a
<span class="Ux">BSD</span> socket and a netgraph node. The
<code class="Nm">ng_socket</code> node type allows user-mode processes to
participate in the kernel <a class="Xr">netgraph(4)</a> networking subsystem
using the <span class="Ux">BSD</span> socket interface. The process must
have root privileges to be able to create netgraph sockets however once
created, any process that has one may use it.</p>
<p class="Pp">A new <code class="Nm">ng_socket</code> node is created by
creating a new socket of type <code class="Dv">NG_CONTROL</code> in the
protocol family <code class="Dv">PF_NETGRAPH</code>, using the
<a class="Xr">socket(2)</a> system call. Any control messages received by
the node and not having a cookie value of
<code class="Dv">NGM_SOCKET_COOKIE</code> are received by the process, using
<a class="Xr">recvfrom(2)</a>; the socket address argument is a
<code class="Dv">struct sockaddr_ng</code> containing the sender's netgraph
address. Conversely, control messages can be sent to any node by calling
<a class="Xr">sendto(2)</a>, supplying the recipient's address in a
<code class="Dv">struct sockaddr_ng</code>. The <a class="Xr">bind(2)</a>
system call may be used to assign a global netgraph name to the node.</p>
<p class="Pp" id="hook">To transmit and receive netgraph data packets, a
<code class="Dv">NG_DATA</code> socket must also be created using
<a class="Xr">socket(2)</a> and associated with a
<code class="Nm">ng_socket</code> node. <code class="Dv">NG_DATA</code>
sockets do not automatically have nodes associated with them; they are bound
to a specific node via the <a class="Xr">connect(2)</a> system call. The
address argument is the netgraph address of the
<code class="Nm">ng_socket</code> node already created. Once a data socket
is associated with a node, any data packets received by the node are read
using <a class="Xr">recvfrom(2)</a> and any packets to be sent out from the
node are written using <a class="Xr">sendto(2)</a>. In the case of data
sockets, the <code class="Dv">struct sockaddr_ng</code> contains the name of
the <a class="permalink" href="#hook"><i class="Em">hook</i></a> on which
the data was received or should be sent.</p>
<p class="Pp">As a special case, to allow netgraph data sockets to be used as
stdin or stdout on naive programs, a <a class="Xr">sendto(2)</a> with a NULL
sockaddr pointer, a <a class="Xr">send(2)</a> or a
<a class="Xr">write(2)</a> will succeed in the case where there is exactly
ONE hook attached to the socket node, (and thus the path is
unambiguous).</p>
<p class="Pp">There is a user library that simplifies using netgraph sockets;
see <a class="Xr">netgraph(3)</a>.</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 hooks with arbitrary names (as long as
they are unique) and always accepts hook connection requests.</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_SOCK_CMD_NOLINGER"><a class="permalink" href="#NGM_SOCK_CMD_NOLINGER"><code class="Dv">NGM_SOCK_CMD_NOLINGER</code></a></dt>
<dd>When the last hook is removed from this node, it will shut down as if it
had received a <code class="Dv">NGM_SHUTDOWN</code> message. Attempts to
access the sockets associated will return
<code class="Er">ENOTCONN</code>.</dd>
<dt id="NGM_SOCK_CMD_LINGER"><a class="permalink" href="#NGM_SOCK_CMD_LINGER"><code class="Dv">NGM_SOCK_CMD_LINGER</code></a></dt>
<dd>This is the default mode. When the last hook is removed, the node will
continue to exist, ready to accept new hooks until it is explicitly shut
down.</dd>
</dl>
<p class="Pp">All other messages with neither the
<code class="Dv">NGM_SOCKET_COOKIE</code> or
<code class="Dv">NGM_GENERIC_COOKIE</code> will be passed unaltered up the
<code class="Dv">NG_CONTROL</code> socket.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1>
<p class="Pp">This node type shuts down and disappears when both the associated
<code class="Dv">NG_CONTROL</code> and <code class="Dv">NG_DATA</code>
sockets have been closed, or a <code class="Dv">NGM_SHUTDOWN</code> control
message is received. In the latter case, attempts to write to the still-open
sockets will return <code class="Er">ENOTCONN</code>. If the
<code class="Dv">NGM_SOCK_CMD_NOLINGER</code> message has been received,
closure of the last hook will also initiate a shutdown of the node.</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(3)</a>,
<a class="Xr">netgraph(4)</a>, <a class="Xr">ng_ksocket(4)</a>,
<a class="Xr">ngctl(8)</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_socket</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">Julian Elischer</span>
<<a class="Mt" href="mailto:julian@FreeBSD.org">julian@FreeBSD.org</a>></p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">It is not possible to reject the connection of a hook, though any
data received on that hook can certainly be ignored.</p>
<p class="Pp">The controlling process is not notified of all events that an
in-kernel node would be notified of, e.g. a new hook, or hook removal. Some
node-initiated messages should be defined for this purpose (to be sent up
the control socket).</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 19, 1999</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
