Date: Sun Dec 17 10:33:45 GMT 2000

Name

ipsvr - the TCP/IP server

Synopsis

Description

- 3 -

These are the capabilities for the Ethernet, IP, TCP and UDP interfaces, respectively.
The default TCP/IP server elements for a user are defined in ampolicy.h. Typically they are the names in the following table:

These defaults can be overridden by either the environment variables below or in some cases by the command line options of the various programs that use the TCP/IP server.

Environment Variables

There are four string environment variables, each referring to one of the above server capabilities of the IP server: ETH_SERVER, IP_SERVER, TCP_SERVER and UDP_SERVER. The value of these environment variables is interpreted as a path name that refers to a capability of the TCP/IP server. To use the environment variables to override the default server, issue the following commands:

Programming Interface Summary

Access to the IP server is provided by the library routines described in ip(L).

Administration

- 5 -

Once the first TCP/IP server is running, rarp(A) and tftp(A) can be started by the boot(A) server and these can boot the remaining Amoeba processors. (The boot server is started on the Bullet Server which is normally booted from disk.) Note that the rarp and tftp servers typically use more than 1.5MB and must run on the only machine guaranteed to be up, i.e., the TCP/IP host. Make sure it has enough memory free.

In the following it is assumed that one of the above mechanisms has been provided to boot the kernel containing the first TCP/IP server.

A TCP/IP kernel needs to to be told its Internet address and a netmask using ifconfig(A). This can also be done using setupipsvr(A) in combination with the boot server. See setupipsvr(A) for an example of how to set up the boot server to do this.
To check if a server knows its own Internet address use the command

ifconfig $IP_SERVER

It reports something like:

hostaddr= 130.37.24.11 netmask= 255.255.255.0

or (after a while):

hostaddr not set

If the Internet address has not (yet) been set then it can be set using ifconfig (as follows:

ifconfig -h 130.37.24.11 $IP_SERVER

with the appropriate address in place of the one shown).
Take a look at the netmask to see if it matches the netmask of the network the machine is on. The netmask can be changed with

ifconfig -n <netmask> $IP_SERVER.

If the boot server has been set up appropriately, the capabilities for the default TCP/IP server will have been installed in /super/cap/ipsvr each time tcpip_host is rebooted. However, the first time it is necessary to install the capabilities manually. Do this using:

get /super/hosts/tcpip_host/ip/eth | put /super/cap/ipsvr/eth

- 6 -

Interrupt this if it seems to be working. It should now also be possible to use ttn(U) to talk to other IP hosts on the Amoeba network. Look up the Internet address of a UNIX machine on the same network and try

ttn <Internet address of UNIX machine>

this will give you something like:

connecting to <Internet address of UNIX machine>
connect succeeded !!!!

SunOS UNIX (xxx.cs.vu.nl)

login:

CTRL-D can be used to exit from the login prompt.
At this moment you can use TCP/IP to talk to hosts on the same network as your Amoeba IP server but probably not to talk to machines on other networks. Issue the command to display the routing table of the TCP/IP server:

pr_routes

If nothing is shown it indicates an empty routing table.
The TCP/IP server needs to know some gateways in order to forward packets that are to be sent to hosts on other networks. There are three ways for the TCP/IP server to get a routing table: built into the kernel, added manually using add_route(A), or discovered dynamically using the Gateway Advertisement ICMPs. The last method is the most appropriate one at moment. Unfortunately, current gateways do not generate Gateway Advertisement ICMPs and a daemon is needed to generate these ICMPs. Start the program irdpd(A) in the background:

- 7 -

irdpd -b -I $IP_SERVER -U $UDP_SERVER &

After about one minute rerun pr_routes(A). It should show some output. For example,

1 DEST= 0.0.0.0, NETMASK= 0.0.0.0, GATEWAY= 130.37.24.2, dist= 1 pref= 1

Connections to machines on other networks should now be possible.
Until now Internet addresses have been used instead of host names. There two ways to map a hostname to an Internet address or the other way around. The first one is the /etc/hosts file. You can add the entry

ttn 127.0.0.1

The other way is the DNS. The TCP/IP programs are compiled with the so-called resolver library. This means that a DNS server can be used to look up Internet addresses. The resolver library uses the file /etc/resolv.conf. This file should contain one entry:

