1 .\" $FreeBSD: src/share/man/man4/tap.4,v 1.1.2.7 2002/04/16 23:59:28 trhodes Exp $
9 .Nd Ethernet tunnel software network interface
15 interface is a software loopback mechanism that can be loosely
16 described as the network interface analog of the
20 does for network interfaces what the
22 driver does for terminals.
28 driver, provides two interfaces: an interface like the usual facility
30 (an Ethernet network interface in the case of
34 and a character-special device
37 A client program transfers Ethernet frames to or from the
43 interface provides similar functionality at the network layer:
44 a client will transfer IP (by default) packets to or from a
49 The network interfaces are named
52 etc., one for each control device that has been opened.
53 These Ethernet network interfaces persist until the
55 module is unloaded, or until removed with
61 devices are created using interface cloning.
62 This is done using the
63 .Dq ifconfig tap Ns Sy N No create
65 This is the preferred method of creating
68 The same method allows removal of interfaces by using the
69 .Dq ifconfig tap Ns Sy N No destroy
74 interface permits opens on the special control device
76 When this special device is opened,
78 will return a handle for the lowest unused
84 Control devices (once successfully opened) persist until the
86 module is unloaded or the interface is destroyed.
88 Each interface supports the usual Ethernet network interface
90 and thus can be used with
92 like any other Ethernet interface.
93 When the system chooses to transmit
94 an Ethernet frame on the network interface, the frame can be read from
99 writing an Ethernet frame to the control device generates an input frame on
100 the network interface, as if the
102 hardware had just received it.
104 The Ethernet tunnel device, normally
105 .Pa /dev/tap Ns Sy N ,
107 (it cannot be opened if it is already open)
108 and is restricted to the super-user, unless the
111 .Va net.link.tap.user_open
116 .Va net.link.tap.up_on_open
117 is non-zero, the tunnel device will be marked
119 when the control device is opened.
122 call will return an error
124 if the interface is not
126 Once the interface is ready,
128 will return an Ethernet frame if one is available; if not, it will
129 either block until one is or return
131 depending on whether non-blocking I/O has been enabled.
133 is longer than is allowed for in the buffer passed to
135 the extra data will be silently dropped.
139 call passes an Ethernet frame in to be
141 on the pseudo-interface.
144 call supplies exactly one frame; the frame length is taken from the
145 amount of data provided to
147 Writes will not block; if the frame cannot be accepted
148 for a transient reason
149 (e.g., no buffer space available),
150 it is silently dropped; if the reason is not transient
151 (e.g., frame too large),
152 an error is returned.
157 .In net/tap/if_tap.h ) :
158 .Bl -tag -width ".Dv TAPSIFINFO"
160 The argument should be a pointer to an
162 this sets the internal debugging variable to that value.
163 What, if anything, this variable controls is not documented here,
166 The argument should be a pointer to an
168 this stores the internal debugging variable's value into it.
170 Set network interface information (line speed and MTU).
171 The type must be the same as returned by
178 The argument should be a pointer to a
181 Retrieve network interface information (line speed, MTU and type).
182 The argument should be a pointer to a
185 Retrieve network interface name.
186 The argument should be a pointer to a
188 The interface name will be returned in the
192 Turn asynchronous I/O for reads
195 when data is available to be read)
196 off or on, according as the argument
198 value is or is not zero.
200 If any frames are queued to be read, store the size of the first one into the argument
202 otherwise, store zero.
204 Set the process group to receive
206 signals, when asynchronous I/O is enabled, to the argument
210 Retrieve the process group value for
212 signals into the argument
216 Retrieve the flags of the network interface associated with the control
217 device into the argument
221 Retrieve the MAC address of the associated network interface.
222 The argument should be a pointer to a
226 This command is used by the
230 Set the MAC address of the associated network interface.
231 The argument should be a pointer to a
237 The control device also supports
239 for read; selecting for write is pointless, and always succeeds, since
240 writes are always non-blocking.
242 On the last close of the data device, the interface is
245 .Dq ifconfig tap Ns Sy N No down ) .
246 All queued frames are thrown away.
247 If the interface is up when the data
248 device is not open, output frames are thrown away rather than
249 letting them pile up.