atp(3)

NAME
AppleTalk Transaction Protocol (ATP) interface

SYNOPSIS

#include <at/appletalk.h>
#include <at/atp.h>

int atp_open(at_socket *socket);

int atp_close(int fd);

int atp_sendreq(int fd, at_inet_t *dest, char *buf,
int len, int userdata, int xo, int xo_relt,
u_short *tid, at_resp_t *resp,
at_retry_t *retry, int nowait);

int atp_getreq(int fd, at_inet_t *src, char *buf,
int *len, int *userdata, int *xo, u_short *tid,
u_char *bitmap, int nowait);

int atp_sendrsp(int fd, at_inet_t *dest, int xo,
u_short tid, at_resp_t *resp);

int atp_getresp(int fd, u_short *tid, at_resp_t *resp);

int atp_abort(int fd);

int atp_look(int fd, at_inet_t *dest, u_short *tid);

DESCRIPTION

The ATP interface provides applications with access to the services of the Transaction Protocol, a transport layer protocol.

These routines use the following structures, defined in <at/appletalk.h>.

The at_inet_t structure specifies the internet address of a DDP socket endpoint:

    typedef struct  at_inet {
    	at_net     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;   /* Retry interval in seconds */
    	short  retries;    /* Maximum number of retries */
    	u_char backoff;    /* Retry backoff, must be 1 through 4 */
    } at_retry_t;

If the retries field of the at_retry_t structure is set to AT_INF_RETRY, then the request will be repeated indefinitely (forever).

The at_resp_t structure, defined in <at/atp.h>, specifies buffers to be used for response data:

    typedef struct at_resp {
    	u_char        bitmap;
    	u_char        filler[3];
    	struct iovec  resp[AT_ATP_TRESP_MAX];
    	int           userdata[AT_ATP_TRESP_MAX];
    } at_resp_t;

The members of this structure are:

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 socket and returns a file descriptor for use with the remaining ATP calls.

socket
    A pointer to the static DDP socket number to open. If the socket number is zero, a socket is dynamically assigned, and the socket number is returned in socket.

The atp_close routine closes the ATP 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.

fd  The ATP file descriptor to use in sending the request.

dest
    The internet address of the socket to which the request should be sent.

buf Specifies the request data buffer.

len Specifies the size of request data buffer size.

userdata
    Contains the user bytes for the ATP request header.

xo  Should be true (1) if the request is to be an exactly-once (XO) transaction.

xo_relt
    will be 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 AT_ATP_XO_DEF_REL_TIME. The other permissible values are: AT_ATP_XO_30SEC, AT_ATP_XO_1MIN, AT_ATP_XO_2MIN, AT_ATP_XO_4MIN and AT_ATP_XO_8MIN. These are declared in the file <at/atp.h>. All other values apart from these are illegal.

tid On return, contains the transaction identifier for this transaction; tid can be NULL if the caller is not interested in the transaction identifier.

resp
    The atp_sendreq routine requires a pointer to an at_resp_t structure (see definition given above). The atp_sendreq routine will return response data to the application in this structure. The field iov_base in each iovec entry of the resp parameter points to a buffer to contain response data. The field iov_len specifies the length of the buffer. The field bitmap of the resp parameter 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 less than expected, either an EOM 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.

retry
    The retry pointer specifies the ATP request retry timeout in seconds and the maximum retry count. If retry is NULL, the default timeout, AT_ATP_DEF_INTERVAL, and the default retries, AT_ATP_DEF_RETRIES, are used. The retries field of retry can be set to AT_INF_RETRY, in which case the transaction will be repeated infinitely.

nowait
    Set nowait to zero (0) to indicate synchronous operation, or to non-zero to indicate asynchronous operation.

The atp_getreq routine receives an ATP request sent from another socket. It is completed when a request is received.

fd  The ATP file descriptor to use in receiving the request.

src The internet address of the socket from which the request was sent.

buf Specifies the data buffer in which to store the incoming request.

len Specifies the data buffer size in which to store the incoming request.

userdata
    On return, contains the user bytes from the ATP request header; userdata can be NULL if the caller is not interested in the userdata.

xo  Indicates to the caller whether the request is to be an exactly once (XO) transaction. If it is to be an XO transaction, atp_getreq will set it true (non-zero).

tid Contains the transaction identifier for this transaction.

bitmap
    Indicates the responses expected by the requester.

nowait
    Indicates whether the operation should be asynchronous or not. Set nowait to zero (0) to indicate synchronous operation, or to non-zero to indicate asynchronous operation.

Because the transaction may require a response, the xo, tid, and bitmap parameters are always used and must not be null.

atp_sendrsp sends an ATP response to another socket. All response data is passed in one at_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.

fd  The ATP file descriptor to use in sending the response.

dest
    The internet address of the socket to which the response should be sent.

tid Contains the transaction identifier for this 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 field bitmap indicates the responses to be sent.

ERRORS
All routines return -1 on error with a detailed error code in errno. For additional errors returned by the underlying DDP and AppleTalk Link Access Protocol (ALAP) modules, see ddp(3) and lap(3).

[EBADF]
    fd is not a valid file descriptor (all).

[ENOTTY]
    fd is not a TTY, that is, not a special device (all).

[EINTR]
    The request was interrupted by signal (all).

[EAGAIN]
    The request failed due to a temporary resource limitation; try again. When this error occurs, no XO transaction is initiated (all).

[EINVAL]
    Invalid dest, len, resp, or retry parameter (atp_sendreq).

    Invalid len parameter (atp_getreq).

    Invalid dest or resp parameter (atp_sendrsp).

[ENOENT]
    An attempt to send a response to a nonexistent transaction (atp_sendrsp).

[ETIMEDOUT]
    The request exceeded the maximum retry count (atp_sendreq).

[EMSGSIZE]
    The response is 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 AT_ATP_DATA_SIZE bytes (atp_sendrsp).

WARNINGS
The length of each response buffer, specified in iov_len, is overwritten by the actual response length when atp_sendreq returns.

SEE ALSO
ddp(3), lap(3), nbp(3), pap(3), rtmp(3);

Inside AppleTalk.