host uunet.uu.net

should report:

uunet.uu.net has address 137.39.1.2

See Also

add_route[A] , boot[A] , ftpd[A] , ifconfig[A] , ip[L] , irdpd[A] , ping[A] , pr_routes[A] , rarp[A] ,
setupipsvr[A] , telnetd[A] .

- 9 -

IP general purpose client interface

(in libraries: libamoeba.a)

Name

ip - Internet Protocol server's general-purpose client interface stubs

Synopsis

Description

- 10 -

used to transfer data using the protocol implemented by the server. This can typically be done with the tcpip_ routines since they are generic to all interfaces. However the semantics of tcpip_read and tcpip_write vary slightly, depending on the protocol in use. The routines specific for each protocol server and the exact semantics of the tcpip_ functions are described in the corresponding ip_xxx(L) manual page.

The descriptions of the various routines are divided into categories according to whether they are for byte-order conversion or general-purpose (i.e., they are used with all four interfaces). Before they are described, a brief introduction to the various types is given.

Types (general)

server/ip/types.h

Rights

The following rights are defined in server/ip/tcpip.h:

IP_RIGHTS_OPEN
The right to do a tcpip_open (this indicates a server capability).

IP_RIGHTS_RWIO
The right to do I/O (this indicates a channel capability).

IP_RIGHTS_DESTROY
The right to destroy a connection.

The right to get existing capabilities (using tcpip_mkcap).

Byte Order Conversion

htons, htonl, ntohs, ntohl

- 11 -

u32_t
htonl(host_dword)
u32_t host_dword;

u16_t
ntohs(network_word)
u16_t network_word;

u32_t

These macros convert 16-bit and 32-bit quantities to and from the network byte order used by the TCP/IP protocols. The function of the macros is encoded in their name. H means host byte order, n means network byte order, s means a 16-bit quantity and l means a 32-bit quantity. Thus htons converts a 16-bit quantity from host byte order to network byte order. The difference between the lower case and upper case variants is that the lower case variants evaluate the argument at most once and the upper case variants can be used for constant folding. That is,

General Functions

OneC_sum is used to calculate the one's complement checksum needed for IP network packets. The IP checksum is described in RFC-1071 (Computing the Internet checksum).
One_Csum expects three parameters:

prev

- 12 -

tcpip_why

char *

This routine returns a pointer to a statically allocated string describing the error code err. If err is not one of the errors as described in the Diagnostics section below then tcpip_why will return the same string as err_why (see error(L)).

int *respite;

Tcpip_keepalive makes sure that a channel capability is not prematurely destroyed. In general channel capabilities are destroyed when not used for a while. Tcpip_keepalive returns the destruction timeout in respite. It is sufficient to call tcpip_keepalive again within respite milliseconds to prevent the channel from being destroyed.
See also tcpip_keepalive_cap.

tcpip_keepalive_cap

errstat

Tcpip_keepalive_cap provides a more convenient interface to tcpip_keepalive. Each time a new TCP/IP capability is created, it can be handed to tcpip_keepalive_cap. Tcpip_keepalive_cap will keep the capability alive until it is either destroyed, tcpip_unkeepalive_cap is called for that capability, or the program exits. The first time tcpip_keepalive_cap is called, it creates a separate thread to manage all the capabilities that should be kept alive.

tcpip_unkeepalive_cap

errstat
tcpip_unkeepalive_cap(cap)

- 13 -

capability *cap;

Tcpip_unkeepalive_cap removes the capability cap from the list of capabilities that should receive a tcpip_keepalive. Normally the IP server will destroy that capability after a while unless some other process keeps the capability alive.

A channel capability can be lost, or can be kept inside a process. Tcpip_mkcap recreates the capability which has object number obj. This provides a way to obtain an otherwise lost capability. To work out the object number of a particular channel use the std_status(U) command.

capability *chan_cap;

Tcpip_open creates a new channel for a server capability. A pointer to the server capability must be passed via the first argument and the new channel capability is stored in the object pointed to by be the second argument.

Tcpip_read transfers data from the TCP/IP server to the client. The call blocks until enough data is available. The semantics of tcpip_read are different for each of the servers. See the tcpip_read section in the ip_xxx(L) manual pages for the exact semantics.

tcpip_write

- 14 -

