.\"

.\" Copyright 1994 Vrije Universiteit, The Netherlands.

.\" For full copyright and restrictions on use see the file COPYRIGHT in the

.\" top level of the Amoeba distribution.

.\"

.ig

Software: Philip Homburg, 1991

Document: Philip Homburg, Sept 3, 1991

Modified: Greg Sharp and Philip Homburg, March 1992

- merged with udp(L) and made a little more complete.

Greg Sharp, April 1992

- updated keywords for auto index generation

Modified: Kees J. Bot, June 1994

- changed to man(7) format for MINIX 3.

..

.TH IP 4

.SH NAME

ip, eth, psip, udp, tcp \- Internet Protocol server devices and definitions

.SH DESCRIPTION

.de SP

.if t .sp 0.4

.if n .sp

..

The

.BR ip* ,

.BR eth* ,

.BR psip* ,

.BR tcp* ,

and

.B 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

.B eth*

or a

.B psip*

device, not both.)

The

.B *

in the device names is a decimal number, so one may see names from

.B ip0

to

.BR 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.

.PP

The

.B eth*

and

.B psip*

devices give direct access to the network packets at the lowest level.

The

.BR ip* ,

.BR tcp* ,

and

.B udp*

devices give access to IP, TCP, or UDP services.

.PP

Most programs that use TCP/IP use code like the following to access the

proper devices:

.PP

.RS

.nf

if ((tcp_device= getenv("TCP_DEVICE")) == NULL)

tcp_device= "/dev/tcp";

.fi

.RE

.PP

The low level networking programs such as

.BR ifconfig (8)

also have options to select the device they are working with. The

convention is:

.PP

.RS

.BI ETH_DEVICE= device

.br

.BI -E " device"

.RS

Device to use as raw ethernet device instead of the default /dev/eth.

.RE

.SP

.BI PSIP_DEVICE= device

.br

.BI -P " device"

.RS

Pseudo IP device to use instead of

.BR /dev/psip .

.RE

.SP

.BI IP_DEVICE= device

.br

.BI -I " device"

.RS

IP device to use instead of

.BR /dev/ip .

.RE

.SP

.BI TCP_DEVICE= device

.br

.BI -T " device"

.RS

TCP device to use instead of

.BR /dev/tcp .

.RE

.SP

.BI UDP_DEVICE= device

.br

.BI -U " device"

.RS

UDP device to use instead of

.BR /dev/udp .

.RE

.RE

.SS Programming

Access to the IP services is provided using filedescriptors to open IP

devices. These open IP channels can be configured with

.BR ioctl (2)

calls, and data can be transferred by calls to

.BR read (2),

and

.BR write (2).

.SS "Types (general)"

.IP <sys/types.h>

.br

Defines

.BR u8_t ,

.BR u16_t ,

.B u32_t

and

.B i32_t

(and

.BR U8_t ,

.BR U16_t ,

.B U32_t

and

.B I32_t

for use in prototypes).

.SS "Types (eth)"

.IP <net/gen/ether.h>

.br

Defines struct ether_addr (\fBether_addr_t\fP) and

.B ether_type_t

and

.B Ether_type_t

for use in prototypes.

.IP <net/gen/eth_io.h>

.br

Defines struct nwio_ethopt (\fBnwio_ethopt_t\fP) and

struct nwio_ethstat (\fBnwio_ethstat_t\fP)

.IP <net/gen/eth_hdr.h>

.br

Defines struct eth_hdr (\fBeth_hdr_t\fP)

.SS "Types (psip)"

.IP <net/gen/psip_hdr.h>

.br

[[[No description available yet.]]]

.IP <net/gen/psip_io.h>

.br

[[[No description available yet.]]]

.SS "Types (ip)"

.IP <net/gen/in.h>

.br

Defines

.BR ipaddr_t ,

.BR ipproto_t

and struct ip_hdropt (\fBip_hdropt_t\fP).

.IP <net/gen/ip_io.h>

.br

Defines struct nwio_ipconf (\fBnwio_ipconf_t\fP) and

