if_tun: Update tun.4 man page to match the code
authorAaron LI <aly@aaronly.me>
Tue, 17 Jul 2018 11:04:12 +0000 (19:04 +0800)
committerAaron LI <aly@aaronly.me>
Thu, 19 Jul 2018 07:09:47 +0000 (15:09 +0800)
Mainly follow FreeBSD's tun.4, refer to NetBSD's tun.4, and with my own
minor adjustments.

share/man/man4/tun.4

index 643f942..f74fedd 100644 (file)
@@ -1,9 +1,8 @@
 .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
 .\" $FreeBSD: src/share/man/man4/tun.4,v 1.9.2.4 2001/08/17 13:08:39 ru Exp $
-.\" $DragonFly: src/share/man/man4/tun.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
 .\" Based on PR#2411
 .\"
-.Dd August 6, 2009
+.Dd July 17, 2018
 .Dt TUN 4
 .Os
 .Sh NAME
@@ -36,16 +35,37 @@ or a terminal for
 and a character-special device
 .Dq control
 interface.
+A client program transfers IP (by default) packets to or from the
+.Nm
+.Dq control
+interface.
+The
+.Xr tap 4
+interface provides similar functionality at the Ethernet layer:
+a client will transfer Ethernet frames to or from a
+.Xr tap 4
+.Dq control
+interface.
 .Pp
 The network interfaces are named
 .Dq Li tun0 ,
 .Dq Li tun1 ,
-etc, and each one supports the usual network-interface
-.Xr ioctl 2 Ns s ,
-such as
-.Dv SIOCSIFADDR
-and
-.Dv SIOCSIFNETMASK ,
+etc., one for each control device that has been opened.
+.Pp
+The
+.Nm
+interface permits opens on the special control device
+.Pa /dev/tun .
+When this device is opened,
+.Nm
+will return a handle for the lowest unused
+.Nm
+device (use
+.Xr devname 3
+to determine which).
+.Pp
+Each interface supports the usual network-interface
+.Xr ioctl 2 Ns s
 and thus can be used with
 .Xr ifconfig 8
 like any other interface.
@@ -59,14 +79,13 @@ network interface, the packet can be read from the control device
 .Dq input
 there);
 writing a packet to the control device generates an input
-packet on the network interface, as if the (non\-existent)
+packet on the network interface, as if the (non-existent)
 hardware had just received it.
 .Pp
-The tunnel device, normally
-.Pa /dev/tun Ns Ar N ,
+The tunnel device
+.Pq Pa /dev/tun Ns Ar N
 is exclusive-open
-(it cannot be opened if it is already open)
-and is restricted to the super-user.
+(it cannot be opened if it is already open).
 A
 .Xr read 2
 call will return an error
@@ -86,15 +105,30 @@ If the packet is longer than is allowed for in the buffer passed to
 .Xr read 2 ,
 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,
+If the
+.Dv TUNSLMODE
+ioctl has been set (i.e.,
+.Dq link-layer
+mode), packets read from the control device will be prepended
+with the destination address as presented to the network interface output
+routine,
 .Fn tunoutput .
 The destination address is in
 .Vt struct sockaddr
 format.
 The actual length of the prepended address is in the member
 .Va sa_len .
-The packet data follows immediately.
+If the
+.Dv TUNSIFHEAD
+ioctl has been set (i.e.,
+.Dq multi-af
+mode), packets will be prepended with a 4-byte address
+family in network byte order.
+.Dv TUNSLMODE
+and
+.Dv TUNSIFHEAD
+are mutually exclusive.
+In any case, the packet data follows immediately.
 .Pp
 A
 .Xr write 2
@@ -105,24 +139,31 @@ Each
 .Xr write 2
 call supplies exactly one packet; the packet length is taken from the
 amount of data provided to
-.Xr write 2 .
+.Xr write 2
+(minus any supplied address family).
 Writes will not block; if the packet cannot be accepted for a
 transient reason
 (e.g., no buffer space available),
 it is silently dropped; if the reason is not transient
 (e.g., packet too large),
 an error is returned.
-If
-.Dq link-layer mode
-is on
-(see
+.Pp
+If the
 .Dv TUNSLMODE
-below),
-the actual packet data must be preceded by a
+ioctl has been set (i.e.,
+.Dq link-layer
+mode), the actual packet data must be preceded by a
 .Vt struct sockaddr .
 The driver currently only inspects the
 .Va sa_family
 field.
+If the
+.Dv TUNSIFHEAD
+ioctl has been set (i.e.,
+.Dq multi-af
+mode), the address family must be prepended, otherwise the
+packet is assumed to be of type
+.Dv AF_INET .
 .Pp
 The following
 .Xr ioctl 2
@@ -159,25 +200,30 @@ The argument should be a pointer to an
 its value must be either
 .Dv IFF_POINTOPOINT
 or
-.Dv IFF_BROADCAST .
+.Dv IFF_BROADCAST
+and should have
+.Dv IFF_MULTICAST
+OR'd into the value if multicast support is required.
 The type of the corresponding
 .Dq Li tun Ns Ar N
 interface is set to the supplied type.
 If the value is anything else, an
 .Er EINVAL
-error occurs.
+error is returned.
 The interface must be down at the time; if it is up, an
 .Er EBUSY
-error occurs.
+error is returned.
 .It Dv TUNSLMODE
 The argument should be a pointer to an
 .Vt int ;
-a non-zero value turns on
+a non-zero value turns off
+.Dq multi-af
+mode and turns on
 .Dq link-layer
 mode, causing packets read from the tunnel device to be prepended with
-network destination address.
+the network destination address (see above).
 .It Dv TUNSIFPID
-Will set the pid owning the tunnel device to the current process's pid.
+Will set the PID owning the tunnel device to the current process's PID.
 .It Dv TUNSIFHEAD
 The argument should be a pointer to an
 .Vt int ;
@@ -185,18 +231,13 @@ a non-zero value turns off
 .Dq link-layer
 mode, and enables
 .Dq multi-af
-mode, where every packet is preceded with a four byte address family.
+mode, where every packet is preceded with a 4-byte address family.
 .It Dv TUNGIFHEAD
 The argument should be a pointer to an
 .Vt int ;
-this stores one if the device is in
+the ioctl sets the value to one if the device is in
 .Dq multi-af
-mode, and zero otherwise in it.
-.It Dv FIONBIO
-Turn non-blocking I/O for reads off or on, according as the argument
-.Vt int Ns 's
-value is or isn't zero.
-(Writes are always non-blocking.)
+mode, and zero otherwise.
 .It Dv FIOASYNC
 Turn asynchronous I/O for reads
 (i.e., generation of
@@ -204,7 +245,7 @@ Turn asynchronous I/O for reads
 when data is available to be read)
 off or on, according as the argument
 .Vt int Ns 's
-value is or isn't zero.
+value is or is not zero.
 .It Dv FIONREAD
 If any packets are queued to be read, store the size of the first one
 into the argument
@@ -238,8 +279,11 @@ If the interface is up when the data device is not open
 output packets are always thrown away rather than letting
 them pile up.
 .Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr devname 3 ,
 .Xr inet 4 ,
-.Xr intro 4
+.Xr tap 4 ,
+.Xr ifconfig 8
 .Sh AUTHORS
 This manual page was originally obtained from
 .Nx .