____________________________________________________________________________
PREFACE ABOUT THIS REFERENCE
____________________________________________________________________________
This reference describes the AppleTalk application programming interface (API) specifications jointly developed by AT&T Computer Systems and Apple Computer, Inc. These API specifications define a standard interface to AppleTalk network protocols for AT&T's UNIX System V Release 4 operating system.
Software developers can create AppleTalk network application programs for UNIX systems that support both these API specifications and AppleTalk. Such applications are readily portable across various UNIX platforms.
AppleTalk network applications running in a UNIX environment can provide a standard desktop interface to Macintosh users accessing network services -- such as file sharing, printer sharing, electronic mail, distributed databases, and other client/server applications. UNIX file servers that support AppleTalk allow Macintosh and other personal computers to store and share information on the servers.
APIs implemented according to these specifications provide interfaces to the AppleTalk family of protocols. AT&T's Transport Interface (TLI) provides the interface to the AppleTalk Data Stream Protocol (ADSP) and the Datagram Delivery Protocol (DDP).
AT&T's TLI and the STREAMS input/output system provide developers with the tools needed to build distributed applications that are both protocol and media independent. The TLI's library of functions facilitates the development of network applications that are compatible with most industry-standard protocols. Such applications can easily provide support for multiple protocols on a UNIX system, migration to new protocols, and the addition of new features to existing network applications.
ADSP resides in the session layer of the International Standards Organization's (ISO) Open System Interconnection (OSI) reference model. Protocols in the session layer guarantee reliable data delivery. ADSP provides bidirectional, sequential, duplicate-free byte-stream service between any two sockets on an AppleTalk internet. ADSP services allow client processes to establish socket connections, to send and receive data -- either as a continuous stream or as logical messages intelligible by the receiving client -- and to close socket connections. ADSP provides a flow-control mechanism to ensure that transmitted data does not exceed the capacity of the receiving client's buffer.
DDP corresponds to the network layer of the OSI model and provides besteffort data delivery service. DDP is an end-to-end data flow protocol that extends socket-to-socket datagram delivery to an AppleTalk internet consisting of one or more AppleTalk networks connected by routers. A datagram is a packet of data that carries its own routing information. DDP defines logical addresses for sockets on an internet.
The AppleTalk Session Protocol (ASP) resides in the session layer of the OSI model. ASP provides the transport services needed for higher-level interactions between workstations and servers. ASP uses the services of the AppleTalk Transaction Protocol to open, manage, and close sessions; and to sequence requests and replies. ASP services include sending commands to a server and returning replies to a workstation, writing blocks of data to a
server, and retrieving status information from a server. During a session -- that is, when a logical connection exists between a workstation and a server -- ASP guarantees the delivery and execution of a sequence of transactions in the order sent.
The AppleTalk Transaction Protocol (ATP) resides in the transport layer of the OSI model. ATP provides loss-free transaction service between sockets on an internet, using a request/response transaction model and error recovery. By binding requests to responses, ATP ensures the reliable exchange of request/response pairs. ATP provides the basis for the session-oriented services of the AppleTalk Session Protocol and the Printer Access Protocol.
The Name Binding Protocol (NBP) resides in the transport layer of the OSI model. NBP converts user-defined names for zones and devices, or entities, to internet socket addresses that AppleTalk protocols can use. Each node maintains name-to-address mapping for its sockets. NBP uses a names directory to provide services that include name registration, deletion, lookup, and confirmation.
The Printer Access Protocol (PAP) resides in the session layer of the OSI model. PAP manages transactions between workstations and servers -- including setting up, maintaining, and terminating connections; and transferring data. PAP allows multiple connections at both the workstation and the server. PAP uses NBP services to locate addresses and ATP services to transfer data. PAP can determine a server's status and filter duplicate requests.
The Routing Table Maintenance Protocol (RTMP) resides in the transport layer of the OSI model. Internet routers use RTMP to establish and maintain routing tables used in forwarding datagrams from any source socket to any destination socket on an internet. Each router on an internet periodically broadcasts RTMP data packets containing updated routing tables, allowing all other routers on the internet to update their own routing tables.
The Zone Information Protocol (ZIP) resides in the session layer of the OSI model. Routers use ZIP to maintain network-to-zone-name mapping on an internet. ZIP allows a node on an extended network to select its zone at startup. ZIP provides commands that allow nodes on a local area network to obtain zone information. NBP uses ZIP mapping to determine which networks contain nodes that belong to a zone.
What this reference contains
This reference consists of three sections, which contain the following information:
-Section 1, "ADSP TLI Specification," describes the Transport Interface to the AppleTalk Data Stream Protocol.
-Section 2, "DDP TLI Specification," describes the Transport Interface to the Datagram Delivery Protocol.
-Section 3, "AppleTalk Manual Pages," contains all AppleTalk Section 3N (Network Programming) manual pages for UNIX System V Release 4. These manual pages correspond to the following AppleTalk protocols: AppleTalk Session Protocol, AppleTalk Transaction Protocol, Routing Table Maintenance Protocol, Name Binding Protocol, Printer Access Protocol, and Zone Information Protocol.
Conventions used in this reference
This reference uses the following typographic conventions to distinguish elements of the text:
-The names of function calls, parameters, and fields in structures appear in italics in the text of the reference.
-Code samples appear in Courier type -- for example:
This is 10-point Courier type.
- The manual pages in Section 3 appear in the standard UNIX man page format.
For more information
The following documents provide information about either the AppleTalk network system or the UNIX System V Release 4 operating system:
-Sidhu, Gursharan S., Andrews, Richard F., and Oppenheimer, Alan B. Apple Computer, Inc. Inside AppleTalk, second edition. Reading, Mass.: AddisonWesley, 1990. Explains the AppleTalk protocols in detail.
-AT&T, UNIX System V Release 4 Programmer's Guide: Networking Interfaces. Englewood Cliffs, N.J.: Prentice-Hall, 1990. Defines the TLI programming calls and describes programming with TLI.
-AT&T, UNIX System V Release 4 Programmer's Guide: STREAMS. Englewood Cliffs, N.J.: Prentice-Hall, 1990. Provides detailed information about STREAMS.
-Jacobson, Van. "Congestion Avoidance and Control." Proceedings of the ACM, SIGCOM '88, Palo Alto, Calif., August 1988. Describes algorithms developed for the TCP/IP protocol that improve performance over slow or congested data links.
____________________________________________________________________________
SECTION 1: ADSP TLI INTERFACE SPECIFICATION
____________________________________________________________________________
Summary of ADSP data structures
This section describes a Transport Interface (TLI) to the AppleTalk Data Stream Protocol (ADSP) and consists of several subsections:
-"General Concepts" explains STREAMS and TLI concepts relevant to this document.
-"Implementation Issues" describes several important implementation issues.
-"ADSP TLI Library Calls and Parameters" describes each ADSP function call and its parameters.
-"A Client/Server Example" presents a sample client/server program.
-"Summary of ADSP Data Structures" presents ADSP constants and data structures.
Some portions of this document are taken from The External Reference Specification for ADSP 1.5/2.0, version 0.14.
General concepts
The services of ADSP map closely to the TLI connection-mode calls. TLI's connection-mode service enables data to be transferred over an established connection in a reliable, sequenced manner. This service enables the negotiation of the parameters and options that govern the transfer of data. The following is a general scenario under TLI:
A connection end |
is |
identified |
by |
a local |
file descriptor (fd) returned by |
|
t_open(3N). Then |
an |
address is |
associated |
with this endpoint |
using |
|
t_bind(3N). At this |
point, the |
process can either listen for |
an incoming |
|||
connect indication, |
t_listen(3N), |
or initiate a connection request, |
t_connect(3N). The passive user can |
then accept |
the connection on a different |
|
fd, t_accept(3N). After the connection has been |
established, |
the process can |
|
send data, t_snd(3N), receive data, |
t_rcv(3N), |
or close the |
connection, |
t_close(3N). |
|
|
|
Error handling
Failures are indicated by a return value of -1. An external integer, t_errno, holds the specific error numbers. When a function sets t_errno to [TSYSERR] it indicates an operating system error, the specifics about which can be accessed through the external variable errno. When a function sets t_errno to [TLOOK], it indicates that an asynchronous event has happened. The user can call t_look(3N) to determine what event has occured.
Synchronous and asynchronous modes
In the synchronous mode, the user has to wait for a specific event to happen
before control is returned to the user. The |
asynchronous |
mode of |
operation |
|||||||
provides a mechanism |
for notifying |
a user of some event without forcing the |
||||||||
user to wait |
for |
the |
event. Synchronous mode is the default |
mode |
of |
|
||||
operation. This |
mode |
can be changed through |
the O_NDELAY |
or |
O_NONBLOCK flag, |
|||||
which may be |
set |
during t_open(3N) |
or fcntl(2). The following is |
a list |
of |
|||||
asynchronous |
events: |
T_LISTEN, T_CONNECT, T_DATA, T_EXDATA, and |
|
|
||||||
T_DISCONNECT. In |
synchronous mode, |
a |
function may return |
-1 |
with |
t_errno |
set |
|||
to [TLOOK] to |
indicate the occurrence |
of an |
asynchronous |
event. |
The |
|
t_look(3N) function is then invoked to identify the specific event. Another means to notify a process that an asynchronous event has occured is polling.
TLI functions supported for ADSP
The following TLI functions, which correspond to connection-oriented services, are supported:
t_accept(3N)
t_bind(3N)
t_close(3N)
t_connect(3N)
t_listen(3N)
t_look(3N)
t_open(3N)
t_rcv(3N)
t_rcvconnect(3N)
t_rcvdis(3N)
t_snd(3N)
t_snddis(3N)
t_unbind(3N)
The following general TLI functions are also supported:
t_alloc(3N)
t_error(3N)
t_free(3N)
t_getinfo(3N)
t_getstate(3N)
t_optmgmt(3N)
t_sync(3N)
The following functions are not supported and upon calling will return -1, with t_errno set to [TNOTSUPPORT]:
t_rcvrel(3N)
t_rcvudata(3N)
t_rcvuderr(3N)
t_sndrel(3N)
t_sndudata(3N)
Key for parameter arrays
For each function, an array is presented that summarizes the content of the input and output parameters. The key for the parameter arrays is as follows:
The parameter value is meaningful. (The input parameter must be set before the call and the output parameter may be read after the call.)
(x) The content of the object to which the x pointer points is meaningful.
The parameter value is meaningful but the parameter is optional.
--The parameter value is meaningless.
The parameter keeps the same value after the call as before the call.
Implementation issues
Options and management parameters
There are two user-selectable options: filter_addr, which supports connection-opening filters, and checksum, which is a boolean variable that can be set to TRUE or FALSE, indicating the desire to turn on or off DDP checksum. Other options or parameters are either set by the system administrator or calculated dynamically.
Connection-opening filters
The ADSP client may need to be selective about establishing connections with remote clients, because the addresses of some remote clients that make openconnection requests may not be acceptable to the local client. In order to establish a selection criterion, the client can provide ADSP with a filter of valid network addresses with which it is willing to establish connections. This filter could be as simple as specifying "open a connection only with the socket to which you are sending the open-connection request" or "open a connection only with a socket on a particular node." If ADSP receives an open-connection request from an address that does not match the filter, it sends back an open-connection denial and ignores the packet. In the case of a connection-listening socket, the end could conceivably become established with a different network address than the one to which the original open request was sent. The original requester can provide ADSP with a filter of network addresses with which it is willing to establish a connection.
Filter_addr is defined in adsp_opt structure. (See "Summary of ADSP Data Structures" later in Section 1.) It can be set when calling t_connect(3N) or before a t_listen(3N) by calling t_optmgmt(3N). A zero in the network number, node identifier, or socket number of filter_addr means that a connection can be established with any connection end on any network, node, or socket, respectively. Setting filter_addr to be the same as remote address means that a connection will be established only with a connection end on the specified remote address.
System administration parameters
There are several parameters tunable by the system administrator. These are:
-Max Receive buffer
-open connection request retries
-initial round-trip time Dynamically set parameters
Many of the ADSP variables are dynamically determined based on algorithms that have been successful in the TCP/IP community. A researcher at the Lawrence Berkeley Labs, Van Jacobson, has done significant work to improve the performance of the TCP/IP protocol over slow or congested data links. Since ADSP is very similar in design to TCP/IP, several of the techniques developed can and will be used for ADSP.
One of the techniques used involves dynamically determining round-trip times between two connection ends, through which ADSP will dynamically determine the values to use for retry intervals.
ADSP TLI protocol address
There are two ways to view the TLI protocol address for ADSP. Primitives like t_bind(3N) and t_connect(3N) accept an NBP entity name (object:type@zone) as their protocol address. The name registration, in t_bind(3N), or name resolution, in t_connect(3N), is done by the transport provider, transparent to the applications. This eliminates the need for NBP primitives in applications. The elimination of NBP primitives and use of the Name-to- Address Mapping provided by System V Release 4 are necessary to allow the
development |
of |
protocol-independent |
applications. Since AppleTalk nodes are |
|||||
not |
required |
to |
have |
network names, |
NBP entity |
names are not available in |
||
some |
cases. |
Sometimes |
all that is |
available is |
the internet |
socket address. |
||
This |
is the |
case with |
t_listen(3N) |
. When a connection request arrives, |
||||
t_listen(3N) |
returns |
the protocol |
address of the requesting |
user. All that is |
available |
for return is the internet socket address. An application |
is |
likely to |
respond with a t_accept(3N) and use the address returned |
by |
t_listen(3N) as the destination address. |
|
The transport provider must be able to distinguish between NBP entity names and internet socket addresses, so that it knows how to process the address field. The convention adopted involves using NULL-terminated strings for NBP entity names and using a leading NULL in the first character position, followed by an at_inet_t structure to identify an internet socket address. The t-bind(3N), t-connect(3N),
t-rcvconnect(3N), and t-listen(3N) calls return an internet socket address. See "Summary of ADSP Data Structures" later in Section 1.
The object and type fields of the NBP entity names cannot contain wildcards. The zone name field may be set to an asterik (*). Using an illegal NBP entity name or a name that cannot be resolved causes t-bind(3N) or t-connect(3N) to return a -1 and set t-errno to [TBADADDR]
Names that are transparently registered with a t_bind(3N) are transparently deregistered with t_unbind(3N) or upon the closing of the corresponding file descriptor.
ADSP features not supported
The following ADSP features are outside the scope of TLI and are not supported:
-connection opening outside of ADSP
-accepting connections on alternate nodes Non-TLI calls
In addition to the TLI calls mentioned in "TLI Functions Supported for ADSP" earlier in Section 1 the following nonstandard call is also supported:
adsp_fwdreset(3)
ADSP TLI library calls and parameters
Several of the ADSP TLI library function calls are described here. For a more detailed description of these calls refer to the UNIX System V Release 4 Programmer's Guide: Networking Interfaces.
fd = t_open (path, oflag, info)
T_open(3N) is called as the first step in the initialization of a transport endpoint. This function returns various default characteristics of the underlying transport protocol by setting fields in the t_info structure.
The |
following should be the |
values returned by the call to t_open(3N) and |
||
t_getinfo(3N) with ADSP as the transport provider: |
||||
Parameters |
Before call |
After |
call |
|
path |
|
ADSP_DEV |
-- |
|
oflag |
x |
-- |
|
|
info->addr |
-- |
99 |
||
info->options |
-- |
64 |
||
info->tsdu |
-- |
- |
1 |
|
info->etsdu |
-- |
572 |
||
info->connect |
-- |
- |
2 |
|
info->discon |
-- |
- |
2 |
|
info->servtype |
-- |
T |
_COTS |
The argument path points to the ADSP device identifier, such as, /dev/adsp, normally extracted from /etc/netconfig (see netconfig(4) and getnetpath(3N)). Oflag may be constructed from O_NDELAY or O_NONBLOCK OR-ed with O_RDWR.
T_open returns a file descriptor that identifies the local ADSP endpoint. The default characteristics of ADSP are returned in info. The maximum size of the ADSP address, addr, is 99 bytes. There is no limit to the size of the Transport Service Data Unit (TSDU). The maximum size of the Expedited Transport Service Data Unit (ETSDU), the attention packet, is 572 bytes. The attention packet is composed of 2 bytes of attention code followed by up to 570 bytes of attention data. No data can be sent with connection-request or disconnect calls. The only service type supported is T_COTS, the connectionoriented mode.
t_bind (fd, req, ret)
This function associates a protocol address with the transport endpoint specified by fd and activates that transport endpoint. The transport provider can then begin accepting or requesting connections. The req and ret arguments point to a t_bind structure. Qlen is used to indicate the maximum number of outstanding connection indications.
Parameters |
Before call |
After call |
req->addr.maxlen |
-- |
-- |
req->addr.len |
x>=0 |
-- |
req->addr.buf |
x(x) |
-- |
req->qlen |
x>=0 |
-- |
ret->addr.maxlen |
x |
-- |
ret->addr.len |
-- |
x |
ret->addr.buf |
x |
(x) |
req->qlen |
-- |
x>=0 |
req->addr.buf is a pointer to an NBP name (a NULL-terminated C string). The transport provider will allocate a dynamic socket and register that name on this socket.
If req is set to NULL or req->addr.len is zero, the transport provider will assign a dynamic socket and return the internet address of this socket in ret->addr.buf in a format described in "ADSP TLI Protocol Address," earlier in Section 1.
t_unbind (fd)
This function disables the transport endpoint specified by fd, which was previously bound by t_bind(3N). On completion of this call, no further data or events destined for this transport endpoint will be accepted by the transport provider.
Parameters |
Before |
call |
After |
call |
fd |
x |
|
-- |
|
The NBP name that was transparently registered by the transport provider during t_bind(3N) will be deregistered.
t_connect (fd, sndcall, rcvcall)
This function enables a user to request a connection to a specified destination. Fd identifies the local connection endpoint. Sndcall and rcvcall point to a t_call structure.
Parameters |
Before call |
After call |
fd |
x |
-- |
sndcall->addr.maxlen |
-- |
-- |
sndcall->addr.len |
x>0 |
-- |
sndcall->addr.buf |
x(x) |
-- |
sndcall->opt.maxlen |
-- |
-- |
sndcall->opt.len |
x>0 |
-- |
sndcall->opt.buf |
x(x) |
-- |
sndcall->udata.maxlen |
-- |
-- |
sndcall->udata.len |
0 |
-- |
sndcall->udata.buf |
-- |
-- |
sndcall->sequence |
-- |
-- |
rcvcall->addr.maxlen |
x |
-- |
rcvcall->addr.len |
-- |
x |
rcvcall->addr.buf |
x |
(x) |
rcvcall->opt.maxlen |
x |
-- |
rcvcall->opt.len |
-- |
x |
rcvcall->opt.buf |
x |
(x) |
rcvcall->udata.maxlen |
-- |
-- |
rcvcall->udata.len |
-- |
-- |
rcvcall->udata.buf |
-- |
-- |
rcvcall->sequence |
-- |
-- |
In sndcall, addr specifies the protocol address of the destination transport user. The sndcall->addr.buf points to an NBP name. The transport provider will resolve the name before sending a connection request.
In sndcall, opt points to an adsp_opt structure that is used to set ADSP address filters or turn on/off DDP checksum. The user can set the filter_addr field in the adsp_opt to filter connection ends responding to this connection request. A zero in the network number, node identifier, or socket number of filter_addr means that a connection can be established with any connection end on any network, node, or socket, respectively. Setting filter_addr to be the same as remote address means that a connection will be established only with a connection end on the specified remote address.
Since data cannot be sent with a t_connect(3N), sndcall->udata.len must be set to 0.
t_rcvconnect (fd, call)
This function enables a user to determine the status of a previously sent connection request and is used in conjunction with t_connect(3N) to establish a connection in asynchronous mode. The connection will be established on successful completion of this function. Fd identifies the endpoint and call contains information associated with the newly established connection.
Parameters |
Before call |
After call |
fd |
x |
-- |
call->addr.maxlen |
x |
-- |
call->addr.len |
-- |
x |
call->addr.buf |
x |
(x) |
call->opt.maxlen |
x |
-- |
call->opt.len |
-- |
x |
call->opt.buf |
x |
(x) |
call->udata.maxlen |
0 |
-- |
call->udata.len |
-- |
-- |
call->udata.buf |
-- |
-- |
call->sequence |
-- |
-- |
Since data cannot be sent with a connection request, call->udata.maxlen must be set to 0 before calling t_rcvconnect(3N). On return, the call->addr structure contains the protocol address of the responding endpoint.
t_optmgmt (fd, req, ret)
This function enables a transport user to retrieve, verify, or negotiate protocol options with the transport provider. The argument fd identifies a bound transport endpoint. The req and ret arguments point to a t_optmgmt structure.
Parameters |
Before call |
After call |
fd |
x |
-- |
req->opt.maxlen |
-- |
-- |
req->opt.len |
x |
-- |
req->opt.buf |
x(x) |
-- |
req->flags |
x |
-- |
ret->opt.maxlen |
x |
-- |
ret->opt.len |
-- |
x |
ret->opt.buf |
x |
(x) |
req->flags |
-- |
x |
The req->opt.buf points to an adsp_opt structure. The user can set the filter_addr field in the adsp_opt. A zero in the network number, node identifier, or socket number of filter_addr means that a connection can be established with any connection end on any network, node, or socket, respectively. Setting filter_addr to be the same as remote address means that a connection will be established only with a connection end on the specified remote address. The user can also change the default value of checksum.