[src/trunk]: src Add and install a manual page for tap(4).

[cube <cube%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/ac2e059fb5cb
branches:  trunk
changeset: 572596:ac2e059fb5cb
user:      cube <cube%NetBSD.org@localhost>
date:      Sat Jan 08 22:29:38 2005 +0000

description:
Add and install a manual page for tap(4).

diffstat:

 distrib/sets/lists/man/mi |    4 +-
 share/man/man4/Makefile   |    4 +-
 share/man/man4/tap.4      |  172 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 177 insertions(+), 3 deletions(-)

diffs (219 lines):

diff -r 8b1411185340 -r ac2e059fb5cb distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Sat Jan 08 22:28:51 2005 +0000
+++ b/distrib/sets/lists/man/mi Sat Jan 08 22:29:38 2005 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.745 2005/01/05 10:10:54 martti Exp $
+# $NetBSD: mi,v 1.746 2005/01/08 22:29:38 cube Exp $
 ./etc/mtree/set.man                            man-sys-root
 ./usr/share/info/am-utils.info                 man-amd-info            info
 ./usr/share/info/as.info                       man-computil-info       bfd,info
@@ -1229,6 +1229,7 @@
 ./usr/share/man/cat4/sw.0                      man-sys-catman          .cat
 ./usr/share/man/cat4/sysbeep.0                 man-sys-catman          .cat
 ./usr/share/man/cat4/systrace.0                        man-sys-catman          .cat
+./usr/share/man/cat4/tap.0                     man-sys-catman          .cat
 ./usr/share/man/cat4/tb.0                      man-sys-catman          .cat
 ./usr/share/man/cat4/tc.0                      man-sys-catman          .cat
 ./usr/share/man/cat4/tcds.0                    man-sys-catman          .cat
@@ -3411,6 +3412,7 @@
 ./usr/share/man/man4/sw.4                      man-sys-man             .man
 ./usr/share/man/man4/sysbeep.4                 man-sys-man             .man
 ./usr/share/man/man4/systrace.4                        man-sys-man             .man
+./usr/share/man/man4/tap.4                     man-sys-man             .man
 ./usr/share/man/man4/tb.4                      man-sys-man             .man
 ./usr/share/man/man4/tc.4                      man-sys-man             .man
 ./usr/share/man/man4/tcds.4                    man-sys-man             .man
diff -r 8b1411185340 -r ac2e059fb5cb share/man/man4/Makefile
--- a/share/man/man4/Makefile   Sat Jan 08 22:28:51 2005 +0000
+++ b/share/man/man4/Makefile   Sat Jan 08 22:29:38 2005 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.342 2004/12/23 23:13:14 he Exp $
+#      $NetBSD: Makefile,v 1.343 2005/01/08 22:29:38 cube Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 acardide.4 aceride.4 acphy.4 adc.4 adv.4 \
@@ -35,7 +35,7 @@
        siop.4 sip.4 siside.4 sk.4 sl.4 slide.4 \
        sm.4 spc.4 speaker.4 spif.4 spp.4 sqphy.4 \
        ss.4 st.4 ste.4 stge.4 sti.4 stpcide.4 sv.4 strip.4 systrace.4 \
-       tb.4 tc.4 tcds.4 tcp.4 termios.4 tfb.4 ti.4 \
+       tap.4 tb.4 tc.4 tcds.4 tcp.4 termios.4 tfb.4 ti.4 \
        tl.4 tlp.4 tlphy.4 tp.4 tr.4 trm.4 tty.4 tun.4 \
        tqphy.4 twe.4 txp.4 ubsec.4 udp.4 uep.4 uha.4 uk.4 ukphy.4 \
        unix.4 userconf.4 verifiedexec.4 vga.4 viaide.4 \
diff -r 8b1411185340 -r ac2e059fb5cb share/man/man4/tap.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/tap.4      Sat Jan 08 22:29:38 2005 +0000
@@ -0,0 +1,172 @@
+.\" $NetBSD: tap.4,v 1.1 2005/01/08 22:29:38 cube Exp $
+.\"
+.\"  Copyright (c) 2004 The NetBSD Foundation.
+.\"  All rights reserved.
+.\"
+.\"  This code is derived from software contributed to the NetBSD Foundation
+.\"   by Quentin Garnier.
+.\" 
+.\"  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, this list of conditions and the following disclaimer.
+.\"  2. Redistributions in binary form must reproduce the above copyright
+.\"     notice, this list of conditions and the following disclaimer in the
+.\"     documentation and/or other materials provided with the distribution.
+.\"  3. All advertising materials mentioning features or use of this software
+.\"     must display the following acknowledgement:
+.\"         This product includes software developed by the NetBSD
+.\"         Foundation, Inc. and its contributors.
+.\"  4. Neither the name of The NetBSD Foundation nor the names of its
+.\"     contributors may be used to endorse or promote products derived
+.\"     from this software without specific prior written permission.
+.\" 
+.\"  THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\"  ``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 FOUNDATION OR CONTRIBUTORS
+.\"  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.
+.\"/
+.Dd December 21, 2004
+.Dt TAP 4
+.Os
+.Sh NAME
+.Nm tap
+.Nd virtual Ethernet device
+.Sh SYNOPSIS
+.Cd pseudo-device tap
+.Sh DESCRIPTION
+The
+.Nm
+driver allows the creation and use of virtual Ethernet devices.
+Those interfaces appear just as any real Ethernet NIC to the kernel,
+but can also be accessed by userland through a character device node in order
+to read frames being sent by the system or to inject frames.
+.Pp
+In that respect it is very similar to what
+.Xr tun 4
+provides, but the added Ethernet layer allows easy integration with machine
+emulators or virtual Ethernet networks through the use of
+.Xr bridge 4
+with tunneling.
+.Sh INTERFACE CREATION
+Interfaces may be created in two different ways:
+using the
+.Xr ifconfig 8
+.Cm create
+command with a specified device number,
+or its ioctl equivalent,
+.Dv SIOCIFCREATE ,
+or using the special cloning device
+.Pa /dev/tap .
+.Pp
+The former works the same as any other cloning network interface:
+the administrator can create and destroy interfaces at any time,
+notably at boot time.
+This is the easiest way of combining
+.Nm
+and
+.Xr bridge 4 .
+Later, userland will actually access the interfaces through the specific
+device nodes
+.Pa /dev/tapN .
+.Pp
+The latter is aimed at applications that need a virtual Ethernet device for
+the duration of their execution.
+A new interface is created at the opening of
+.Pa /dev/tap ,
+and is later destroyed when the last process using the file descriptor closes
+it.
+.Sh CHARACTER DEVICES
+Whether the
+.Nm
+devices are accessed through the special cloning device
+.Pa /dev/tap
+or through the specific devices
+.Pa /dev/tapN ,
+the possible actions to control the matching interface are the same.
+.Pp
+When using
+.Pa /dev/tap
+though, as the interface is created on-the-fly, its name is not known
+immediately by the application.
+Therefore the
+.Dv TAPGIFNAME
+ioctl is provided.
+It should be the first action an application using the special cloning device
+will do.
+It takes a pointer to a
+.Ft struct ifreq
+as an argument.
+.Pp
+Ethernet frames sent out by the kernel on a
+.Nm
+interface can be obtained by the controlling application with
+.Xr read 2 .
+It can also inject frames in the kernel with
+.Xr write 2 .
+There is absolutely no validation of the content of the injected frame,
+it can be any data, of any length.
+.Pp
+One call of
+.Xr write 2
+will inject a single frame in the kernel, as one call of
+.Xr read 2
+will retrieve a single frame from the queue, to the extent of the provided
+buffer.
+If the buffer is not large enough, the frame will be truncated.
+.Pp
+.Nm
+character devices support the
+.Dv FIONREAD
+ioctl which returns the size of the next available frame,
+or 0 if there is no available frame in the queue.
+.Pp
+They also support non-blocking I/O through the
+.Dv FIONBIO
+ioctl.
+In that mode,
+.Er EWOULDBLOCK
+is returned by
+.Xr read 2
+when no data is available.
+.Pp
+Asynchronous I/O is supported through the
+.Dv FIOASYNC ,
+.Dv FIOSETOWN
+and
+.Dv FIOGETOWN
+ioctls.
+The first will enable
+.Dv SIGIO
+generation, while the two other configure the process group that
+will receive the signal when data is ready.
+.Pp
+Synchronisation may also be achieved through the use of
+.Xr select 2 ,
+.Xr poll 2
+or
+.Xr kevent 2 .
+.Sh FILES
+.Bl -tag -compact -width /dev/tap[0-9]*
+.It Pa /dev/tap
+cloning device
+.It Pa /dev/tap[0-9]*
+individual character device nodes
+.El
+.Sh SEE ALSO
+.Xr bridge 4 ,
+.Xr ifconfig 8 ,
+.Xr tun 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 3.0 .