errstat
tcpip_write(chan_cap, buffer, bytes)
capability *chan_cap;

Tcpip_write transfers data from the client to the TCP/IP server. The call blocks until enough buffer space is available. The semantics of tcpip_write are different for each of the servers. See the tcpip_write section in the ip_xxx(L) manual pages for the exact semantics.

Diagnostics

The TCP/IP server introduces several new error codes. These are defined in server/ip/tcpip.h.

The TCP/IP server has insufficient memory to execute the request.

The request was refused because the channel is not fully configured, in the wrong state
or the parameters are invalid.

TCPIP_BADDEST
This indicates an illegal destination address for a packet.

TCPIP_DSTNORCH
The destination was not reachable.

TCPIP_ISCONN
The channel is already connected so a second request is refused.

TCPIP_ADDRINUSE
This address is in use.

TCPIP_CONNREFUSED
The connection was refused by the other side.

TCPIP_CONNRESET
The connection was reset (non-gracefully terminated) by the other side.

TCPIP_TIMEDOUT
The connection was terminated due to an expired timer.

TCPIP_URG

See Also

error(L), ip_eth[L] , ip_ip[L] , ip_tcp[L], ip_udp[L] , ipsvr[A] .

- 16 -

Name

ip_ip - Internet Protocol server's IP client interface stubs

Synopsis

Description

- 17 -

defines ipaddr_t, ipproto_t and struct ip_hdropt (ip_hdropt_t).

server/ip/gen/ip_io.h

defines struct nwio_ipconf (nwio_ipconf_t) and struct nwio_ipopt (nwio_ipopt_t)

server/ip/gen/ip_hdr.h

defines struct ip_hdr (ip_hdr_t)

server/ip/gen/route.h

defines struct nwio_route (nwio_route_t)

General Functions

Tcpip_read reads IP packets from the IP channel of a TCP/IP server, specified by chan_cap, into buffer, which has length nbytes. If the packet is larger than nbytes the packet is truncated to the buffer size and the error TCPIP_PACKSIZE will be returned. It blocks until it has a complete IP packet. If successful it returns the number of bytes read. Otherwise it returns a negative error status. If the read is interrupted the server returns STD_INTR.

It is possible to read the data only or the data plus IP header. See ip_ioc_setconf below for details.

Error Conditions:

See ip(L) for a description of the error codes.

TCPIP_BADMODE

- 18 -

errstat
tcpip_write(chan_cap, buffer, nbytes)
capability *chan_cap;

Tcpip_write transfers the IP packet in buffer from the client to the TCP/IP server's IP channel specified by chan_cap. The IP packet to be sent is nbytes long. It accepts only complete packets. It computes the checksum for the packet and inserts it at the appropriate place. The call blocks until enough buffer space for the whole packet is available in the TCP/IP server. On success it returns the number of bytes written. On failure it returns a negative error code.

Error Conditions:

See ip(L) for a description of the error codes.

TCPIP_BADMODE

IP Functions

struct nwio_ipconf *ipconf;

Ip_ioc_getconf reports the Internet address and the netmask. For the nwio_ipconf structure see ip_ioc_setconf below.

struct nwio_ipopt *ipopt;

This call returns in ipopt the current options of the IP channel specified by chan_cap. See ip_ioc_setopt for a description of the options.

ip_ioc_getroute

- 19 -

errstat
ip_ioc_getroute(chan_cap, route)

Ip_ioc_getroute can be used to query an IP server about it is routing table. The structure nwio_route is defined in server/ip/gen/route.h:

typedef struct nwio_route

#define NWRF_UNREACHABLE 4

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 field indicates if the entry is in use (NWRF_INUSE) and if the entry is static (NWRF_STATIC using ip_ioc_setroute) or generated by the IP server itself. A destination can be marked unreachable using NWRF_UNREACHABLE. 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 the gateway that should be used. Nwr_dist is the minimal distance (i.e. if the specified network is subnetted, destinations can be at varying distances.) 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 different gateways then the gateway with highest value in nwr_pref is used.

ip_ioc_setconf

errstat

- 20 -

ip_ioc_setconf(chan_cap, ipconf)

Ip_ioc_setconf 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. Ip_ioc_setconf 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 server/ip/gen/ip_io.h:

typedef struct nwio_ipconf

