atp(3N) atp(3N)NAME atp_open, atp_close, atp_sendreq, atp_getreq, atp_sendrsp, atp_getresp, atp_asynch_kind - provide a AppleTalk Transaction Protocol (ATP) interface SYNOPSIS #include <at/appletalk.h> #include <at/atp.h> cc [flags] files -lat [libraries] int atp_open(socket) at_socket *socket; int atp_close(fd) int fd; int atp_sendreq(fd, dest, buf, len, userdata, xo, xo_relt, tid, resp, retry, asynch); int fd; at_inet_t *dest; char *buf; int len, userdata, xo, xo_relt; u_short *tid; at_resp_t *resp; at_retry_t *retry; int asynch; int atp_getreq(fd, src, buf, len, userdata, xo, tid, bitmap, asynch); int fd; at_inet_t *src; char *buf; int *len, *userdata, *xo; u_short *tid; u_char bitmap; int asynch; int atp_sendrsp(fd, dest, xo, tid, resp); int fd; at_inet_t *dest; int xo; u_short tid; at_resp_t *resp; int atp_getresp(fd, tid, resp); int fd; u_short tid; at_resp_t *resp; int atp_asynch_kind(fd, tid); int fd; u_short *tid; January 1992 1
atp(3N) atp(3N)DESCRIPTION The ATP interface provides applications with access to the services of the AppleTalk Transaction Protocol, a transport layer protocol. These routines use the following structures, defined in <at/appletalk.h>. The at_inet_t structure specifies the AppleTalk internet address of a Datagram Delivery Protocol (DDP) AppleTalk socket endpoint: typedef struct at_inet { u_short net; at_node node; at_socket socket; } at_inet_t; The at_retry_t structure specifies the retry interval and maximum count for a transaction: typedef struct at_retry { short interval; short retries; u_char backoff; } at_retry_t; The members of this structure are interval The interval in seconds before ATP retries a request. retries The maximum number of retries for this ATP request. If retries is AT_INF_RETRY, the request will be repeated infinitely. backoff The value by which the interval is multiplied on each retry, to a maximum interval of 16 seconds. The at_resp_t, defined in <at/atp.h>, specifies buffers to be used for response data: typedef struct at_resp { u_char bitmap; struct iovec resp[ATP_TRESP_MAX]; int userdata[ATP_TRESP_MAX]; } at_resp_t; The members of this structure are 2 January 1992
atp(3N) atp(3N)bitmap The bitmap of responses expected and for which buffers are allocated. resp An iovec structure describing the response buffers and their lengths. userdata An array of 32-bit words holding the user bytes for each ATP response. The atp_open routine opens an ATP AppleTalk socket and returns a file descriptor for use with the remaining ATP calls. socket A pointer to the DDP socket number to open. If the AppleTalk socket number is 0, or if socket is NULL, a DDP socket is dynamically assigned. If non-NULL, the socket number is returned in socket. The atp_close routine closes the ATP AppleTalk socket identified by the file descriptor fd. The atp_sendreq routine sends an ATP request to another socket. This call blocks until a response is received. The parameters are fd The ATP file descriptor to use in sending the request. dest The AppleTalk internet address of the AppleTalk socket to which the request should be sent. buf The request data buffer. len The size of request data buffer size. userdata The user bytes for the ATP request header. xo Is true (nonzero) if the request is to be an exactly- once (XO) transaction. xo_relt Is ignored if xo is not set to true. Otherwise, it may be used to set the release timer value on the remote end. The default value is ATP_XO_DEF_REL_TIME. The other permissible values are: ATP_XO_30SEC, ATP_XO_1MIN, ATP_XO_2MIN, ATP_XO_4MIN, and ATP_XO_8MIN. These are declared in the file <at/atp.h>. All other values are illegal. January 1992 3
atp(3N) atp(3N)tid On return, the transaction identifier for this transaction. Can be NULL if the caller is not interested in the transaction identifier. The atp_sendreq routine requires a pointer to an at_resp_t structure containing two arrays for the response data: resp, an eight-entry iovec array, and userdata, an eight- entry array. The field iov_base in each iovec entry points to a buffer that will contain response data. The field iov_len specifies the length of the buffer. The field bitmap indicates the responses expected; on return it indicates the responses received. On return each iov_len entry indicates the length of the actual response data. If the number of responses is lower than expected, either an end-of-message was received or the retry count was exceeded. In the latter case, an error is returned. Each userdata entry in resp contains the user data for the respective ATP response packet. The retry pointer specifies the ATP request retry timeout in seconds and the maximum retry count. If retry is NULL, the default timeout, ATP_DEF_INTERVAL; the default retries, ATP_DEF_RETRIES; and a backoff value of 1 are used. The retries parameter of retry can be set to AT_INF_RETRY, in which case the transaction will be repeated infinitely. The atp_getreq routine receives an incoming ATP request. It is completed when a request is received. The parameters are fd The ATP file descriptor to use in receiving the request. src The AppleTalk internet address of the AppleTalk socket from which the request was sent. buf The data buffer in which to store the incoming request. len The data buffer size. userdata On return the user bytes from the ATP request header. Can be NULL if the caller is not interested in the userdata. xo Is true (nonzero) if the request is an exactly once (XO) transaction. tid The transaction identifier for this transaction. bitmap The responses expected by the requester. 4 January 1992
atp(3N) atp(3N)Because the transaction may require a response, the xo, tid, and bitmap parameters are always returned. The atp_sendrsp routine sends an ATP response to another AppleTalk socket. All response data is passed in one atp_sendrsp call. In the case of an XO transaction, the call does not return until a release is received from the requester or the release timer expires. In the latter case an error is returned. The parameters are fd The ATP file descriptor to use in sending the response. dest The AppleTalk internet address of the AppleTalk socket to which the response should be sent. tid The transaction identifier for this transaction. xo Is true (nonzero) if the response is an exactly once (XO) transaction. The atp_sendrsp routine requires a pointer to an at_resp_t structure containing two arrays for the response data: resp, an eight-entry iovec array, and userdata, an eight- entry array. The field iov_base in each iovec entry points to a buffer containing response data. The field iov_len specifies the length of the response data. Each userdata entry in resp contains the user data to be sent with the respective ATP response packet. The bitmap field indicates the responses to be sent. STATUS MESSAGES AND VALUES All routines return -1 on error with a detailed error code in errno. For additional errors returned by the underlying DDP module, see ddp(3N). The error messages are: [EAGAIN] The request failed due to a temporary resource limitation; try again. When this error occurs, no XO transaction is initiated. [EINVAL] The dest, len, resp, or retry parameter was invalid. [ENOENT] The request was an attempt to send a response to a nonexistent transaction. [ETIMEDOUT] The request exceeded the maximum retry count. January 1992 5
atp(3N) atp(3N)[EMSGSIZE] The response was larger than the buffer, or more responses were received than expected; truncated to available buffer space (atp_sendreq). The request buffer is too small for request data; truncated (atp_getreq). The response is too large; maximum is ATP_DATA_SIZE bytes (atp_sendrsp). WARNINGS The parameter asynch and the routines atp_getresp and atp_asynch_kind allow asynchronous sending and receiving of ATP requests. Asynchronous requests are not currently supported, so set asynch to 0 to indicate synchronous operation. The length of each response buffer, specified in iov_len, is overwritten by the actual response length when atp_sendreq returns. SEE ALSO ddp(3N), nbp(3N), pap(3N), rtmp(3N) Inside AppleTalk ``AppleTalk Programming Guide,'' in A/UX Network Applications Programming 6 January 1992