freebsd-skq/share/man/man4/tap.4

.\" $FreeBSD$
.\" Based on PR#2411
.\"
.Dd July 9, 2000
.Os
.Dt TAP 4
.Sh NAME
.Nm tap
.Nd Ethernet tunnel software network interface
.Sh SYNOPSIS
.Cd pseudo-device tap
.Sh DESCRIPTION
The
.Nm tap
interface is a software loopback mechanism that can be loosely
described as the network interface analog of the
.Xr pty 4 ,
that is,
.Nm tap
does for network interfaces what the
.Nm pty
driver does for terminals.
.Pp
The
.Nm tap
driver, like the
.Nm pty
driver, provides two interfaces: an interface like the usual facility
it is simulating
.Po
an Ethernet network interface in the case of
.Nm tap ,
or a terminal for
.Nm pty
.Pc ,
and a character-special device
.Dq control
interface.
.Pp
The network interfaces are named
.Sy tap Ns Ar 0 ,
.Sy tap Ns Ar 1 ,
etc, as many as were made by
.Xr MAKEDEV 8 .
Each one supports the usual Ethernet network-interface
.Xr ioctl 2 Ns s ,
such as
.Dv SIOCSIFADDR
and
.Dv SIOCSIFNETMASK ,
and thus can be used with
.Xr 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
.Po
it appears as
.Dq input
there
.Pc ;
writing an Ethernet frame to the control device generates an input frame on
the network interface, as if the
.Pq non-existent
hardware had just received it.
.Pp
The Ethernet tunnel device, normally
.Pa /dev/tap Ns Sy N ,
is exclusive-open
.Po
it cannot be opened if it is already open
.Pc
and is restricted to the super-user.
A
.Fn read
call will return an error
.Pq Er EHOSTDOWN
if the interface is not
.Dq ready .
Once the interface is ready,
.Fn read
will return an Ethernet frame if one is available; if not, it will 
either block until one is or return
.Er 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
.Fn read ,
the extra data will be silently dropped.
.Pp
A
.Xr write 2
call passes an Ethernet frame in to be
.Dq received
on the pseudo-interface.  Each
.Fn write
call supplies exactly one frame; the frame length is taken from the
amount of data provided to
.Fn write .
Writes will not block; if the frame cannot be accepted
for a transient reason
.Pq e.g., no buffer space available ,
it is silently dropped; if the reason is not transient
.Pq e.g., frame too large ,
an error is returned.
The following
.Xr ioctl 2
calls are supported
.Pq defined in Aq Pa net/if_tap.h Ns :
.Bl -tag -width VMIO_SIOCSETMACADDR
.It Dv TAPSDEBUG
The argument should be a pointer to an
.Va int ;
this sets the internal debugging variable to that value.  What, if
anything, this variable controls is not documented here; see the source
code.
.It Dv TAPGDEBUG
The argument should be a pointer to an
.Va int ;
this stores the internal debugging variable's value into it.
.It Dv FIONBIO
Turn non-blocking I/O for reads off or on, according as the argument
.Va int Ns 's
value is or isn't zero
.Pq Writes are always nonblocking .
.It Dv FIOASYNC
Turn asynchronous I/O for reads
.Po
i.e., generation of
.Dv SIGIO
when data is available to be read
.Pc
off or on, according as the argument
.Va int Ns 's
value is or isn't zero.
.It Dv FIONREAD
If any frames are queued to be read, store the size of the first one into the argument
.Va int ;
otherwise, store zero.
.It Dv TIOCSPGRP
Set the process group to receive
.Dv SIGIO
signals, when asynchronous I/O is enabled, to the argument
.Va int
value.
.It Dv TIOCGPGRP
Retrieve the process group value for
.Dv SIGIO
signals into the argument
.Va int
value.
.It SIOCGIFADDR
Retrieve the Media Access Control
.Pq MAC 
address. This command should be executed on descriptor, associated with
control device
.Pq Pa /dev/tap Ns Sy N .
The
.Va buffer ,
which is passed as argument, is expected to have enought space to store
.Pq MAC
address.
.It SIOCSIFADDR
Set the Media Access Control
.Pq MAC
address. This command should be executed on a descriptor, associated with
control device
.Pq Pa /dev/tap Ns Sy N .
.El
.Pp
The control device also supports
.Xr select 2
for read; selecting for write is pointless, and always succeeds, since
writes are always non-blocking.
.Pp
On the last close of the data device, by default, the interface is
brought down
.Po
as if with  
.Dq ifconfig tap Ns Sy N No down
.Pc .
All queued frames are thrown away. If the interface is up when the data 
device is not open output frames are always thrown away rather than 
letting them pile up.
.Pp
The 
.Nm tap
device is also can be used with VMware port as a replacement
of VMnet device driver. The driver uses minor number to select between
.Nm tap
and
.Nm vmnet
devices. VMnet minor numbering is
.Va 0x10000 
+
.Va N . 
Where
.Va N 
is a VMnet unit number. In this case control device is expected to be 
.Pa /dev/vmnet Ns Sy N ,
and network interface will be
.Sy vmnet Ns Ar N .
Everything else is the same. 
.Pp
In addition to mentioned above
.Xr ioctl 2
there are additional one for VMware port.
.Bl -tag -width VMIO_SIOCSETMACADDR
.It VMIO_SIOCSIFFLAGS
VMware 
.Dv SIOCSIFFLAGS .
.El
.Sh SEE ALSO
.Xr inet 4 ,
.Xr intro 4
.\" .Sh BUGS
.Sh AUTHORS
This man page has been obtained from
.Bx Free .