ipaddr_t nwic_ipaddr;
ipaddr_t nwic_netmask;

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.

struct nwio_ipopt *ipopt;

Before an IP channel can be used, it has to be configured using ip_ioc_setopt. The structure nwio_ipopt is defined in server/ip/gen/ip_io.h:

typedef struct nwio_ipopt

- 21 -

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 next- level protocol. If NWIO_EXCL is specified then only that channel can use a certain IP next-level protocol. If NWIO_SHARED is set then multiple channels that all have to specify NWIO_SHARED can use the same IP next-level protocol, but incoming packets will be delivered to at 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 sent 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 next-level 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 server/ip/gen/in.h:

See Also

error(L), ip[L] , ip_eth[L] , ip_tcp[L] , ip_udp[L] , ipsvr[A] .

- 23 -

Name

ip_eth - Internet Protocol server's Ethernet client interface stubs

Synopsis

Description

- 24 -

defines struct nwio_ethopt (nwio_ethopt_t) and struct nwio_ethstat (nwio_ethstat_t)

server/ip/gen/eth_hdr.h

defines struct eth_hdr (eth_hdr_t)

General Functions

Tcpip_read transfers Ethernet packets from the Ethernet channel specified by chan_cap to the client. The data is returned in buffer which has size nbytes. The call blocks until a packet is available. If successful it returns the number of bytes read. If unsuccessful the function returns an error status. It is possible to read just the data of the Ethernet packets or both the header and the data. See eth_ioc_setopt below for details.
Only reads with a buffer size greater than or equal to the maximum packet size are allowed.

Error Conditions:

See ip(L) for a description of the TCPIP_ error codes.

- 25 -

Tcpip_write transfers the nbytes of data in buffer from the client to the Ethernet channel specified by chan_cap. The call blocks until enough buffer space is available. The buffer must contain a complete packet and be at least of minimum size (60 bytes). On success this function returns the number of bytes written. On error it returns a negative error status.

Error Conditions:

See ip(L) for a description of the TCPIP_ error codes.

TCPIP_BADMODE

ETH Functions

struct nwio_ethopt *ethopt;

This call returns in ethopt the current options of an Ethernet channel specified by chan_cap. See eth_ioc_setopt for a description of the options.

struct nwio_ethstat *ethstat;

Eth_ioc_getstat returns the Ethernet address and some statistics about the channel specified by the capability chan_cap. The result is returned in the structure to which ethstat points. The struct nwio_ethstat defined in server/ip/gen/eth_io.h is used to pass the configuration description to the server.

- 26 -

errstat
eth_ioc_setopt(chan_cap, ethopt)

Before a capability of an Ethernet channel can be used to send or receive Ethernet packets, it has to be configured using eth_ioc_setopt. The structure nwio_ethopt is defined in server/ip/gen/eth_io.h:

typedef struct nwio_ethopt

- 27 -

ether_type_t nweo_type;
} nwio_ethopt_t;

#define NWEO_NOFLAGS 0x0000L

#define NWEO_PROMISC_MASK 0x0080L

The configuration is divided in a number of sections (covered by the xx_MASK macros). Options can be set in the nweo_flags field. The first section (NWEO_ACC_MASK) controls 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 local packets, i.e., with a destination address equal to the Ethernet address of the machine where the TCP/IP server is running. 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 promiscuous 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 a single destination or not. NWEO_REMSPEC restricts 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 Ethernet packets to the protocol type specified in nweo_type. (For example, the RARP protocol has type number 0x8035.) The type has to be in network byte order (see htons in ip(L)). 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 just the

See Also

error(L), ip[L] , ip_ip[L] , ip_tcp[L] , ip_udp[L] , ipsvr[A] .

- 29 -

Name

ip_udp - Internet Protocol server's UDP client interface stubs

Synopsis

Description

- 30 -

defines udpport_t and Udpport_t for use in prototypes.

server/ip/gen/udp_io.h

defines struct nwio_udpopt (nwio_udpopt_t).

server/ip/gen/udp_hdr.h

defines struct udp_hdr (udp_hdr_t) and struct udp_io_hdr (udp_io_hdr_t).

General Functions

A more convenient interface to read and write UDP packets is described in the UDP Library Functions section below. The following interface is described for completeness.

