| .\" This man page is Copyright (C) 1998 Alan Cox. |
| .\" |
| .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
| .\" Permission is granted to distribute possibly modified copies |
| .\" of this page provided the header is included verbatim, |
| .\" and in case of nontrivial modification author and date |
| .\" of the modification is added to the header. |
| .\" %%%LICENSE_END |
| .\" |
| .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ |
| .\" |
| .TH DDP 7 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ddp \- Linux AppleTalk protocol implementation |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/socket.h> |
| .B #include <netatalk/at.h> |
| .PP |
| .IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" |
| .IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" |
| .fi |
| .SH DESCRIPTION |
| Linux implements the AppleTalk protocols described in |
| .IR "Inside AppleTalk" . |
| Only the DDP layer and AARP are present in |
| the kernel. |
| They are designed to be used via the |
| .B netatalk |
| protocol |
| libraries. |
| This page documents the interface for those who wish or need to |
| use the DDP layer directly. |
| .PP |
| The communication between AppleTalk and the user program works using a |
| BSD-compatible socket interface. |
| For more information on sockets, see |
| .BR socket (7). |
| .PP |
| An AppleTalk socket is created by calling the |
| .BR socket (2) |
| function with a |
| .B AF_APPLETALK |
| socket family argument. |
| Valid socket types are |
| .B SOCK_DGRAM |
| to open a |
| .B ddp |
| socket or |
| .B SOCK_RAW |
| to open a |
| .B raw |
| socket. |
| .I protocol |
| is the AppleTalk protocol to be received or sent. |
| For |
| .B SOCK_RAW |
| you must specify |
| .BR ATPROTO_DDP . |
| .PP |
| Raw sockets may be opened only by a process with effective user ID 0 |
| or when the process has the |
| .B CAP_NET_RAW |
| capability. |
| .SS Address format |
| An AppleTalk socket address is defined as a combination of a network number, |
| a node number, and a port number. |
| .PP |
| .in +4n |
| .EX |
| struct at_addr { |
| unsigned short s_net; |
| unsigned char s_node; |
| }; |
| |
| struct sockaddr_atalk { |
| sa_family_t sat_family; /* address family */ |
| unsigned char sat_port; /* port */ |
| struct at_addr sat_addr; /* net/node */ |
| }; |
| .EE |
| .in |
| .PP |
| .I sat_family |
| is always set to |
| .BR AF_APPLETALK . |
| .I sat_port |
| contains the port. |
| The port numbers below 129 are known as |
| .IR "reserved ports" . |
| Only processes with the effective user ID 0 or the |
| .B CAP_NET_BIND_SERVICE |
| capability may |
| .BR bind (2) |
| to these sockets. |
| .I sat_addr |
| is the host address. |
| The |
| .I net |
| member of |
| .I struct at_addr |
| contains the host network in network byte order. |
| The value of |
| .B AT_ANYNET |
| is a |
| wildcard and also implies \(lqthis network.\(rq |
| The |
| .I node |
| member of |
| .I struct at_addr |
| contains the host node number. |
| The value of |
| .B AT_ANYNODE |
| is a |
| wildcard and also implies \(lqthis node.\(rq The value of |
| .B ATADDR_BCAST |
| is a link |
| local broadcast address. |
| .\" FIXME . this doesn't make sense [johnl] |
| .SS Socket options |
| No protocol-specific socket options are supported. |
| .SS /proc interfaces |
| IP supports a set of |
| .I /proc |
| interfaces to configure some global AppleTalk parameters. |
| The parameters can be accessed by reading or writing files in the directory |
| .IR /proc/sys/net/atalk/ . |
| .TP |
| .I aarp\-expiry\-time |
| The time interval (in seconds) before an AARP cache entry expires. |
| .TP |
| .I aarp\-resolve\-time |
| The time interval (in seconds) before an AARP cache entry is resolved. |
| .TP |
| .I aarp\-retransmit\-limit |
| The number of retransmissions of an AARP query before the node is declared |
| dead. |
| .TP |
| .I aarp\-tick\-time |
| The timer rate (in seconds) for the timer driving AARP. |
| .PP |
| The default values match the specification and should never need to be |
| changed. |
| .SS Ioctls |
| All ioctls described in |
| .BR socket (7) |
| apply to DDP. |
| .\" FIXME . Add a section about multicasting |
| .SH ERRORS |
| .TP |
| .B EACCES |
| The user tried to execute an operation without the necessary permissions. |
| These include sending to a broadcast address without |
| having the broadcast flag set, |
| and trying to bind to a reserved port without effective user ID 0 or |
| .BR CAP_NET_BIND_SERVICE . |
| .TP |
| .B EADDRINUSE |
| Tried to bind to an address already in use. |
| .TP |
| .B EADDRNOTAVAIL |
| A nonexistent interface was requested or the requested source address was |
| not local. |
| .TP |
| .B EAGAIN |
| Operation on a nonblocking socket would block. |
| .TP |
| .B EALREADY |
| A connection operation on a nonblocking socket is already in progress. |
| .TP |
| .B ECONNABORTED |
| A connection was closed during an |
| .BR accept (2). |
| .TP |
| .B EHOSTUNREACH |
| No routing table entry matches the destination address. |
| .TP |
| .B EINVAL |
| Invalid argument passed. |
| .TP |
| .B EISCONN |
| .BR connect (2) |
| was called on an already connected socket. |
| .TP |
| .B EMSGSIZE |
| Datagram is bigger than the DDP MTU. |
| .TP |
| .B ENODEV |
| Network device not available or not capable of sending IP. |
| .TP |
| .B ENOENT |
| .B SIOCGSTAMP |
| was called on a socket where no packet arrived. |
| .TP |
| .BR ENOMEM " and " ENOBUFS |
| Not enough memory available. |
| .TP |
| .B ENOPKG |
| A kernel subsystem was not configured. |
| .TP |
| .BR ENOPROTOOPT " and " EOPNOTSUPP |
| Invalid socket option passed. |
| .TP |
| .B ENOTCONN |
| The operation is defined only on a connected socket, but the socket wasn't |
| connected. |
| .TP |
| .B EPERM |
| User doesn't have permission to set high priority, |
| make a configuration change, |
| or send signals to the requested process or group. |
| .TP |
| .B EPIPE |
| The connection was unexpectedly closed or shut down by the other end. |
| .TP |
| .B ESOCKTNOSUPPORT |
| The socket was unconfigured, or an unknown socket type was requested. |
| .SH VERSIONS |
| AppleTalk is supported by Linux 2.0 or higher. |
| The |
| .I /proc |
| interfaces exist since Linux 2.2. |
| .SH NOTES |
| Be very careful with the |
| .B SO_BROADCAST |
| option; it is not privileged in Linux. |
| It is easy to overload the network |
| with careless sending to broadcast addresses. |
| .SS Compatibility |
| The basic AppleTalk socket interface is compatible with |
| .B netatalk |
| on BSD-derived systems. |
| Many BSD systems fail to check |
| .B SO_BROADCAST |
| when sending broadcast frames; this can lead to compatibility problems. |
| .PP |
| The |
| raw |
| socket mode is unique to Linux and exists to support the alternative CAP |
| package and AppleTalk monitoring tools more easily. |
| .SH BUGS |
| There are too many inconsistent error values. |
| .PP |
| The ioctls used to configure routing tables, devices, |
| AARP tables, and other devices are not yet described. |
| .SH SEE ALSO |
| .BR recvmsg (2), |
| .BR sendmsg (2), |
| .BR capabilities (7), |
| .BR socket (7) |