.ds At AppleTalk
.TH ddp 3
.SH NAME
.NA ddp_open
.NA ddp_close
.TX
AppleTalk Datagram Delivery Protocol (DDP) interface
.SH SYNOPSIS
.B #include <at/appletalk.h>
.br
.B #include <at/ddp.h>
.PP
.BI int\0ddp_open(at_socket\0* socket );
.PP
.BI int\0ddp_close(int\0 sd );
.SH DESCRIPTION
.PP
The
.B ddp_open
routine
opens a static or dynamic DDP socket
and returns an \*(At socket descriptor
that can be used to read and write DDP datagrams.
.TP 8
.I socket
A pointer to the DDP socket number to open.  If the \*(At socket number is 0, or
if
.I socket
is NULL, a DDP socket is dynamically assigned.
If non-NULL, the socket number is returned in
.IR socket .
.PP
An error condition will result if there are no more dynamic DDP
sockets available, if the maximum number of open files has
been exceeded at a process or system level, or if the network
is offline.
.PP
Only the superuser can open a static DDP socket.
.PP
The
.B ddp_close
routine
closes the DDP socket identified by the \*(At socket descriptor
.IR sd .
.PP
Datagrams are always read and written with the long DDP header
format, using standard \*U
.BR read (2)
and
.BR write (2)
system calls.
If the datagram is directed to a LocalTalk\*(Tm
interface on the same network,
the DDP protocol module will send it with a short DDP header.
The long header DDP datagram is defined by the following structure
in
.BR <at/ddp.h> .
.PP
.RS
.nf
typedef struct {
        u_short     unused : 2,
                    hopcount : 4,
                    length : 10;
        u_short     checksum;
        at_net      dst_net;
        at_net      src_net;
        at_node     dst_node;
        at_node     src_node;
        at_socket   dst_socket;
        at_socket   src_socket;
        u_char      type;
        u_char      data[AT_DDP_DATA_SIZE];
} at_ddp_t;
.fi
.RE
.PP
When a datagram is written, only the fields
.IR checksum ,
.IR dst_net ,
.IR dst_node ,
.IR dst_socket ,
.IR type ,
and
.I data
need to be set.
The
.I length
field
is the DDP packet length and hop count field.
The hop count is in the 6 most significant bits of this field;
the length is in the 10 least significant bits.
.PP
The
.I checksum
field
contains the DDP checksum.
When datagrams are writen, a checksum is computed only if this
field is nonzero.
.PP
Datagrams can be sent and received asynchronously using the standard
operating system facilities:
.BR select (2N);
.BR fcntl (2)
specifying
.BR O_NDELAY ;
or
.BR FIONREAD ,
.BR FIONBIO ,
and
.B FIOASYNC
ioctls
(see
.BR ioctl (2)).
.PP
.SH ERRORS
All routines return \-1 on error with detailed error
code in
.BR errno :
.TP 20
.B [EACCES]
A nonsuperuser attempted to open a static \*(At socket
.RB ( ddp_open ).
.TP
.B [EADDRINUSE]
The static socket is in use, or all dynamic sockets
are in use
.RB ( ddp_open ).
.TP
.B [EINVAL]
An attempt was made to open
an invalid \*(At socket number
.RB ( ddp_open ).
.TP
.B [EMSGSIZE]
A datagram is too large.
.TP
.B [ENETDOWN]
The network interface is down (all).
.TP
.B [ENOBUFS]
DDP out of buffers, unable to return configuration information.
.P
Routines also
return any additional error codes returned by
the underlying LAP module
and by standard operating system calls:
.BR open (2) ,
.BR close (2) ,
.BR read (2) ,
.BR write (2) ,
and
.BR ioctl (2) .
.SH SEE ALSO
.BR close (2),
.BR fcntl (2),
.BR ioctl (2),
.BR open (2),
.BR read (2),
.BR select (2N),
.BR write (2),
.BR atp (3),
.BR ddp (3),
.BR nbp (3),
.BR pap (3),
.BR rmtp (3),
.BR fcntl (5),
.BR termio (7);
.IR "Inside AppleTalk" .