NB. The TCP/IP server sends and receives the udp_io_hdr in network byte-order. This includes the uih_ip_opt_len and uih_data_len fields. The following two tcpip_ routines do not decode these or any other fields to the local byte-order. The udp_read_msg and udp_write_msg functions do decode the length fields of the header making them simpler and safer to use.

Tcpip_read reads UDP packets from the UDP channel specified by chan_cap into buffer, which is of size nbytes. The call blocks until a complete packet is available. If successful it returns the number of bytes read.

It is possible to obtain just the data from the UDP packets or the data plus UDP headers. See udp_ioc_setopt below for details.

Error Conditions:

See ip(L) for a description of the error codes.

- 31 -

TCPIP_BADMODE

UDP Functions

struct nwio_udpopt *conf;

Udp_ioc_getopt returns the current options that result from the default options and the options set with udp_ioc_setopt 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.

struct nwio_udpopt *conf;

A UDP channel must be configured using udp_ioc_setopt before any data can be read or written. Udp_ioc_setopt takes two parameters, a pointer to the capability of the UDP channel and pointer to a nwio_udpopt structure that describes the requested configuration. The nwio_udpopt structure is defined in server/ip/gen/udp_io.h as:

- 32 -

typedef struct nwio_udpopt

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 NWUO_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 NWUO_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. (See tcpip_read, and tcpip_write above).

- 33 -

The NWUO_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 reception of packets for the local IP address.
The NWUO_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 NWUO_REMPORT flags let the client specify one specific remote UDP port or 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 from any port and when transmitting packets the remote port must be specified.

The NWUO_REMADDR flags control the remote IP address. NWUO_RA_SET sets the remote IP address to 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 specified.

The NWUO_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. This option can only be set if the header information is completely specified by the other options. Otherwise NWUO_RWDATALL must be used. 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 destination UDP ports, the IP options, etc. The server expects such a header to be present in front of the data to be transmitted.

The NWUO_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 options will be stripped from received packets and no IP options will be sent.

UDP Library Functions

The following routines provide a somewhat easier to use interface to UDP than the routines described above (tcpip_open, udp_ioc_setopt, tcpip_read and tcpip_write).

capability *chan_cap;
udpport_t srcport;
udpport_t dstport;

Udp_connect combines the functionality of tcpip_open and udp_ioc_setopt. A pointer to a UDP server capability should be passed in udp_cap, and the channel capability will be returned in the capability pointed to by chan_cap. If srcport is 0 then an unused port will be selected, otherwise the local port will be set to srcport. If dstport is non-zero then communication will be restricted to remote ports equal to dstport, otherwise any data can be sent to or received from any remote port. The same applies to dstaddr: if dstaddr is non-zero then only dstaddr can be reached. Currently no flags are defined so flags should be 0.

- 34 -

errstat
udp_read_msg(chan_cap, msg, msglen, actlen, flags)
capability *chan_cap;
char *msg;
int msglen;

Udp_read_msg delivers a UDP packet. The data part of the UDP packet is prepended with a udp_io_hdr. The actual length of the (possibly truncated) packet is returned in actlen. No flags are defined so flags should be 0.

char *msg;

A UDP packet can be sent with udp_write_msg. Msg should point to a udp_io_hdr followed by the data part of the UDP packet. The uih_dst_addr and uih_dst_port fields of the udp_io_hdr should be filled in if no values were specified in the udp_connect, or udp_reconnect call.

int flags;

Udp_close cleans up the administration kept by the UDP library but does not destroy the capability. This

See Also

error(L), ip[L] , ip_eth[L] , ip_ip[L] , ip_tcp[L] , ipsvr[A] .

- 36 -

Name

ip_tcp - Internet Protocol server's TCP client interface stubs

Synopsis

Description

- 37 -

server/ip/gen/tcp.h

defines tcpport_t and Tcpport_t for use in prototypes.

defines struct tcp_hdr (tcp_hdr_t) and struct tcp_hdropt (tcp_hdropt_t).

General Functions

Tcpip_read reads data from the TCP channel specified by chan_cap into buffer. The call blocks until either nbytes of data are available, or an error condition is detected. On success it returns the number of bytes read. If the connection has been closed then it returns 0. If urgent data is pending and the channel is not configured for urgent data then the error code TCPIP_URG is returned. The channel should then be reconfigured for urgent data using tcp_ioc_setopt. Further tcpip_reads should then be done until the error code TCPIP_NOURG is returned, indicating that there is no more urgent data. At this point the channel can be reconfigured for normal operation.

