feat: Added NetBSD man pages

1 files changed, 194 insertions, 0 deletions

diff --git a/static/netbsd/man4/tap.4 b/static/netbsd/man4/tap.4
new file mode 100644
index 00000000..80692410
--- /dev/null
+++ b/static/netbsd/man4/tap.4
@@ -0,0 +1,194 @@
+.\" $NetBSD: tap.4,v 1.16 2022/05/02 23:25:12 gutteridge Exp $
+.\"
+.\"  Copyright (c) 2004, 2005 The NetBSD Foundation.
+.\"  All rights reserved.
+.\"
+.\"  Redistribution and use in source and binary forms, with or without
+.\"  modification, are permitted provided that the following conditions
+.\"  are met:
+.\"  1. Redistributions of source code must retain the above copyright
+.\"     notice, this list of conditions and the following disclaimer.
+.\"  2. Redistributions in binary form must reproduce the above copyright
+.\"     notice, this list of conditions and the following disclaimer in the
+.\"     documentation and/or other materials provided with the distribution.
+.\"
+.\"  THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\"  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\"  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\"  PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\"  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\"  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\"  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\"  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\"  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\"  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\"  POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 2, 2022
+.Dt TAP 4
+.Os
+.Sh NAME
+.Nm tap
+.Nd Ethernet tunnel software network interface
+.Sh SYNOPSIS
+.Cd pseudo-device tap
+.Sh DESCRIPTION
+The
+.Nm
+driver allows the creation and use of virtual Ethernet devices.
+Those interfaces appear just as any real Ethernet NIC to the kernel,
+but can also be accessed by userland through a character device node in order
+to read frames being sent by the system or to inject frames. In that respect
+it is very similar to what
+.Xr tun 4
+provides.
+.Ss INTERFACE CREATION
+Interfaces may be created in two different ways:
+using the
+.Xr ifconfig 8
+.Cm create
+command with a specified device number,
+or its
+.Xr ioctl 2
+equivalent,
+.Dv SIOCIFCREATE ,
+or using the special cloning device
+.Pa /dev/tap .
+.Pp
+The former works the same as any other cloning network interface:
+the administrator can create and destroy interfaces at any time,
+notably at boot time.
+This is the easiest way of combining
+.Nm
+and
+.Xr bridge 4 .
+Later, userland will actually access the interfaces through the specific
+device nodes
+.Pa /dev/tapN .
+.Pp
+The latter is aimed at applications that need a virtual Ethernet device for
+the duration of their execution.
+A new interface is created at the opening of
+.Pa /dev/tap ,
+and is later destroyed when the last process using the file descriptor closes
+it.
+.Ss CHARACTER DEVICES
+Whether the
+.Nm
+devices are accessed through the special cloning device
+.Pa /dev/tap
+or through the specific devices
+.Pa /dev/tapN ,
+the possible actions to control the matching interface are the same.
+.Pp
+When using
+.Pa /dev/tap
+though, as the interface is created on-the-fly, its name is not known
+immediately by the application.
+Therefore the
+.Dv TAPGIFNAME
+ioctl is provided.
+It should be the first action an application using the special cloning device
+will do.
+It takes a pointer to a
+.Ft struct ifreq
+as an argument.
+.Pp
+Ethernet frames sent out by the kernel on a
+.Nm
+interface can be obtained by the controlling application with
+.Xr read 2 .
+It can also inject frames in the kernel with
+.Xr write 2 .
+There is absolutely no validation of the content of the injected frame,
+it can be any data, of any length.
+.Pp
+One call of
+.Xr write 2
+will inject a single frame in the kernel, as one call of
+.Xr read 2
+will retrieve a single frame from the queue, to the extent of the provided
+buffer.
+If the buffer is not large enough, the frame will be truncated.
+.Pp
+.Nm
+character devices support the
+.Dv FIONREAD
+ioctl which returns the size of the next available frame,
+or 0 if there is no available frame in the queue.
+.Pp
+They also support non-blocking I/O through the
+.Dv FIONBIO
+ioctl.
+In that mode,
+.Er EWOULDBLOCK
+is returned by
+.Xr read 2
+when no data is available.
+.Pp
+Asynchronous I/O is supported through the
+.Dv FIOASYNC ,
+.Dv FIOSETOWN ,
+and
+.Dv FIOGETOWN
+ioctls.
+The first will enable
+.Dv SIGIO
+generation, while the two other configure the process group that
+will receive the signal when data is ready.
+.Pp
+Synchronisation may also be achieved through the use of
+.Xr select 2 ,
+.Xr poll 2 ,
+or
+.Xr kevent 2 .
+.Ss ETHERNET ADDRESS
+When a
+.Nm
+device is created, it is assigned an Ethernet address
+of the form f2:0b:a4:xx:xx:xx.
+This address can later be changed using
+.Xr ifconfig 8
+to add an active link layer address, or directly via the
+.Dv SIOCALIFADDR
+ioctl on a
+.Dv PF_LINK
+socket, as it is not available on
+the ioctl handler of the character device interface.
+.Ss LINK STATE
+When an application has opened the
+.Nm
+character device the link is considered up, otherwise down.
+As such, it is best to open the character device once connectivity has
+been established so that Duplicate Address Detection, if applicable,
+can be performed.
+If connectivity is lost, the character device should be closed.
+.Sh FILES
+.Bl -tag -compact -width /dev/tap[0-9]*
+.It Pa /dev/tap
+cloning device
+.It Pa /dev/tap[0-9]*
+individual character device nodes
+.El
+.Sh SEE ALSO
+.Xr bridge 4 ,
+.Xr l2tp 4 ,
+.Xr tun 4 ,
+.Xr vether 4 ,
+.Xr ifconfig 8
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 3.0 .
+.Sh CAVEATS
+Starting from
+.Nx 10.0 ,
+the
+.Nm
+driver can no longer be used as a
+.Xr bridge 4
+endpoint because it supports a link state based on if it has been opened or not.
+Use the
+.Xr vether 4
+driver instead as it's been explicitly designed for this purpose.