diff options
Diffstat (limited to 'static/freebsd/man4/ng_socket.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_socket.4 3.html | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_socket.4 3.html b/static/freebsd/man4/ng_socket.4 3.html new file mode 100644 index 00000000..c086bc6b --- /dev/null +++ b/static/freebsd/man4/ng_socket.4 3.html @@ -0,0 +1,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> |