1.\" $FreeBSD$ 2.\" Based on PR#2411 3.\" 4.Dd July 9, 2000 5.Os 6.Dt TAP 4 7.Sh NAME 8.Nm tap 9.Nd Ethernet tunnel software network interface 10.Sh SYNOPSIS 11.Cd device tap 12.Sh DESCRIPTION 13The 14.Nm 15interface is a software loopback mechanism that can be loosely 16described as the network interface analog of the 17.Xr pty 4 , 18that is, 19.Nm 20does for network interfaces what the 21.Nm pty 22driver does for terminals. 23.Pp 24The 25.Nm 26driver, like the 27.Nm pty 28driver, provides two interfaces: an interface like the usual facility 29it is simulating 30(an Ethernet network interface in the case of 31.Nm , 32or a terminal for 33.Nm pty ) , 34and a character-special device 35.Dq control 36interface. 37.Pp 38The network interfaces are named 39.Sy tap Ns Ar 0 , 40.Sy tap Ns Ar 1 , 41etc, as many as were made by 42.Xr MAKEDEV 8 . 43Each one supports the usual Ethernet network-interface 44.Xr ioctl 2 Ns s , 45such as 46.Dv SIOCSIFADDR 47and 48.Dv SIOCSIFNETMASK , 49and thus can be used with 50.Xr ifconfig 8 51like any other Ethernet interface. When the system chooses to transmit 52an Ethernet frame on the network interface, the frame can be read from 53the control device 54(it appears as 55.Dq input 56there); 57writing an Ethernet frame to the control device generates an input frame on 58the network interface, as if the 59.Pq non-existent 60hardware had just received it. 61.Pp 62The Ethernet tunnel device, normally 63.Pa /dev/tap Ns Sy N , 64is exclusive-open 65(it cannot be opened if it is already open) 66and is restricted to the super-user. 67A 68.Fn read 69call will return an error 70.Pq Er EHOSTDOWN 71if the interface is not 72.Dq ready . 73Once the interface is ready, 74.Fn read 75will return an Ethernet frame if one is available; if not, it will 76either block until one is or return 77.Er EWOULDBLOCK , 78depending on whether non-blocking I/O has been enabled. If the frame 79is longer than is allowed for in the buffer passed to 80.Fn read , 81the extra data will be silently dropped. 82.Pp 83A 84.Xr write 2 85call passes an Ethernet frame in to be 86.Dq received 87on the pseudo-interface. Each 88.Fn write 89call supplies exactly one frame; the frame length is taken from the 90amount of data provided to 91.Fn write . 92Writes will not block; if the frame cannot be accepted 93for a transient reason 94.Pq e.g., no buffer space available , 95it is silently dropped; if the reason is not transient 96.Pq e.g., frame too large , 97an error is returned. 98The following 99.Xr ioctl 2 100calls are supported 101.Pq defined in Aq Pa net/if_tap.h Ns : 102.Bl -tag -width VMIO_SIOCSETMACADDR 103.It Dv TAPSDEBUG 104The argument should be a pointer to an 105.Va int ; 106this sets the internal debugging variable to that value. What, if 107anything, this variable controls is not documented here; see the source 108code. 109.It Dv TAPGDEBUG 110The argument should be a pointer to an 111.Va int ; 112this stores the internal debugging variable's value into it. 113.It Dv FIONBIO 114Turn non-blocking I/O for reads off or on, according as the argument 115.Va int Ns 's 116value is or isn't zero 117.Pq Writes are always nonblocking . 118.It Dv FIOASYNC 119Turn asynchronous I/O for reads 120(i.e., generation of 121.Dv SIGIO 122when data is available to be read) 123off or on, according as the argument 124.Va int Ns 's 125value is or isn't zero. 126.It Dv FIONREAD 127If any frames are queued to be read, store the size of the first one into the argument 128.Va int ; 129otherwise, store zero. 130.It Dv TIOCSPGRP 131Set the process group to receive 132.Dv SIGIO 133signals, when asynchronous I/O is enabled, to the argument 134.Va int 135value. 136.It Dv TIOCGPGRP 137Retrieve the process group value for 138.Dv SIGIO 139signals into the argument 140.Va int 141value. 142.It Dv SIOCGIFADDR 143Retrieve the Media Access Control 144.Pq Dv MAC 145address of the 146.Dq remote 147side. This command is used by the VMware port and expected to be executed on 148descriptor, associated with control device 149(usually 150.Pa /dev/vmnet Ns Sy N 151or 152.Pa /dev/tap Ns Sy N ) . 153The 154.Va buffer , 155which is passed as the argument, is expected to have enough space to store 156the 157.Dv MAC 158address. At the open time both 159.Dq local 160and 161.Dq remote 162.Dv MAC 163addresses are the same, so this command could be used to retrieve the 164.Dq local 165.Dv MAC 166address. 167.It Dv SIOCSIFADDR 168Set the Media Access Control 169.Pq Dv MAC 170address of the 171.Dq remote 172side. This command is used by VMware port and expected to be executed on 173a descriptor, associated with control device 174.Pq usually Pa /dev/vmnet Ns Sy N . 175.El 176.Pp 177The control device also supports 178.Xr select 2 179for read; selecting for write is pointless, and always succeeds, since 180writes are always non-blocking. 181.Pp 182On the last close of the data device, the interface is 183brought down 184(as if with 185.Dq ifconfig tap Ns Sy N No down ) 186unless the devices is a VMnet device. 187All queued frames are thrown away. If the interface is up when the data 188device is not open, output frames are thrown away rather than 189letting them pile up. 190.Pp 191The 192.Nm 193device is also can be used with the VMware port as a replacement 194for the old VMnet device driver. The driver uses the minor number 195to select between 196.Nm 197and 198.Nm vmnet 199devices. VMnet minor numbers begin at 200.Va 0x10000 201+ 202.Va N . 203Where 204.Va N 205is a VMnet unit number. In this case control device is expected to be 206.Pa /dev/vmnet Ns Sy N , 207and network interface will be 208.Sy vmnet Ns Ar N . 209Additionally, VMnet devices do not ifconfig themselves down when the 210control device is closed. Everything else is the same. 211.Pp 212In addition to mentioned above 213.Xr ioctl 2 214there is one additional one for the VMware port. 215.Bl -tag -width VMIO_SIOCSETMACADDR 216.It Dv VMIO_SIOCSIFFLAGS 217VMware 218.Dv SIOCSIFFLAGS . 219.El 220.Sh SEE ALSO 221.Xr inet 4 , 222.Xr intro 4 223.\" .Sh BUGS 224.Sh AUTHORS 225This man page has been obtained from 226.Fx . 227