share/doc/smm/18.net/8.t

   1 .\" Copyright (c) 1983, 1986, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)8.t 8.1 (Berkeley) 6/8/93
  33 .\"
  34 .nr H2 1
  35 .\".ds RH "Protocol/protocol interface
  36 .br
  37 .ne 2i
  38 .NH
  39 \s+2Protocol/protocol interface\s0
  40 .PP
  41 The interface between protocol modules is through the \fIpr_usrreq\fP,
  42 \fIpr_input\fP, \fIpr_output\fP, \fIpr_ctlinput\fP, and
  43 \fIpr_ctloutput\fP routines.  The calling conventions for all
  44 but the \fIpr_usrreq\fP routine are expected to be specific to
  45 the protocol
  46 modules and are not guaranteed to be consistent across protocol
  47 families.  We
  48 will examine the conventions used for some of the Internet
  49 protocols in this section as an example.
  50 .NH 2
  51 pr_output
  52 .PP
  53 The Internet protocol UDP uses the convention,
  54 .DS
  55 error = udp_output(inp, m);
  56 int error; struct inpcb *inp; struct mbuf *m;
  57 .DE
  58 where the \fIinp\fP, ``\fIin\fP\^ternet
  59 \fIp\fP\^rotocol \fIc\fP\^ontrol \fIb\fP\^lock'',
  60 passed between modules conveys per connection state information, and
  61 the mbuf chain contains the data to be sent.  UDP
  62 performs consistency checks, appends its header, calculates a
  63 checksum, etc. before passing the packet on.
  64 UDP is based on the Internet Protocol, IP [Postel81a], as its transport.
  65 UDP passes a packet to the IP module for output as follows:
  66 .DS
  67 error = ip_output(m, opt, ro, flags);
  68 int error; struct mbuf *m, *opt; struct route *ro; int flags;
  69 .DE
  70 .PP
  71 The call to IP's output routine is more complicated than that for
  72 UDP, as befits the additional work the IP module must do.
  73 The \fIm\fP parameter is the data to be sent, and the \fIopt\fP
  74 parameter is an optional list of IP options which should
  75 be placed in the IP packet header.  The \fIro\fP parameter is
  76 is used in making routing decisions (and passing them back to the
  77 caller for use in subsequent calls).  The
  78 final parameter, \fIflags\fP contains flags indicating whether the
  79 user is allowed to transmit a broadcast packet
  80 and if routing is to be performed.  The broadcast flag may
  81 be inconsequential if the underlying hardware does not support the
  82 notion of broadcasting.
  83 .PP
  84 All output routines return 0 on success and a UNIX error number
  85 if a failure occurred which could be detected immediately
  86 (no buffer space available, no route to destination, etc.).
  87 .NH 2
  88 pr_input
  89 .PP
  90 Both UDP and TCP use the following calling convention,
  91 .DS
  92 (void) (*protosw[].pr_input)(m, ifp);
  93 struct mbuf *m; struct ifnet *ifp;
  94 .DE
  95 Each mbuf list passed is a single packet to be processed by
  96 the protocol module.
  97 The interface from which the packet was received is passed as the second
  98 parameter.
  99 .PP
 100 The IP input routine is a VAX software interrupt level routine,
 101 and so is not called with any parameters.  It instead communicates
 102 with network interfaces through a queue, \fIipintrq\fP, which is
 103 identical in structure to the queues used by the network interfaces
 104 for storing packets awaiting transmission.
 105 The software interrupt is enabled by the network interfaces
 106 when they place input data on the input queue.
 107 .NH 2
 108 pr_ctlinput
 109 .PP
 110 This routine is used to convey ``control'' information to a
 111 protocol module (i.e. information which might be passed to the
 112 user, but is not data).
 113 .PP
 114 The common calling convention for this routine is,
 115 .DS
 116 (void) (*protosw[].pr_ctlinput)(req, addr);
 117 int req; struct sockaddr *addr;
 118 .DE
 119 The \fIreq\fP parameter is one of the following,
 120 .DS
 121 .ta \w'#define  'u +\w'PRC_UNREACH_NEEDFRAG   'u +8n
 122 #define PRC_IFDOWN      0       /* interface transition */
 123 #define PRC_ROUTEDEAD   1       /* select new route if possible */
 124 #define PRC_QUENCH      4       /* some said to slow down */
 125 #define PRC_MSGSIZE     5       /* message size forced drop */
 126 #define PRC_HOSTDEAD    6       /* normally from IMP */
 127 #define PRC_HOSTUNREACH 7       /* ditto */
 128 #define PRC_UNREACH_NET 8       /* no route to network */
 129 #define PRC_UNREACH_HOST        9       /* no route to host */
 130 #define PRC_UNREACH_PROTOCOL    10      /* dst says bad protocol */
 131 #define PRC_UNREACH_PORT        11      /* bad port # */
 132 #define PRC_UNREACH_NEEDFRAG    12      /* IP_DF caused drop */
 133 #define PRC_UNREACH_SRCFAIL     13      /* source route failed */
 134 #define PRC_REDIRECT_NET        14      /* net routing redirect */
 135 #define PRC_REDIRECT_HOST       15      /* host routing redirect */
 136 #define PRC_REDIRECT_TOSNET     14      /* redirect for type of service & net */
 137 #define PRC_REDIRECT_TOSHOST    15      /* redirect for tos & host */
 138 #define PRC_TIMXCEED_INTRANS    18      /* packet lifetime expired in transit */
 139 #define PRC_TIMXCEED_REASS      19      /* lifetime expired on reass q */
 140 #define PRC_PARAMPROB   20      /* header incorrect */
 141 .DE
 142 while the \fIaddr\fP parameter is the address to which the condition applies.
 143 Many of the requests have obviously been
 144 derived from ICMP (the Internet Control Message Protocol [Postel81c]),
 145 and from error messages defined in the 1822 host/IMP convention
 146 [BBN78].  Mapping tables exist to convert
 147 control requests to UNIX error codes which are delivered
 148 to a user.
 149 .NH 2
 150 pr_ctloutput
 151 .PP
 152 This is the routine that implements per-socket options at the protocol
 153 level for \fIgetsockopt\fP and \fIsetsockopt\fP.
 154 The calling convention is,
 155 .DS
 156 error = (*protosw[].pr_ctloutput)(op, so, level, optname, mp);
 157 int op; struct socket *so; int level, optname; struct mbuf **mp;
 158 .DE
 159 where \fIop\fP is one of PRCO_SETOPT or PRCO_GETOPT,
 160 \fIso\fP is the socket from whence the call originated,
 161 and \fIlevel\fP and \fIoptname\fP are the protocol level and option name
 162 supplied by the user.
 163 The results of a PRCO_GETOPT call are returned in an mbuf whose address
 164 is placed in \fImp\fP before return.
 165 On a PRCO_SETOPT call, \fImp\fP contains the address of an mbuf
 166 containing the option data; the mbuf should be freed before return.