struct nwio_ipopt (\fBnwio_ipopt_t\fP)

.IP <net/gen/ip_hdr.h>

.br

Defines struct ip_hdr (\fBip_hdr_t\fP)

.IP <net/gen/route.h>

.br

Defines struct nwio_route (\fBnwio_route_t\fP)

.SS "Types (tcp)"

.IP <net/gen/tcp.h>

.br

Defines

.B tcpport_t

and

.B Tcpport_t

for use in prototypes.

.IP <net/gen/tcp_io.h>

.br

Defines struct nwio_tcpconf (\fBnwio_tcpconf_t\fP),

struct nwio_tcpcl (\fBnwio_tcpcl_t\fP),

struct nwio_tcpatt (\fBnwio_tcpatt_t\fP) and

struct nwio_tcpopt (\fBnwio_tcpopt_t\fP).

.IP <net/gen/tcp_hdr.h>

.br

Defines struct tcp_hdr (\fBtcp_hdr_t\fP) and struct tcp_hdropt

(\fBtcp_hdropt_t\fP).

.SS "Types (udp)"

.IP <net/gen/udp.h>

.br

Defines

.B udpport_t

and

.B Udpport_t

for use in prototypes.

.IP <net/gen/udp_io.h>

.br

Defines struct nwio_udpopt (\fBnwio_udpopt_t\fP).

.IP <net/gen/udp_hdr.h>

.br

Defines struct udp_hdr (\fBudp_hdr_t\fP) and struct udp_io_hdr

(\fBudp_io_hdr_t\fP).

.SS "Byte Order Conversion"

All 16-bit and 32-bit quantities in IP headers must be in network byte

order. The macros described in

.BR hton (3)

can be used to convert these values to and from the byte order used by

the host machine.

.SS "The Internet Checksum"

The

.B oneC_sum

function (see

.BR oneC_sum (3))

is used to calculate the one's complement checksum needed for IP network

packets.

.SS "General Functions"

.PP

.ft B

\fIfd\fP = open(\fItcpip_device\fP, O_RDWR)

.ft R

.PP

This is how one normally obtains a filedescriptor for a new TCP/IP channel.

.I tcpip_device

names one of the TCP/IP devices. The channel may be used both to send or to

receive data.

.PP

.ft B

\fIn\fP = read(\fIfd\fP, \fIbuf\fP, \fIsize\fP)

.ft R

.PP

Receives one packet (low level devices) or a number of bytes (TCP stream).

Returns the the number of bytes placed into

.IR buf ,

or returns -1 with an error code placed into

.BR errno .

.PP

.ft B

\fIn\fP = write(\fIfd\fP, \fIbuf\fP, \fIsize\fP)

.ft R

.PP

Sends one packet (low level devices) or a number of bytes (TCP stream).

Returns

.I size

or -1 with the error code placed into

.BR errno .

The TCP/IP

.B read

and

.B write

functions behave like reads and writes on pipes when it comes to signals.

.SS "ETH Functions"

.PP

.ft B

ioctl(\fIfd\fP, NWIOGETHSTAT, &struct nwio_ethstat)

.ft R

.PP

The

.B NWIOGETHSTAT

ioctl

returns the Ethernet address and some statistics of the Ethernet server of

the channel

.IR fd .

The result is returned in the nwio_ethstat structure.

The \fBstruct nwio_ethstat\fP is defined in <net/gen/eth_io.h>:

.PP

.RS

.nf

.if t .ft C

typedef struct nwio_ethstat

{

ether_addr_t nwes_addr;

eth_stat_t nwes_stat;

} nwio_ethstat_t;

.SP

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;

.if t .ft R

.fi

.RE

.PP

.ft B

ioctl(\fIfd\fP, NWIOSETHOPT, &struct nwio_ethopt)

.ft R

.PP

Before an Ethernet channel can be used to send or receive

Ethernet packets, it has to be configured using the

.B NWIOSETHOPT

ioctl.

The structure

