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