Error Conditions:

See ip(L) for a description of the error codes.

- 38 -

errstat
tcpip_write(chan_cap, buffer, nbytes)
capability *chan_cap;

Tcpip_write writes the nbytes of data in buffer to the TCP channel specified by chan_cap. The call blocks until enough buffer space is available to hold the entire write. Urgent data can be sent by setting the NWTO_SND_URG option using tcp_ioc_setopt and then doing the write.

Error Conditions:

See ip(L) for a description of the error codes.

STD_INTR

TCP Functions

struct nwio_tcpcl *clopt;

Tcp_ioc_connect tries to setup a connection with a remote TCP/IP server. The channel must be fully configured (see tcp_ioc_setconf) and values for the local port, the remote port and the remote address must have been specified using NWTC_LP_SET or NWTC_LP_SEL, NWTC_SET_RA and NWTC_SET_RP.

struct nwio_tcpconf *tcpconf;

This call reports the current configuration of a TCP channel. See tcp_ioc_setconffor struct nwio_tcpconf. 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, once it has been set with NWTC_SET_RA or after a successful connect or listen (see tcp_ioc_connect and tcp_ioc_listen). Nwio_locport contains the local TCP/IP port, set with

- 39 -

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 (see tcp_ioc_connect or tcp_ioc_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.

struct nwio_tcpopt *tcpopt;

This returns in tcpopt the current options for a TCP channel specified by chan_cap. See tcp_ioc_setopt for a description of the various options.

struct nwio_tcpcl *clopt;

Tcp_ioc_listen waits until a remote TCP/IP server tries to connect to this channel. The channel has to be configured (see tcp_ioc_setconf). 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, tcp_ioc_getconf can be used to find out the address and port of the other side.

struct nwio_tcpconf *conf;

Before a TCP channel (created by calling tcpip_open with a TCP server capability) can be used or options set, it must configured using tcp_ioc_setconf. The parameters to tcp_ioc_setconf are the channel capability and a struct nwio_tcpconf as defined in server/ip/gen/tcp_io.h:

typedef struct nwio_tcpconf

- 40 -

ipaddr_t nwtc_remaddr;
tcpport_t nwtc_locport;
tcpport_t nwtc_remport;
} nwio_tcpconf_t;

#define NWTC_NOFLAGS 0x0000L

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 NWTC_ACC_ flags control the access to a 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 then all other channels that use the same port should also be configured with the NWTC_SHARED flag. NWTC_COPY is specified when the programmer does not care about other channels. This is the default.

The locport flags control which TCP port is used for communication. 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 Byte Order Conversion in ip(L)). 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 connections to the host specified in nwtc_remaddr are acceptable. Nwtc_remaddr should be in network byte order (see Byte Order Conversion in ip(L)). NWTC_UNSET_RA allows any host on the other side of a connection. 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 any port on the other side of a connection. This is the default.

tcp_ioc_setopt

errstat

- 41 -

tcp_ioc_setopt(chan_cap, tcpopt)

The behavior of a TCP channel can be changed using tcp_ioc_setopt. The parameters to tcp_ioc_setopt are a channel capability and a struct nwio_tcopt as defined in server/ip/gen/tcp_io.h:

NWTO_SND_URG and NWTO_SND_NOTURG control the sending of urgent data. If NWTO_SND_URG is set, data written with tcpip_write will be sent as urgent data. If NWTO_SND_NOTURG is set, data will be sent as normal data. Similarly, NWTO_RCV_URG and NWTO_RCV_NOTURG control the reception of urgent data. If the wrong kind of data is present tcpip_read returns the error TCPIP_URG or TCPIP_NOURG, as appropriate.

NWTO_BSD_URG and NWTO_NOTBSD_URG control whether data is sent and received according to the BSD semantics or according to the semantics described in the RFC. These options can only be specified if a successful tcp_ioc_connect or tcp_ioc_listen has been done.