.B nwio_ethopt

is defined in <net/gen/eth_io.h>:

.PP

.RS

.nf

.if t .ft C

typedef struct nwio_ethopt

{

u32_t nweo_flags;

ether_addr_t nweo_multi, nweo_rem;

ether_type_t nweo_type;

} nwio_ethopt_t;

.SP

#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

.if t .ft R

.fi

.RE

.PP

The configuration is divided in a number of section (covered by the xx_MASK

macros).

Options can be set in the

.B nweo_flags

field.

The first section (\fBNWEO_ACC_MASK\fP) controls the access to a certain

Ethernet packet type.

If

.B NWEO_EXCL

is selected then this is the only channel that can send or

receive Ethernet packets of the selected type.

If

.B NWEO_SHARED

is selected then multiple channels (which all have to

select

.BR 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

.B NWEO_COPY

is selected then multiple channels have access to the same

Ethernet type and all receive a copy of an incoming packet.

.LP

The

.B NWEO_LOC_MASK

flags control the delivery of packets with a destination

address equal to the Ethernet address of the machine.

If

.B NWEO_EN_LOC

is selected then these packets will be delivered and with

.B NWEO_DI_LOC

they will be discarded.

.PP

.BR NWEO_BROAD_MASK ,

.BR NWEO_MULTI_MASK ,

and

.B NWEO_PROMISC_MASK

do the same to broadcast packets,

multicast packets and promiscuous mode packets as

.B NWEO_LOC_MASK

does for local packets.

Except that the precise multicast address is taken from the \fBnweo_multi\fP

field.

.LP

The

.B NWEO_REM_MASK

flags control whether communication is restricted to

single destination or not.

.B NWEO_REMSPEC

restricts sending and receiving of packets to the single

remote computer specified in the \fBnweo_rem\fP field.

.B NWEO_REMANY

allows sending to and receiving from any remote computer.

.PP

.B NWEO_TYPESPEC

restricts sending and receiving of packets to the type

specified in \fBnweo_type\fP.

The type has to be in network byte order (using

.BR hton (3)).

.B NWEO_TYPEANY

allows any type.

.PP

If the Ethernet header is completely specified by the

.B nweo_flags

i.e., all of

.BR NWEO_EN_LOC ,

.BR NWEO_DI_BROAD ,

.BR NWEO_DI_MULTI ,

.BR NWEO_DI_PROMISC ,

.BR NWEO_REMSPEC

and

.B NWEO_TYPESPEC

are

specified, then

.B NWEO_RWDATONLY

can be used to send and receive only the data part of an Ethernet packet.

If

.B NWEO_RWDATALL

is specified then both Ethernet header and data are used.

.SS "PSIP Functions"

.PP

[[[No description available yet.]]]

.SS "IP Functions"

.PP

.ft B

ioctl(\fIfd\fP, NWIOGIPCONF, &struct nwio_ipconf)

.ft R

.PP

The

.B NWIOGIPCONF

ioctl reports the Internet Address and the netmask.

For the \fInwio_ipconf\fP structure see the \fBNWIOSIPCONF\fP ioctl below.

.PP

.ft B

ioctl(\fIfd\fP, NWIOGIPOROUTE, &struct nwio_route)

.ft R

.PP

The

.B NWIOGIPOROUTE

ioctl can be used to query an IP server about its routing table.

[[[NWIODIPOROUTE, NWIOGIPIROUTE, NWIODIPIROUTE?]]]

The structure \fBnwio_route\fP is defined in <net/gen/route.h>:

.PP

.RS

.nf

.if t .ft C

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;

.SP

#define NWRF_EMPTY 0

#define NWRF_INUSE 1

#define NWRF_FIXED 2

.if t .ft R

.fi

.RE

.PP

The requested entry is taken from \fBnwr_ent_no\fP.

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 \fBnwr_ent_count\fP.

The \fBnwr_flags\fP indicates if the entry is in use (\fBNWRF_INUSE\fP) and

if the entry was inserted manually (using \fBNWIOSIPOROUTE\fP) or generated

by the IP server itself.

The route is described by

.BR nwr_dest ,

.BR nwr_netmask ,

.BR nwr_gateway ,

.BR nwr_dist ,

and

.BR nwr_pref .

\fBNwr_dest\fP and \fBnwr_netmask\fP select the destination addresses.

A value of 0.0.0.0 (0x0) in both \fBnwr_dest\fP and \fBnwr_netmask\fP means

every host.

A value of 255.255.255.255 (0xffffffff) in \fBnwr_netmask\fP means a single

host.

Other values of \fBnwr_netmask\fP are netmasks for the network specified

by \fBnwr_dest\fP.

\fBNwr_gateway\fP is gateway that should be used.

\fBNwr_dist\fP is a minimal distance.

Packets with a time to live smaller than \fBnwr_dist\fP will not reach the

destination.

If two routes have equal netmask and distance fields but different

gateways then the gateway with highest value in \fBnwr_pref\fP is used.

.PP

.ft B

ioctl(\fIfd\fP, NWIOSIPCONF, &struct nwio_ipconf)

.ft R

.PP

The

.B 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.

.B 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.

.PP

The structure \fBnwio_ipconf\fP is defined in <net/gen/ip_io.h>:

.PP

.RS

.nf

.if t .ft C

typedef struct nwio_ipconf

{

u32_t nwic_flags;

ipaddr_t nwic_ipaddr;

ipaddr_t nwic_netmask;

} nwio_ipconf_t;

.SP

#define NWIC_NOFLAGS 0x0

#define NWIC_FLAGS 0x3

# define NWIC_IPADDR_SET 0x1

# define NWIC_NETMASK_SET 0x2

.if t .ft R

.fi

.RE

.PP

The function of \fBnwio_ipconf\fP depends on the value of \fBnwic_flags\fP.

If

.B NWIC_IPADDR_SET

is set then the Internet Address will be set to

\fBnwic_ipaddr\fP.

If

.B NWIC_NETMASK_SET

is set then the Internet Address will be set to

\fBnwic_netmask\fP.

.PP

.ft B

ioctl(\fIfd\fP, NWIOSIPOPT, &struct nwio_ipopt)

.ft R

.PP

Before an IP channel can be used, it has to be configured using the

.B NWIOSIPOPT

ioctl.

The structure \fBnwio_ipopt\fP is defined in <net/gen/ip_io.h>:

.PP

.RS

.nf

.if t .ft C

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;

.SP

#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

.if t .ft R

.fi

.RE

.PP

The options are divided in several categories:

.BR NWIO_ACC_MASK ,

.BR NWIO_LOC_MASK ,

.BR NWIO_BROAD_MASK ,

.BR NWIO_REM_MASK ,

.BR NWIO_PROTO_MASK ,

.B NWIO_HDR_O_MASK

and

.BR NWIO_RW_MASK .

A channel is configured when one option of each category is set.

.PP

The options covered by

.B NWIO_ACC_MASK

control the number of channels that

can use one IP protocol.

If

.B NWIO_EXCL

is specified then only that channel can use a certain IP protocol.

If

.B NWIO_SHARED

then multiple channels that all have to specify

.B NWIO_SHARED

can use the same IP protocol, but incoming packets will

be delivered to a most one channel.

.B NWIO_COPY

does not impose any restrictions.

Every channel gets a copy of an incoming packet.

.PP

.B NWIO_LOC_MASK

and

.B NWIO_BROAD_MASK

control the delivery of packets.

If

.B NWIO_EN_LOC

is specified then packets that are explicitly send to

the IP server are delivered.

If

.B NWIO_EN_BROAD

is specified then broadcast packets are delivered.

Either one or both of them can be disabled with

.B NWIO_DI_LOC

and

.BR NWIO_DI_BROAD .

.PP

.B NWIO_REMSPEC

can be used to restrict communication to one remote host.

This host is taken from the \fBnwio_rem\fP field.

If any remote host is to be allowed then

.B NWIO_REMANY

can be used.

.PP

.B NWIO_PROTOSPEC

restricts communication to one IP protocol, specified

in \fBnwio_proto\fP.

.B NWIO_PROTOANY

allows any protocol to be sent or received.

.PP

.B NWIO_HDR_O_SPEC

specifies all IP header options in advance.

The values are taken from

.BR nwio_hdropt ,

.BR nwio_tos ,

.BR nwio_ttl ,

and

.BR nwio_df .

\fBNwio_hdropt\fP specifies the IP options that should be present in an

outgoing packet.

\fBIp_hdropt_t\fP is defined in <net/gen/in.h>:

.PP

.RS

.nf

.if t .ft C

typedef struct ip_hdropt

{

u8_t iho_opt_siz;

u8_t iho_data[IP_MAX_HDR_SIZE-IP_MIN_HDR_SIZE];

} ip_hdropt_t;

.if t .ft R

.fi

.RE

.PP

The bytes of size \fBiho_opt_siz\fP in \fBiho_data\fP are appended to the IP

header.

\fBNwio_tos\fP specifies the value of the ``type of service'' bits,

\fBnwio_ttl\fP gives the value of the ``time to live'' field and \fBnwio_df\fP

specifies whether fragmentation is disallowed or not.

.B NWIO_HDR_O_ANY

specifies that the header options should be specified at

each write request.

.PP

.B 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:

.BR NWIO_EN_LOC ,

.BR NWIO_DI_BROAD ,

.BR NWIO_REMSPEC ,

.B NWIO_PROTOSPEC

and

.BR NWIO_HDR_O_SPEC .

A read operation will also only return the data part, so the IP options will

be lost.

.PP

.ft B

ioctl(\fIfd\fP, NWIOSIPOROUTE, &struct nwio_route)

.ft R

.PP

The

.B NWIOSIPOROUTE

ioctl adds a route to the routing table.

See \fBNWIOGIPOROUTE\fP above for a description of the \fBnwio_route\fP

structure.

The fields \fBnwr_ent_no\fP and \fBnwr_ent_count\fP are ignored.

.SS "TCP Functions"

.PP

.ft B

ioctl(\fIfd\fP, NWIOTCPCONN, &struct nwio_tcpcl)

.ft R

.PP

The

.B NWIOTCPCONN

ioctl tries to setup a connection with a remote TCP/IP server.

The channel must be fully configured (see

.BR NWIOSTCPCONF )

and values for the local port, the remote port and the remote address have be

specified using

.B NWTC_LP_SET

or

.BR NWTC_LP_SEL ,

.B NWTC_SET_RA

and

.BR NWTC_SET_RP .

The struct nwio_tcpcl is defined in <net/gen/tcp_io.h> as:

.PP

.RS

.nf

.if t .ft C

typedef struct nwio_tcpcl

{

long nwtcl_flags;

long nwtcl_ttl;

} nwio_tcpcl_t;

.if t .ft R

.fi

.RE

.PP

Set the

.B nwtcl_flags

field to zero before the connect or listen call. [[[Further explanation of

nwio_tcpcl?]]]

.PP

.ft B

ioctl(\fIfd\fP, NWIOGTCPCONF, &struct nwio_tcpconf)

.ft R

.PP

This call reports the current configuration of a TCP channel.

The

.B nwtc_flags

field shows the status of the

.BR access ,

.BR locport ,

.B remaddr

and

.B remport

fields.

.B Nwtc_locaddr

contains the Internet address of the TCP/IP server.

.B Remaddr

contains the Internet address of the remote TCP/IP server when set with

.B NWTC_SET_RA

or after a successful connect or listen (see

.B NWIOTCPCONN

or

.BR NWIOTCPLISTEN ).

.B Nwio_locport

contains the local TCP/IP port set with

.B NWTC_LP_SET

or the selected port set with

.BR NWTC_LP_SEL .

.B Nwtc_remport

contains the TCP port of the remote TCP/IP server as set with

.B NWIO_SET_RP

or after a successful connect or listen.

.PP

A value of 0 (zero) is reported for

.BR nwtc_remaddr ,

.B nwtc_locport

or

.B nwtc_remport

when no value is set either explicitly or implicitly.

.PP

.ft B

ioctl(\fIfd\fP, NWIOTCPLISTEN, &struct nwio_tcpcl)

.ft R

.PP

The

.B NWIOTCPLISTEN

ioctl waits until a remote TCP/IP server tries to connect to this channel.

The channel has to be configured (see

.BR NWIOSTCPCONF ).

An additional restriction is that the local port

must be set (with

.BR NWTC_LP_SET )

or selected (with

.BR 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

.B NWIOGTCPCONF

can be used to find out what the address and port of the other side are.

.PP

.ft B

ioctl(\fIfd\fP, NWIOSTCPCONF, &struct nwio_tcpconf)

.ft R

.PP

Before a TCP channel can be used it must configured using the

.B NWIOSTCPCONF

ioctl.

The parameters to

.B NWIOSTCPCONF

are the channel file descriptor and a

.B struct nwio_tcpconf

as defined in <net/gen/tcp_io.h>:

.PP

.RS

.nf

.if t .ft C

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;

.SP

#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

.if t .ft R

.fi

.RE

.PP

A tcp channel is considered configured when one flag in each category has

been selected.

Thus one of

.BR NWTC_EXCL ,

.B NWTC_SHARED

or

.BR NWTC_COPY ,

one of

.BR NWTC_LP_UNSET ,

.B NWTC_LP_SET

or

.BR NWTC_LP_SEL ,

one of

.B NWTC_SET_RA

or

.BR NWTC_UNSET_RA ,

and one of

.B NWTC_SET_RP

or

.BR NWTC_UNSET_RP .

.PP

The acc flags control the access to a certain TCP port.

.B 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.

.B 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

.B NWTC_SHARED

flag.

.B NWTC_COPY

is specified when the programmer does not care about other channels.

This is the default.

.PP

The locport flags control which TCP port is used for communication.

.B NWTC_LP_UNSET

indicates the absence of a local port.

This is the default.

.B NWTC_LP_SET

means that the

.B nwtc_locport

field contains the local port to be used by TCP.

This value must be in network byte order (see

.BR hton (3).)

.B 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.

.LP

The

.B remaddr

flags specify which hosts are acceptable for connections.

.B NWTC_SET_RA

indicates that only connection to the host specified in

.B nwtc_remaddr

are acceptable.

.B Nwtc_remaddr

should be in network byte order (see

.BR hton (3).)

.B NWTC_UNSET_RA

allows every host on the other side of a connection.

This is the default.

.PP

The

.B remport

flags specify which remote ports are acceptable for connections.

.B NWTC_SET_RP

indicates that only the port specified in

.B nwtc_remport

is acceptable.

.B NWTC_UNSET_RP

allows every port on the other side of a connection.

This is the default.

.PP

.ft B

ioctl(\fIfd\fP, NWIOTCPSHUTDOWN)

.ft R

.PP

The

.B NWIOTCPSHUTDOWN

tells the TCP/IP server that no more data will be sent over the channel

specified by

.IR 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.

.PP

.ft B

ioctl(\fIfd\fP, NWIOGTCPOPT, &struct nwio_tcpopt)

.br

ioctl(\fIfd\fP, NWIOSTCPOPT, &struct nwio_tcpopt)

.ft R

.PP

The behaviour of a TCP channel may be changed by setting a number of

options. The TCP options can be obtained with the

.B NWIOGTCPOPT

ioctl and set with the

.B NWIOSTCPOPT

ioctl. The options are passed in a

.B struct nwio_tcpopt

as defined in <net/gen/tcp_io.h>:

.PP

.RS

.nf

.if t .ft C

typedef struct nwio_tcpopt

{

u32_t nwto_flags;

} nwio_tcpopt_t;

.SP

#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

.if t .ft R

.fi

.RE

.PP

The