NAME
ip, eth, psip, udp, tcp - Internet Protocol server devices
and definitions
DESCRIPTION
The ip*, eth*, psip*, tcp*, and udp* devices give access to
the Internet Protocol (IP) services in MINIX 3. There can
be up to 16 different networks, with 4 network devices each
(a network has either an eth* or a psip* device, not both.)
The * in the device names is a decimal number, so one may
see names from ip0 to ip15. A program scanning all networks
must try all 16, and not stop if one in between is missing.
One network is the default network. Its devices are linked
to names without numbers.
The eth* and psip* devices give direct access to the network
packets at the lowest level. The ip*, tcp*, and udp* dev-
ices give access to IP, TCP, or UDP services.
Most programs that use TCP/IP use code like the following to
access the proper devices:
if ((tcp_device= getenv("TCP_DEVICE")) == NULL)
tcp_device= "/dev/tcp";
The low level networking programs such as ifconfig(8) also
have options to select the device they are working with.
The convention is:
ETH_DEVICE=device
-E device
Device to use as raw ethernet device instead of
the default /dev/eth.
PSIP_DEVICE=device
-P device
Pseudo IP device to use instead of /dev/psip.
IP_DEVICE=device
-I device
IP device to use instead of /dev/ip.
TCP_DEVICE=device
-T device
TCP device to use instead of /dev/tcp.
UDP_DEVICE=device
-U device
UDP device to use instead of /dev/udp.
Programming
Access to the IP services is provided using filedescriptors
to open IP devices. These open IP channels can be config-
ured with ioctl(2) calls, and data can be transferred by
calls to read(2), and write(2).
Types (general)
<sys/types.h>
Defines u8_t, u16_t, u32_t and i32_t (and U8_t, U16_t,
U32_t and I32_t for use in prototypes).
Types (eth)
<net/gen/ether.h>
Defines struct ether_addr (ether_addr_t) and
ether_type_t and Ether_type_t for use in prototypes.
<net/gen/eth_io.h>
Defines struct nwio_ethopt (nwio_ethopt_t) and struct
nwio_ethstat (nwio_ethstat_t)
<net/gen/eth_hdr.h>
Defines struct eth_hdr (eth_hdr_t)
Types (psip)
<net/gen/psip_hdr.h>
[[[No description available yet.]]]
<net/gen/psip_io.h>
[[[No description available yet.]]]
Types (ip)
<net/gen/in.h>
Defines ipaddr_t, ipproto_t and struct ip_hdropt
(ip_hdropt_t).
<net/gen/ip_io.h>
Defines struct nwio_ipconf (nwio_ipconf_t) and struct
nwio_ipopt (nwio_ipopt_t)
<net/gen/ip_hdr.h>
Defines struct ip_hdr (ip_hdr_t)
<net/gen/route.h>
Defines struct nwio_route (nwio_route_t)
Types (tcp)
<net/gen/tcp.h>
Defines tcpport_t and Tcpport_t for use in prototypes.
<net/gen/tcp_io.h>
Defines struct nwio_tcpconf (nwio_tcpconf_t), struct
nwio_tcpcl (nwio_tcpcl_t), struct nwio_tcpatt
(nwio_tcpatt_t) and struct nwio_tcpopt (nwio_tcpopt_t).
<net/gen/tcp_hdr.h>
Defines struct tcp_hdr (tcp_hdr_t) and struct
tcp_hdropt (tcp_hdropt_t).
Types (udp)
<net/gen/udp.h>
Defines udpport_t and Udpport_t for use in prototypes.
<net/gen/udp_io.h>
Defines struct nwio_udpopt (nwio_udpopt_t).
<net/gen/udp_hdr.h>
Defines struct udp_hdr (udp_hdr_t) and struct
udp_io_hdr (udp_io_hdr_t).
Byte Order Conversion
All 16-bit and 32-bit quantities in IP headers must be in
network byte order. The macros described in hton(3) can be
used to convert these values to and from the byte order used
by the host machine.
The Internet Checksum
The oneC_sum function (see oneC_sum(3)) is used to calculate
the one's complement checksum needed for IP network packets.
General Functions
fd = open(tcpip_device, O_RDWR)
This is how one normally obtains a filedescriptor for a new
TCP/IP channel. tcpip_device names one of the TCP/IP dev-
ices. The channel may be used both to send or to receive
data.
n = read(fd, buf, size)
Receives one packet (low level devices) or a number of bytes
(TCP stream). Returns the the number of bytes placed into
buf, or returns -1 with an error code placed into errno.
n = write(fd, buf, size)
Sends one packet (low level devices) or a number of bytes
(TCP stream). Returns size or -1 with the error code placed
into errno. The TCP/IP read and write functions behave like
reads and writes on pipes when it comes to signals.
ETH Functions
ioctl(fd, NWIOGETHSTAT, &struct nwio_ethstat)
The NWIOGETHSTAT ioctl returns the Ethernet address and some
statistics of the Ethernet server of the channel fd. The
result is returned in the nwio_ethstat structure. The
struct nwio_ethstat is defined in <net/gen/eth_io.h>:
typedef struct nwio_ethstat
{
ether_addr_t nwes_addr;
eth_stat_t nwes_stat;
} nwio_ethstat_t;
typedef struct eth_stat
{
unsigned long ets_recvErr, /* # receive errors */
ets_sendErr, /* # send error */
ets_OVW, /* # buffer overwrite warnings,
(packets arrive faster than
can be processed) */
ets_CRCerr, /* # crc errors of read */
ets_frameAll, /* # frames not aligned (# bits
not a multiple of 8) */
ets_missedP, /* # packets missed due to too
slow packet processing */
ets_packetR, /* # packets received */
ets_packetT, /* # packets transmitted */
ets_transDef, /* # transmission deferred (there
was a transmission of an
other station in progress */
ets_collision, /* # collisions */
ets_transAb, /* # transmissions aborted due
to excessive collisions */
ets_carrSense, /* # carrier sense lost */
ets_fifoUnder, /* # fifo underruns (processor
is too busy) */
ets_fifoOver, /* # fifo overruns (processor is
too busy) */
ets_CDheartbeat, /* # times unable to transmit
collision signal */
ets_OWC; /* # times out of window
collision */
} eth_stat_t;
ioctl(fd, NWIOSETHOPT, &struct nwio_ethopt)
Before an Ethernet channel can be used to send or receive
Ethernet packets, it has to be configured using the
NWIOSETHOPT ioctl. The structure nwio_ethopt is defined in
<net/gen/eth_io.h>:
typedef struct nwio_ethopt
{
u32_t nweo_flags;
ether_addr_t nweo_multi, nweo_rem;
ether_type_t nweo_type;
} nwio_ethopt_t;
#define NWEO_NOFLAGS 0x0000L
#define NWEO_ACC_MASK 0x0003L
# define NWEO_EXCL 0x00000001L
# define NWEO_SHARED 0x00000002L
# define NWEO_COPY 0x00000003L
#define NWEO_LOC_MASK 0x0010L
# define NWEO_EN_LOC 0x00000010L
# define NWEO_DI_LOC 0x00100000L
#define NWEO_BROAD_MASK 0x0020L
# define NWEO_EN_BROAD 0x00000020L
# define NWEO_DI_BROAD 0x00200000L
#define NWEO_MULTI_MASK 0x0040L
# define NWEO_EN_MULTI 0x00000040L
# define NWEO_DI_MULTI 0x00400000L
#define NWEO_PROMISC_MASK 0x0080L
# define NWEO_EN_PROMISC 0x00000080L
# define NWEO_DI_PROMISC 0x00800000L
#define NWEO_REM_MASK 0x0100L
# define NWEO_REMSPEC 0x00000100L
# define NWEO_REMANY 0x01000000L
#define NWEO_TYPE_MASK 0x0200L
# define NWEO_TYPESPEC 0x00000200L
# define NWEO_TYPEANY 0x02000000L
#define NWEO_RW_MASK 0x1000L
# define NWEO_RWDATONLY 0x00001000L
# define NWEO_RWDATALL 0x10000000L
The configuration is divided in a number of section (covered
by the xx_MASK macros). Options can be set in the
nweo_flags field. The first section (NWEO_ACC_MASK) con-
trols the access to a certain Ethernet packet type. If
NWEO_EXCL is selected then this is the only channel that can
send or receive Ethernet packets of the selected type. If
NWEO_SHARED is selected then multiple channels (which all
have to select NWEO_SHARED) can use the same Ethernet type,
they all can send packets but incoming packets will be
delivered to at most one of them. If NWEO_COPY is selected
then multiple channels have access to the same Ethernet type
and all receive a copy of an incoming packet.
The NWEO_LOC_MASK flags control the delivery of packets with
a destination address equal to the Ethernet address of the
machine. If NWEO_EN_LOC is selected then these packets will
be delivered and with NWEO_DI_LOC they will be discarded.
NWEO_BROAD_MASK, NWEO_MULTI_MASK, and NWEO_PROMISC_MASK do
the same to broadcast packets, multicast packets and promis-
cuous mode packets as NWEO_LOC_MASK does for local packets.
Except that the precise multicast address is taken from the
nweo_multi field.
The NWEO_REM_MASK flags control whether communication is
restricted to single destination or not. NWEO_REMSPEC res-
tricts sending and receiving of packets to the single remote
computer specified in the nweo_rem field. NWEO_REMANY
allows sending to and receiving from any remote computer.
NWEO_TYPESPEC restricts sending and receiving of packets to
the type specified in nweo_type. The type has to be in net-
work byte order (using hton(3)). NWEO_TYPEANY allows any
type.
If the Ethernet header is completely specified by the
nweo_flags i.e., all of NWEO_EN_LOC, NWEO_DI_BROAD,
NWEO_DI_MULTI, NWEO_DI_PROMISC, NWEO_REMSPEC and
NWEO_TYPESPEC are specified, then NWEO_RWDATONLY can be used
to send and receive only the data part of an Ethernet
packet. If NWEO_RWDATALL is specified then both Ethernet
header and data are used.
PSIP Functions
[[[No description available yet.]]]
IP Functions
ioctl(fd, NWIOGIPCONF, &struct nwio_ipconf)
The NWIOGIPCONF ioctl reports the Internet Address and the
netmask. For the nwio_ipconf structure see the NWIOSIPCONF
ioctl below.
ioctl(fd, NWIOGIPOROUTE, &struct nwio_route)
The NWIOGIPOROUTE ioctl can be used to query an IP server
about its routing table. [[[NWIODIPOROUTE, NWIOGIPIROUTE,
NWIODIPIROUTE?]]] The structure nwio_route is defined in
<net/gen/route.h>:
typedef struct nwio_route
{
u32_t nwr_ent_no;
u32_t nwr_ent_count;
ipaddr_t nwr_dest;
ipaddr_t nwr_netmask;
ipaddr_t nwr_gateway;
u32_t nwr_dist;
u32_t nwr_flags;
u32_t nwr_pref;
} nwio_route_t;
#define NWRF_EMPTY 0
#define NWRF_INUSE 1
#define NWRF_FIXED 2
The requested entry is taken from nwr_ent_no. Entries are
counted from 0, so the value 0 can be used for an initial
query. The size of the routing table is returned in
nwr_ent_count. The nwr_flags indicates if the entry is in
use (NWRF_INUSE) and if the entry was inserted manually
(using NWIOSIPOROUTE) or generated by the IP server itself.
The route is described by nwr_dest, nwr_netmask,
nwr_gateway, nwr_dist, and nwr_pref. Nwr_dest and
nwr_netmask select the destination addresses. A value of
0.0.0.0 (0x0) in both nwr_dest and nwr_netmask means every
host. A value of 255.255.255.255 (0xffffffff) in
nwr_netmask means a single host. Other values of
nwr_netmask are netmasks for the network specified by
nwr_dest. Nwr_gateway is gateway that should be used.
Nwr_dist is a minimal distance. Packets with a time to live
smaller than nwr_dist will not reach the destination. If
two routes have equal netmask and distance fields but dif-
ferent gateways then the gateway with highest value in
nwr_pref is used.
ioctl(fd, NWIOSIPCONF, &struct nwio_ipconf)
The NWIOSIPCONF ioctl can be used to inform the IP server
about its Internet Address and/or its netmask. Normally an
IP server will discover its Internet Address using the RARP
protocol. NWIOSIPCONF can be used in the case that the RARP
failed, or the netmask has to be changed. Note that higher
level protocols (TCP and UDP) assume that the Internet
Address of an IP device does not change, therefore TCP and
UDP stop functioning if the Internet Address is changed.
The structure nwio_ipconf is defined in <net/gen/ip_io.h>:
typedef struct nwio_ipconf
{
u32_t nwic_flags;
ipaddr_t nwic_ipaddr;
ipaddr_t nwic_netmask;
} nwio_ipconf_t;
#define NWIC_NOFLAGS 0x0
#define NWIC_FLAGS 0x3
# define NWIC_IPADDR_SET 0x1
# define NWIC_NETMASK_SET 0x2
The function of nwio_ipconf depends on the value of
nwic_flags. If NWIC_IPADDR_SET is set then the Internet
Address will be set to nwic_ipaddr. If NWIC_NETMASK_SET is
set then the Internet Address will be set to nwic_netmask.
ioctl(fd, NWIOSIPOPT, &struct nwio_ipopt)
Before an IP channel can be used, it has to be configured
using the NWIOSIPOPT ioctl. The structure nwio_ipopt is
defined in <net/gen/ip_io.h>:
typedef struct nwio_ipopt
{
u32_t nwio_flags;
ipaddr_t nwio_rem;
ip_hdropt_t nwio_hdropt;
u8_t nwio_tos;
u8_t nwio_ttl;
u8_t nwio_df;
ipproto_t nwio_proto;
} nwio_ipopt_t;
#define NWIO_NOFLAGS 0x0000L
#define NWIO_ACC_MASK 0x0003L
# define NWIO_EXCL 0x00000001L
# define NWIO_SHARED 0x00000002L
# define NWIO_COPY 0x00000003L
#define NWIO_LOC_MASK 0x0010L
# define NWIO_EN_LOC 0x00000010L
# define NWIO_DI_LOC 0x00100000L
#define NWIO_BROAD_MASK 0x0020L
# define NWIO_EN_BROAD 0x00000020L
# define NWIO_DI_BROAD 0x00200000L
#define NWIO_REM_MASK 0x0100L
# define NWIO_REMSPEC 0x00000100L
# define NWIO_REMANY 0x01000000L
#define NWIO_PROTO_MASK 0x0200L
# define NWIO_PROTOSPEC 0x00000200L
# define NWIO_PROTOANY 0x02000000L
#define NWIO_HDR_O_MASK 0x0400L
# define NWIO_HDR_O_SPEC 0x00000400L
# define NWIO_HDR_O_ANY 0x04000000L
#define NWIO_RW_MASK 0x1000L
# define NWIO_RWDATONLY 0x00001000L
# define NWIO_RWDATALL 0x10000000L
The options are divided in several categories:
NWIO_ACC_MASK, NWIO_LOC_MASK, NWIO_BROAD_MASK,
NWIO_REM_MASK, NWIO_PROTO_MASK, NWIO_HDR_O_MASK and
NWIO_RW_MASK. A channel is configured when one option of
each category is set.
The options covered by NWIO_ACC_MASK control the number of
channels that can use one IP protocol. If NWIO_EXCL is
specified then only that channel can use a certain IP proto-
col. If NWIO_SHARED then multiple channels that all have to
specify NWIO_SHARED can use the same IP protocol, but incom-
ing packets will be delivered to a most one channel.
NWIO_COPY does not impose any restrictions. Every channel
gets a copy of an incoming packet.
NWIO_LOC_MASK and NWIO_BROAD_MASK control the delivery of
packets. If NWIO_EN_LOC is specified then packets that are
explicitly send to the IP server are delivered. If
NWIO_EN_BROAD is specified then broadcast packets are
delivered. Either one or both of them can be disabled with
NWIO_DI_LOC and NWIO_DI_BROAD.
NWIO_REMSPEC can be used to restrict communication to one
remote host. This host is taken from the nwio_rem field.
If any remote host is to be allowed then NWIO_REMANY can be
used.
NWIO_PROTOSPEC restricts communication to one IP protocol,
specified in nwio_proto. NWIO_PROTOANY allows any protocol
to be sent or received.
NWIO_HDR_O_SPEC specifies all IP header options in advance.
The values are taken from nwio_hdropt, nwio_tos, nwio_ttl,
and nwio_df. Nwio_hdropt specifies the IP options that
should be present in an outgoing packet. Ip_hdropt_t is
defined in <net/gen/in.h>:
typedef struct ip_hdropt
{
u8_t iho_opt_siz;
u8_t iho_data[IP_MAX_HDR_SIZE-IP_MIN_HDR_SIZE];
} ip_hdropt_t;
The bytes of size iho_opt_siz in iho_data are appended to
the IP header. Nwio_tos specifies the value of the ``type
of service'' bits, nwio_ttl gives the value of the ``time to
live'' field and nwio_df specifies whether fragmentation is
disallowed or not. NWIO_HDR_O_ANY specifies that the header
options should be specified at each write request.
NWIO_RWDATONLY specifies that the header should be omitted
from a write request. This option can only be used when all
header fields are specified in previous options:
NWIO_EN_LOC, NWIO_DI_BROAD, NWIO_REMSPEC, NWIO_PROTOSPEC and
NWIO_HDR_O_SPEC. A read operation will also only return the
data part, so the IP options will be lost.
ioctl(fd, NWIOSIPOROUTE, &struct nwio_route)
The NWIOSIPOROUTE ioctl adds a route to the routing table.
See NWIOGIPOROUTE above for a description of the nwio_route
structure. The fields nwr_ent_no and nwr_ent_count are
ignored.
TCP Functions
ioctl(fd, NWIOTCPCONN, &struct nwio_tcpcl)
The NWIOTCPCONN ioctl tries to setup a connection with a
remote TCP/IP server. The channel must be fully configured
(see NWIOSTCPCONF) and values for the local port, the remote
port and the remote address have be specified using
NWTC_LP_SET or NWTC_LP_SEL, NWTC_SET_RA and NWTC_SET_RP.
The struct nwio_tcpcl is defined in <net/gen/tcp_io.h> as:
typedef struct nwio_tcpcl
{
long nwtcl_flags;
long nwtcl_ttl;
} nwio_tcpcl_t;
Set the nwtcl_flags field to zero before the connect or
listen call. [[[Further explanation of nwio_tcpcl?]]]
ioctl(fd, NWIOGTCPCONF, &struct nwio_tcpconf)
This call reports the current configuration of a TCP chan-
nel. The nwtc_flags field shows the status of the access,
locport, remaddr and remport fields. Nwtc_locaddr contains
the Internet address of the TCP/IP server. Remaddr contains
the Internet address of the remote TCP/IP server when set
with NWTC_SET_RA or after a successful connect or listen
(see NWIOTCPCONN or NWIOTCPLISTEN). Nwio_locport contains
the local TCP/IP port set with NWTC_LP_SET or the selected
port set with NWTC_LP_SEL. Nwtc_remport contains the TCP
port of the remote TCP/IP server as set with NWIO_SET_RP or
after a successful connect or listen.
A value of 0 (zero) is reported for nwtc_remaddr,
nwtc_locport or nwtc_remport when no value is set either
explicitly or implicitly.
ioctl(fd, NWIOTCPLISTEN, &struct nwio_tcpcl)
The NWIOTCPLISTEN ioctl waits until a remote TCP/IP server
tries to connect to this channel. The channel has to be
configured (see NWIOSTCPCONF). An additional restriction is
that the local port must be set (with NWTC_LP_SET) or
selected (with NWTC_LP_SEL). When a remote address is set
only connections for that host are accepted, and when a
remote port is set only connections from that port are
accepted. After a successful listen NWIOGTCPCONF can be
used to find out what the address and port of the other side
are.
ioctl(fd, NWIOSTCPCONF, &struct nwio_tcpconf)
Before a TCP channel can be used it must configured using
the NWIOSTCPCONF ioctl. The parameters to NWIOSTCPCONF are
the channel file descriptor and a struct nwio_tcpconf as
defined in <net/gen/tcp_io.h>:
typedef struct nwio_tcpconf
{
u32_t nwtc_flags;
ipaddr_t nwtc_locaddr;
ipaddr_t nwtc_remaddr;
tcpport_t nwtc_locport;
tcpport_t nwtc_remport;
} nwio_tcpconf_t;
#define NWTC_NOFLAGS 0x0000L
#define NWTC_ACC_MASK 0x0003L
# define NWTC_EXCL 0x00000001L
# define NWTC_SHARED 0x00000002L
# define NWTC_COPY 0x00000003L
#define NWTC_LOCPORT_MASK 0x0030L
# define NWTC_LP_UNSET 0x00000010L
# define NWTC_LP_SET 0x00000020L
# define NWTC_LP_SEL 0x00000030L
#define NWTC_REMADDR_MASK 0x0100L
# define NWTC_SET_RA 0x00000100L
# define NWTC_UNSET_RA 0x01000000L
#define NWTC_REMPORT_MASK 0x0200L
# define NWTC_SET_RP 0x00000200L
# define NWTC_UNSET_RP 0x02000000L
A tcp channel is considered configured when one flag in each
category has been selected. Thus one of NWTC_EXCL,
NWTC_SHARED or NWTC_COPY, one of NWTC_LP_UNSET, NWTC_LP_SET
or NWTC_LP_SEL, one of NWTC_SET_RA or NWTC_UNSET_RA, and one
of NWTC_SET_RP or NWTC_UNSET_RP.
The acc flags control the access to a certain TCP port.
NWTC_EXCL means exclusive access. An attempt to configure a
channel will be denied if the same port is specified as that
of a channel that requested exclusive access. NWTC_SHARED
indicates that several channels use the same port but
cooperate. If the shared mode is specified for one channel
than all other channel that use the same port should also be
configured with the NWTC_SHARED flag. NWTC_COPY is speci-
fied when the programmer does not care about other channels.
This is the default.
The locport flags control which TCP port is used for commun-
ication. NWTC_LP_UNSET indicates the absence of a local
port. This is the default. NWTC_LP_SET means that the
nwtc_locport field contains the local port to be used by
TCP. This value must be in network byte order (see
hton(3).) NWTC_LP_SEL requests the TCP server to pick a
port. This port will be in the range from 32768 to 65535
and will be unique.
The remaddr flags specify which hosts are acceptable for
connections. NWTC_SET_RA indicates that only connection to
the host specified in nwtc_remaddr are acceptable.
Nwtc_remaddr should be in network byte order (see hton(3).)
NWTC_UNSET_RA allows every host on the other side of a con-
nection. This is the default.
The remport flags specify which remote ports are acceptable
for connections. NWTC_SET_RP indicates that only the port
specified in nwtc_remport is acceptable. NWTC_UNSET_RP
allows every port on the other side of a connection. This
is the default.
ioctl(fd, NWIOTCPSHUTDOWN)
The NWIOTCPSHUTDOWN tells the TCP/IP server that no more
data will be sent over the channel specified by fd. This
command can be issued when the channel is connected to a
remote TCP/IP server. The TCP/IP server will tell the
remote TCP/IP server and the client of the remote TCP/IP
server will receive an end-of-file indication.
ioctl(fd, NWIOGTCPOPT, &struct nwio_tcpopt)
ioctl(fd, NWIOSTCPOPT, &struct nwio_tcpopt)
The behaviour of a TCP channel may be changed by setting a
number of options. The TCP options can be obtained with the
NWIOGTCPOPT ioctl and set with the NWIOSTCPOPT ioctl. The
options are passed in a struct nwio_tcpopt as defined in
<net/gen/tcp_io.h>:
typedef struct nwio_tcpopt
{
u32_t nwto_flags;
} nwio_tcpopt_t;
#define NWTO_NOFLAG 0x0000L
#define NWTO_SND_URG_MASK 0x0001L
# define NWTO_SND_URG 0x00000001L
# define NWTO_SND_NOTURG 0x00010000L
#define NWTO_RCV_URG_MASK 0x0002L
# define NWTO_RCV_URG 0x00000002L
# define NWTO_RCV_NOTURG 0x00020000L
#define NWTO_BSD_URG_MASK 0x0004L
# define NWTO_BSD_URG 0x00000004L
#define NWTO_DEL_RST_MASK 0x0008L
# define NWTO_DEL_RST 0x00000008L
The NWTO_SND_URG option causes bytes written to the channel
to be send out as urgent data. On receiving an EURG error
the NWTO_RCV_URG option must be set to switch over to read-
ing urgent data. When all urgent data has been read an
ENOURG error will follow, indicating that the option must be
cleared with NWTO_RCV_NOTURG. Alas the BSD implementation
of urgent data disagrees with the RFC's, so to be BSD compa-
tible one must set the NWTO_BSD_URG option beforehand on a
channel that is to send or receive urgent data. Given that
the BSD implementation is the regarded as the TCP/IP stan-
dard one should always use the BSD style. The NWTO_DEL_RST
option delays a failure response on a connect to the same
port as the current open connection. Without this option a
connect would fail if a server is not yet listening. With
this option a connect will linger on until the server starts
listening. This option is useful for a server that opens a
connection, tells the remote end the local port number and
then listens (FTP), or for a program that forks off servers
for incoming connections (TELNET). A new connection may
come in before a new listen can be started, so it is nice if
the new connect doesn't fail. Use this option only when it
is clearly needed.
UDP Functions
ioctl(fd, NWIOGUDPOPT, &struct nwio_udpopt)
The NWIOGUDPOPT ioctl returns the current options that
result from the default options and the options set with
NWIOSUDPOPT. When NWUO_LP_SEL or NWUO_LP_SET is selected
the local port is returned in nwuo_locport. When
NWUO_RP_SET is selected the remote port is returned in
nwuo_remport. The local address is always returned in
nwuo_locaddr, and when NWUO_RA_SET is selected the remote
address is returned in nwuo_remaddr.
ioctl(fd, NWIOSUDPOPT, &struct nwio_udpopt)
A UDP channel must be configured using the NWIOSUDPOPT ioctl
before any data can be read or written. NWIOSUDPOPT takes
two parameters, a file descriptor to an open UDP device and
pointer to a nwio_udpopt structure that describes the
requested configuration. The nwio_udpopt structure is
defined in <net/gen/udp_io.h> as:
typedef struct nwio_udpopt
{
unsigned long nwuo_flags;
udpport_t nwuo_locport;
udpport_t nwuo_remport;
ipaddr_t nwuo_locaddr;
ipaddr_t nwuo_remaddr;
} nwio_udpopt_t;
#define NWUO_NOFLAGS 0x0000L
#define NWUO_ACC_MASK 0x0003L
#define NWUO_EXCL 0x00000001L
#define NWUO_SHARED 0x00000002L
#define NWUO_COPY 0x00000003L
#define NWUO_LOCPORT_MASK 0x000CL
#define NWUO_LP_SEL 0x00000004L
#define NWUO_LP_SET 0x00000008L
#define NWUO_LP_ANY 0x0000000CL
#define NWUO_LOCADDR_MASK 0x0010L
#define NWUO_EN_LOC 0x00000010L
#define NWUO_DI_LOC 0x00100000L
#define NWUO_BROAD_MASK 0x0020L
#define NWUO_EN_BROAD 0x00000020L
#define NWUO_DI_BROAD 0x00200000L
#define NWUO_REMPORT_MASK 0x0100L
#define NWUO_RP_SET 0x00000100L
#define NWUO_RP_ANY 0x01000000L
#define NWUO_REMADDR_MASK 0x0200L
#define NWUO_RA_SET 0x00000200L
#define NWUO_RA_ANY 0x02000000L
#define NWUO_RW_MASK 0x1000L
#define NWUO_RWDATONLY 0x00001000L
#define NWUO_RWDATALL 0x10000000L
#define NWUO_IPOPT_MASK 0x2000L
#define NWUO_EN_IPOPT 0x00002000L
#define NWUO_DI_IPOPT 0x20000000L
A UDP channel is considered configured when one flag in each
category has been selected. Thus one of NWUO_EXCL,
NWUO_SHARED or NWUO_COPY, one of NWUO_LP_SEL, NWUO_LP_SET or
NWUO_LP_ANY, one of NWUO_EN_LOC or NWUO_DI_LOC, one of
NWUO_EN_BROAD, or NWUO_DI_BROAD, one of NWUO_RP_SET, or
NWUO_RP_ANY, one of NWUO_RA_SET, or NWUO_RA_ANY, one of
NWUO_RWDATONLY, or NWUO_RWDATALL, and one of NWUO_EN_IPOPT,
or NWUO_DI_IPOPT. The acc flags control the access to a
certain UDP port. NWUO_EXCL means exclusive access: no
other channel can use this port. NWUO_SHARED means shared
access: only channels that specify shared access can use
this port and all packets that are received are handed to at
most one channel. NWUO_COPY imposes no access restriction
and all channels get a copy of every received packet for
that port.
The locport flags control the selection of the UDP port for
this channel. NWUO_LP_SEL requests the server to pick a
port. This port will be in the range from 32768 to 65535
and it will be unique. NWUO_LP_SET sets the local port to
the value of the nwuo_locport field. NWUO_LP_ANY does not
select a port. Reception of data is therefore not possible
but it is possible to send data.
The locaddr flags control the reception of packets.
NWUO_EN_LOC enables the reception of packets with the local
IP address as destination. NWUO_DI_LOC disables the recep-
tion of packet for the local IP address.
The broad flags control the reception of broadcast packets.
NWUO_EN_BROAD enables the reception of broadcast packets and
NWUO_DI_BROAD disables the reception of broadcast packets.
The remport flags let the client to specify one specific
remote UDP port or to allow any remote port. NWUO_RP_SET
sets the remote UDP port to the value of nwuo_remport. Only
packets with a matching remote port will be delivered and
all packets will be sent to that port. NWUO_RP_ANY allows
reception of packets form any port and when transmitting
packets the remote port has to be specified.
The remaddr flags control the remote IP address.
NWUO_RA_SET sets the remote IP address the value of
nwuo_remaddr. Only packets from that address will be
delivered and all packets will be sent to that address.
NWUO_RA_ANY allows reception of packets from any host and
when transmitting packets the remote host has to be speci-
fied.
The rw flags control the format of the data to be sent or
received. With NWUO_RWDATONLY only the data part of a UDP
packet is sent to the server and only the data part is
received from the server. The NWUO_RWDATALL mode presents
the data part of a UDP packet with a header that contains
the source and destination IP address, source and destina-
tion UDP ports, the IP options, etc. The server expects
such a header in front of the data to be transmitted.
The ipopt flags control the delivery and transmission of IP
options. When NWUO_EN_IPOPT is set IP, options will be
delivered and sent. When NWUO_DI_IPOPT is set IP option
will be stripped from received packets and no IP options
will be sent.
FILES
/dev/eth* Raw ethernet. The numbers in the device names
are decimal, so one may see names from eth0 to
eth15.
/dev/psip* First and second Pseudo IP network.
/dev/ip* IP devices for two ethernets and two Pseudo IP
networks.
/dev/tcp* TCP devices for same four networks.
/dev/udp* UDP devices.
/dev/eth, /dev/psip, /dev/ip, /dev/tcp, /dev/udp
Devices for the default network, links to the
devices above. Eth is only present if ethernet
is the default, psip only for pseudo IP.
SEE ALSO
hton(3), oneC_sum(3), inet(8), boot(8).
DIAGNOSTICS
Several errors may be returned by the TCP/IP server. The
error code is found in the errno variable if the read,
write, or ioctl call returns -1. The TCP/IP error codes
defined in <errno.h> are:
EPACKSIZE This indicates an attempt to read or
write with a buffer that is too large or
too small.
EOUTOFBUFS The TCP/IP server has insufficient
memory to execute the request.
EBADIOCTL This indicates an attempt to execute a
command the particular server does not
understand. For example, a NWIOGTCPCONF
on an ETH channel.
EBADMODE The request is refused because the chan-
nel is not fully configured, in the
wrong state or the parameters are
invalid.
EBADDEST This indicates an illegal destination
address for a packet.
EDSTNORCH The destination is not reachable.
EISCONN The channel is already connected so a
second request is refused.
EADDRINUSE This address is in use.
ECONNREFUSED The connection is refused by the other
side.
ECONNRESET The connection is reset (non-gracefully
terminated) by the other side.
ETIMEDOUT The connection is terminated due to an
expired timer.
EURG Urgent data is present and the current
receive mode does not allow urgent data
to be transferred.
ENOURG No urgent data is present and a request
came for urgent data.
ENOTCONN The request requires a connected channel
and the channel is not connected.
ESHUTDOWN The connection is shut down. That is, a
NWIOTCPSHUTDOWN has been executed so no
more data can be transmitted.
ENOCONN The connection does not exist.
EGENERIC A generic error code for extremely weird
cases.
AUTHOR
Philip Homburg (philip@cs.vu.nl)