.TH ETHER 3 
.SH NAME
ether \- Ethernet device
.SH SYNOPSIS
.nf
.B bind -a #l\fIn\fP /net

.BI /net/ether n /clone
.BI /net/ether n /addr
.BI /net/ether n /mtu
.BI /net/ether n /ifstats
.BI /net/ether n /stats
.BI /net/ether n /[0-7]
.BI /net/ether n /[0-7]/data
.BI /net/ether n /[0-7]/ctl
.BI /net/ether n /[0-7]/ifstats
.BI /net/ether n /[0-7]/stats
.BI /net/ether n /[0-7]/type
.fi
.SH DESCRIPTION
The Ethernet interface,
.BI /net/ether n\f1,
is a directory
containing subdirectories, one for each distinct Ethernet packet type,
and
.BR clone ,
.BR addr ,
.BR mtu ,
.BR ifstats ,
and
.B stats
files.
.B stats
and
.B ifstats
are the same as in the subdirectories (see below).
Reading
.B addr
returns the MAC address of this interface in hex with no punctuation
and no trailing newline.  Reading
.B mtu
returns 3 12-byte numbers: the hardware's minimum MTU, the current
MTU and the maximum MTU supported by the interface.  The MTU
is set by writing
.B mtu
.I n
into the
.B ctl
file.
The number
.I n
(optional in the bind)
is the device number of the card, permitting multiple cards to be used on a single machine.
.PP
Each directory contains files to control the associated connection,
receive and send data,
and supply statistics.
Incoming Ethernet packets are demultiplexed by packet type and passed up
the corresponding open connection.
Reading from the
.B data
file reads packets of that type arriving from the network.
A read will terminate at packet boundaries.
Each write to the
.B data
file causes a packet to be sent.
The Ethernet address of the interface is inserted into
the packet header as the source address unless
.B l2bridge
is set.
.PP
A connection is assigned to a packet type by opening its
.B ctl
file and
writing 
.B connect
.I n
where
.I n
is a decimal integer constant identifying the Ethernet packet type.
A type of \-1 enables the connection to receive copies of packets of
all types.  A type of \-2 enables the connection to receive copies of
the first 64 bytes of packets of all types.
If multiple connections are assigned to a given packet type
a copy of each packet is passed up each connection.
.PP
Some interfaces also accept unique options when written to the
.I ctl
(or
.IR clone )
file; see the description of
.I wavelan
in
.IR plan9.ini (8).
The control messages described in
.IR ip (3)
under
.B "Configuring interfaces"
from
.L bridge
to
.L headersonly
are understood.
The additional control message
.L nonblocking
makes
.I write
systems calls to this interface non-blocking iff
followed by nothing or a non-zero integer;
a following
.L 0
makes
.I writes
block on a full output queue.
.PP
Reading the
.B ctl
file returns the decimal index of the associated connection, 0 through 7.
Reading the
.B type
file returns the decimal value of the assigned Ethernet packet type.
Reading the
.B stats
file returns status information such as the Ethernet address of the
card and general statistics, independent of the interface;
.B ifstats
contains device-specific data and statistics about the card.
The format of the
.B stats
file is
.IB stat : value ...\fR.
In particular, 
if
.B link
is non-zero,
.B mbps
is the current speed of the interface in
megabits-per-second.  While
.B in
and
.B out
are the total number of packets input or output
and do differ (in the case of dropped packets or
loop back) from hardware counters.
.PP
An interface normally receives only those packets whose 
destination address is that of the interface, the
broadcast address,
.BR ff:ff:ff:ff:ff:ff ,
or a a multicast address assigned to the interface.
Multicast addresses are added by writing
.B addmulti
.I ea
and remove by writing
.B remmulti
.I ea
to the
.B ctl
file.  Multicast addresses are automatically dropped when
the connection is closed.
The interface can be made to receive all packets on the
network by writing the string 
.B promiscuous
to the
.B ctl
file. 
The interface remains promiscuous until the control file is
closed by all connections requesting promiscuous mode.
The extra packets are passed up connections of types \-1
and \-2 only.
.PP
Writing
.B bridge
to the
.B ctl
file causes loop back packets to be ignored.  This is useful for
layer 3 bridging.  Writing
.B l2bridge
also allows the connection to set the source address and
receive packets with any destination address.
Writing
.B scanbs
[
.I secs
]
starts a scan for wireless base stations and sets the
scanning interval to
.IR secs.
Scanning is terminated when the connection is closed.
The default interval is 5s.  
For wired connections, this command is ignored.
.PP
Writing
.B headersonly
causes the connection to return only the first
58 bytes of the packet followed by a two-byte
length and a four-byte time in machine ticks.
Both numbers are in big-endian format.
.SH SOURCE
.B /sys/src/9/*/devether.c
.br
.B /sys/src/9/port/netif.c
.SH "SEE ALSO"
.IR ip (3).
.SH BUGS
The multicast interface makes removal of multicast
addresses on that rely on hashing difficult.
.PP
Interface MTU settings must be greater than those
used by
.IR ip (3);
this is not enforced.  NB: interface MTU is different
than IP stack's MTU.