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