The NWTO_DEL_RST can be used to delay the sending of an RST packet in response to a SYN packet. Normally, when a SYN arrives for a port and there is no listen for that particular port, the TCP server will send an RST packet. This results in a ``Connection Refused'' error at the sending host. If a server repeatedly accepts connections for the same port, it can use this bit tell the TCP server not to send an RST immediately. When a SYN packet arrives and the TCP server is about to send an RST packet, it will look for existing channels to the same port with the bit set. If such a channel exists, the TCP server will delay the sending of the RST packet to give the server an opportunity to open a new channel and start a listen.

tcp_ioc_shutdown

See Also

error(L), ip[L] , ip_eth[L] , ip_ip[L] , ip_udp[L] , ipsvr[A] .

- 43 -

* This util reads with a minimal ftp interface files
* from a remote UNIX machine. On the UNIX side,
* the filed server handles the file requests. All received
* data will be written to stdout.

fprintf(stderr,"Remote IP-
Address:%d.%d.%d.%d\n",RemIpAddr[0],RemIpAddr[1],RemIpAddr[2],RemIpAddr[3]); /* Get the tcpip server capability */

err=name_lookup(TCPIPCAPNAME,&TcpipCap);

if (err != STD_OK)

/* set the remote IP address */

tcpconf.nwtc_remaddr=(u32_t)((RemIpAddr[3] << 24)

/* No Time-destroy of ChanCap... */

err=tcpip_keepalive_cap(&ChanCap);

if (err != STD_OK)

/* Send the read request to the Server: */

/* Wait, until SERVER is ready to receive... */

/* check the answer ... */
command=htons(command);

if (command != MSG_OK)

/* Now send the remote Path and file name...*/

command=htons(strlen(filename));

/* Wait, until SERVER ack. ... */

/* check again the answer from the remote server ... */ command=htons(command);

if (command != MSG_OK)

/* and the string... */

err = tcpip_write(&ChanCap,

command=0;

/* Wait, until SERVER ack. ... */

err=tcpip_read(&ChanCap,
(char *)&command,

command=htons(command);

if (command != MSG_OK)

/* write the data to STDOUT */
writtenbytes=write(1,buffer,byteswrite);

if ((writtenbytes != byteswrite) && (writtenbytes > 0))
{
fprintf(stderr,"Cant write enough Bytes to
stdout(%d).\n",byteswrite);

- 48 -

if (writtenbytes < 0)

fprintf(stderr,"Server aborted.\n");

/* Do the shutdown */

void tcp_shutdown()

- 49 -

exit(-1);

- 50 -

- i -

Types (general) ................................................................................................................ 10
Rights .............................................................................................................................. 10
Byte Order Conversion ...................................................................................................... 10
General Functions ............................................................................................................. 11
Diagnostics....................................................................................................................... 14
See Also ............................................................................................................................... 15 IP client interface ....................................................................................................................... 16
Name ................................................................................................................................... 16
Synopsis ............................................................................................................................... 16
Description ........................................................................................................................... 16
IP Types .......................................................................................................................... 16
General Functions ............................................................................................................. 17
IP Functions ..................................................................................................................... 18
Diagnostics....................................................................................................................... 22
See Also ............................................................................................................................... 22 Ethernet client interface .............................................................................................................. 23
Name ................................................................................................................................... 23
Synopsis ............................................................................................................................... 23
Description ........................................................................................................................... 23
Eth Types......................................................................................................................... 23
General Functions ............................................................................................................. 24
ETH Functions.................................................................................................................. 25
Diagnostics....................................................................................................................... 28
See Also ............................................................................................................................... 28 UDP client interface ................................................................................................................... 29
Name ................................................................................................................................... 29
Synopsis ............................................................................................................................... 29
Description ........................................................................................................................... 29
UDP Types....................................................................................................................... 29
General Functions ............................................................................................................. 30
UDP Functions.................................................................................................................. 31
UDP Library Functions ...................................................................................................... 33
Diagnostics....................................................................................................................... 35
See Also ............................................................................................................................... 35 TCP client interface.................................................................................................................... 36

- ii -

Name ................................................................................................................................... 36
Synopsis ............................................................................................................................... 36
Description ........................................................................................................................... 36
TCP Types ....................................................................................................................... 36
General Functions ............................................................................................................. 37
TCP Functions .................................................................................................................. 38
Diagnostics....................................................................................................................... 42
See Also ............................................................................................................................... 42 TCP example program................................................................................................................ 43