This commit was generated by cvs2svn to compensate for changes in r29195,

which included commits to RCS files with non-trunk default branches.

1 files changed, 216 insertions, 0 deletions

diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4
new file mode 100644
index 0000000..2f813d8
--- /dev/null
+++ b/share/man/man4/tun.4
@@ -0,0 +1,216 @@
+.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
+.\" Based on PR#2411
+.\"
+.Dd March 10, 1996
+.Dt TUN 4
+.Os NetBSD 1.1
+.Sh NAME
+.Nm tun
+.Nd tunnel software network interface
+.Sh SYNOPSIS
+.Cd pseudo-device tun Op Ar count
+.Sh DESCRIPTION
+The
+.Nm tun
+interface is a software loopback mechanism that can be loosely
+described as the network interface analog of the
+.Xr pty 4 ,
+that is,
+.Nm tun
+does for network interfaces what the
+.Nm pty
+driver does for terminals.
+.Pp
+The
+.Nm tun
+driver, like the
+.Nm pty
+driver, provides two interfaces: an interface like the usual facility
+it is simulating
+.Po
+a network interface in the case of
+.Nm tun ,
+or a terminal for
+.Nm pty Pc ,
+and a character-special device
+.Dq control
+interface.
+.Pp
+The network interfaces are named
+.Sy tun Ns Ar 0 ,
+.Sy tun Ns Ar 1 ,
+etc, as many in all as the
+.Ar count
+figure given on the
+.Sy pseudo-device
+line.  Each one supports the usual network-interface
+.Xr ioctl 2 Ns s ,
+such as
+.Dv SIOCSIFADDR
+and
+.Dv SIOCSIFNETMASK ,
+and thus can be used with
+.Xr ifconfig 8
+like any other interface.  At boot time, they are
+.Dv POINTOPOINT
+interfaces, but this can be changed; see the description of the control
+device, below.  When the system chooses to transmit a packet on the
+network interface, the packet can be read from the control device
+.Po
+it appears as
+.Dq input
+there
+.Pc ;
+writing a packet to the control device generates an input
+packet on the network interface, as if the
+.Pq non-existent
+hardware had just received it.
+.Pp
+The tunnel device, normally
+.Pa /dev/tun Ns Sy N ,
+is exclusive-open
+.Po
+it cannot be opened if it is already open
+.Pc
+and is restricted to the super-user. A
+.Fn read
+call will return an error
+.Pq Er EHOSTDOWN
+if the interface is not
+.Dq ready
+.Po
+which means that the control device is open and the interface's
+address has been set
+.Pc .
+Once the interface is ready,
+.Fn read
+will return a packet if one is available; if not, it will either block
+until one is or return
+.Er EWOULDBLOCK ,
+depending on whether non-blocking I/O has been enabled.  If the packet
+is longer than is allowed for in the buffer passed to
+.Fn read ,
+the extra data will be silently dropped.
+.Pp
+Packets can be optionally prepended with the destination address as presented
+to the network interface output routine
+.Pq Sq Li tunoutput .
+The destination address is in
+.Sq Li struct sockaddr
+format. The actual length of the prepended address is in the member
+.Sq Li sa_len .
+The packet data follows immediately.
+A
+.Xr write 2
+call passes a packet in to be
+.Dq received
+on the pseudo-interface.  Each
+.Fn write
+call supplies exactly one packet; the packet length is taken from the
+amount of data provided to
+.Fn write .
+Writes will not block; if the packet cannot be accepted for a
+transient reason
+.Pq e.g., no buffer space available ,
+it is silently dropped; if the reason is not transient
+.Pq e.g., packet too large ,
+an error is returned.
+If
+.Dq link-layer mode
+is on
+.Pq see Dv TUNSLMODE No below ,
+the actual packet data must be preceded by a
+.Sq Li struct sockaddr .
+The driver currently only inspects the
+.Sq Li sa_family
+field.
+The following
+.Xr ioctl 2
+calls are supported
+.Pq defined in Aq Pa net/if_tun.h Ns :
+.Bl -tag -width TUNSIFMODE
+.It Dv TUNSDEBUG
+The argument should be a pointer to an
+.Va int ;
+this sets the internal debugging variable to that value.  What, if
+anything, this variable controls is not documented here; see the source
+code.
+.It Dv TUNGDEBUG
+The argument should be a pointer to an
+.Va int ;
+this stores the internal debugging variable's value into it.
+.It Dv TUNSIFMODE
+The argument should be a pointer to an
+.Va int ;
+its value must be
+.Dv IFF_POINTOPOINT
+or
+.Dv IFF_BROADCAST .
+The type of the corresponding
+.Em tun Ns Sy n
+interface is set to the supplied type.  If the value is anything else,
+an
+.Er EINVAL
+error occurs.  The interface must be down at the time; if it is up, an
+.Er EBUSY
+error occurs.
+.It Dv TUNSLMODE
+The argument should be a pointer to an
+.Va int ;
+a non-zero value turns on
+.Dq link-layer
+mode, causing packets read from the tunnel device to be prepended with
+network destination address.
+.It Dv FIONBIO
+Turn non-blocking I/O for reads off or on, according as the argument
+.Va int Ns 's
+value is or isn't zero
+.Pq Writes are always nonblocking .
+.It Dv FIOASYNC
+Turn asynchronous I/O for reads
+.Po
+i.e., generation of
+.Dv SIGIO
+when data is available to be read
+.Pc off or on, according as the argument
+.Va int Ns 's
+value is or isn't zero.
+.It Dv FIONREAD
+If any packets are queued to be read, store the size of the first one
+into the argument
+.Va int ;
+otherwise, store zero.
+.It Dv TIOCSPGRP
+Set the process group to receive
+.Dv SIGIO
+signals, when asynchronous I/O is enabled, to the argument
+.Va int
+value.
+.It Dv TIOCGPGRP
+Retrieve the process group value for
+.Dv SIGIO
+signals into the argument
+.Va int
+value.
+.El
+.Pp
+The control device also supports
+.Xr select 2
+for read; selecting for write is pointless, and always succeeds, since
+writes are always non-blocking.
+.Pp
+On the last close of the data device, by default, the interface is
+brought down
+.Po as if with
+.Dq ifconfig tun Ns Sy n No down
+.Pc .
+All queued packets are thrown away.
+.Po If the interface is up when the data device is not open
+output packets are always
+thrown away rather than letting them pile up
+.Pc .
+.Sh SEE ALSO
+.Xr intro 4 ,
+.Xr inet 4
+.Sh BUGS
+Currently is IP-only.