tap(4)
NAME
tap - Ethernet tunnel software network interface
SYNOPSIS
device tap
DESCRIPTION
- The tap interface is a software loopback mechanism that can
- be loosely
described as the network interface analog of the pty(4), - that is, tap
does for network interfaces what the pty driver does for - terminals.
- The tap driver, like the pty driver, provides two inter
- faces: an interface like the usual facility it is simulating (an Ethernet
- network interface in the case of tap, or a terminal for pty), and a char
- acter-special
device ``control'' interface. - The network interfaces are named ``tap0'', ``tap1'', etc.,
- one for each
control device that has been opened. These Ethernet network - interfaces
persist until if_tap.ko module is unloaded (if tap is built - into your
kernel, the network interfaces cannot be removed). - The tap interface permits opens on the special control de
- vice /dev/tap.
When this device is opened, tap will return a handle for the - lowest
unused tap device (use devname(3) to determine which). Con - trol devices
(once successfully opened) persist until if_tap.ko is un - loaded in the
same way that network interfaces persist (see above). - Each interface supports the usual Ethernet network interface
- ioctl(2)s,
such as SIOCSIFADDR and SIOCSIFNETMASK, and thus can be used - with
ifconfig(8) like any other Ethernet interface. When the - system chooses
to transmit an Ethernet frame on the network interface, the - frame can be
read from the control device (it appears as ``input'' - there); writing an
Ethernet frame to the control device generates an input - frame on the network interface, as if the (non-existent) hardware had just
- received it.
- The Ethernet tunnel device, normally /dev/tapN, is exclu
- sive-open (it
cannot be opened if it is already open) and is restricted to - the superuser, unless the sysctl(8) variable net.link.tap.user_open
- is non-zero.
A read() call will return an error (EHOSTDOWN) if the inter - face is not
``ready''. Once the interface is ready, read() will return - an Ethernet
frame if one is available; if not, it will either block un - til one is or
return EWOULDBLOCK, depending on whether non-blocking I/O - has been
enabled. If the frame is longer than is allowed for in the - buffer passed
to read(), the extra data will be silently dropped. - A write(2) call passes an Ethernet frame in to be ``re
- ceived'' on the
pseudo-interface. Each write() call supplies exactly one - frame; the
frame length is taken from the amount of data provided to - write().
Writes will not block; if the frame 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., frame too large), an error is - returned.
The following ioctl(2) calls are supported (defined in - TAPSDEBUG The argument should be a pointer to an
- int; this
- sets the internal debugging variable to
- that value.
What, if anything, this variable con - trols is not
documented here; see the source code. - TAPGDEBUG The argument should be a pointer to an
- int; this
- stores the internal debugging vari
- able's value into
it. - FIONBIO Turn non-blocking I/O for reads off or
- on, according
- as the argument int's value is or is
- not zero
(Writes are always nonblocking). - FIOASYNC Turn asynchronous I/O for reads (i.e.,
- generation of
- SIGIO when data is available to be
- read) off or on,
according as the argument int's value - is or is not
zero. - FIONREAD If any frames are queued to be read,
- store the size
- of the first one into the argument int;
- otherwise,
store zero. - TIOCSPGRP Set the process group to receive SIGIO
- signals, when
- asynchronous I/O is enabled, to the ar
- gument int
value. - TIOCGPGRP Retrieve the process group value for
- SIGIO signals
- into the argument int value.
- SIOCGIFADDR Retrieve the Media Access Control (MAC)
- address of
- the ``remote'' side. This command is
- used by the
VMware port and expected to be executed - on descriptor, associated with control device
- (usually
/dev/vmnetN or /dev/tapN). The buffer, - which is
passed as the argument, is expected to - have enough
space to store the MAC address. At the - open time
both ``local'' and ``remote'' MAC ad - dresses are the
same, so this command could be used to - retrieve the
``local'' MAC address. - SIOCSIFADDR Set the Media Access Control (MAC) ad
- dress of the
- ``remote'' side. This command is used
- by VMware
port and expected to be executed on a - descriptor,
associated with control device (usually
/dev/vmnetN). - The control device also supports select(2) for read; select
- ing for write
is pointless, and always succeeds, since writes are always - non-blocking.
- On the last close of the data device, the interface is
- brought down (as
if with ``ifconfig tapN down'') unless the device is a VMnet - device. All
queued frames are thrown away. If the interface is up when - the data
device is not open, output frames are thrown away rather - than letting
them pile up. - The tap device can also be used with the VMware port as a
- replacement for
the old VMnet device driver. The driver uses the minor num - ber to select
between tap and vmnet devices. VMnet minor numbers begin at - 0x800000 +
N; where N is a VMnet unit number. In this case the control - device is
expected to be /dev/vmnetN, and the network interface will - be vmnetN.
Additionally, VMnet devices do not ifconfig(8) themselves - down when the
control device is closed. Everything else is the same. - In addition to the above mentioned ioctl(2) calls, there is
- an additional
one for the VMware port. - VMIO_SIOCSIFFLAGS VMware SIOCSIFFLAGS.