Return to 7.t CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / smm / 15.net

Annotation of 43BSDReno/share/doc/smm/15.net/7.t, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983, 1986 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted
        !             5: .\" provided that the above copyright notice and this paragraph are
        !             6: .\" duplicated in all such forms and that any documentation,
        !             7: .\" advertising materials, and other materials related to such
        !             8: .\" distribution and use acknowledge that the software was developed
        !             9: .\" by the University of California, Berkeley.  The name of the
        !            10: .\" University may not be used to endorse or promote products derived
        !            11: .\" from this software without specific prior written permission.
        !            12: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
        !            13: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
        !            14: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            15: .\"
        !            16: .\"    @(#)7.t 6.4 (Berkeley) 3/7/89
        !            17: .\"
        !            18: .nr H2 1
        !            19: .br
        !            20: .ne 30v
        !            21: .\".ds RH "Socket/protocol interface
        !            22: .NH
        !            23: \s+2Socket/protocol interface\s0
        !            24: .PP
        !            25: The interface between the socket routines and the communication
        !            26: protocols is through the \fIpr_usrreq\fP routine defined in the
        !            27: protocol switch table.  The following requests to a protocol
        !            28: module are possible:
        !            29: .DS
        !            30: ._d
        !            31: #define        PRU_ATTACH      0       /* attach protocol */
        !            32: #define        PRU_DETACH      1       /* detach protocol */
        !            33: #define        PRU_BIND        2       /* bind socket to address */
        !            34: #define        PRU_LISTEN      3       /* listen for connection */
        !            35: #define        PRU_CONNECT     4       /* establish connection to peer */
        !            36: #define        PRU_ACCEPT      5       /* accept connection from peer */
        !            37: #define        PRU_DISCONNECT  6       /* disconnect from peer */
        !            38: #define        PRU_SHUTDOWN    7       /* won't send any more data */
        !            39: #define        PRU_RCVD        8       /* have taken data; more room now */
        !            40: #define        PRU_SEND        9       /* send this data */
        !            41: #define        PRU_ABORT       10      /* abort (fast DISCONNECT, DETATCH) */
        !            42: #define        PRU_CONTROL     11      /* control operations on protocol */
        !            43: #define        PRU_SENSE       12      /* return status into m */
        !            44: #define        PRU_RCVOOB      13      /* retrieve out of band data */
        !            45: #define        PRU_SENDOOB     14      /* send out of band data */
        !            46: #define        PRU_SOCKADDR    15      /* fetch socket's address */
        !            47: #define        PRU_PEERADDR    16      /* fetch peer's address */
        !            48: #define        PRU_CONNECT2    17      /* connect two sockets */
        !            49: /* begin for protocols internal use */
        !            50: #define        PRU_FASTTIMO    18      /* 200ms timeout */
        !            51: #define        PRU_SLOWTIMO    19      /* 500ms timeout */
        !            52: #define        PRU_PROTORCV    20      /* receive from below */
        !            53: #define        PRU_PROTOSEND   21      /* send to below */
        !            54: .DE
        !            55: A call on the user request routine is of the form,
        !            56: .DS
        !            57: ._f
        !            58: error = (*protosw[].pr_usrreq)(so, req, m, addr, rights);
        !            59: int error; struct socket *so; int req; struct mbuf *m, *addr, *rights;
        !            60: .DE
        !            61: The mbuf data chain \fIm\fP is supplied for output operations
        !            62: and for certain other operations where it is to receive a result.
        !            63: The address \fIaddr\fP is supplied for address-oriented requests
        !            64: such as PRU_BIND and PRU_CONNECT.
        !            65: The \fIrights\fP parameter is an optional pointer to an mbuf
        !            66: chain containing user-specified capabilities (see the \fIsendmsg\fP
        !            67: and \fIrecvmsg\fP system calls).  The protocol is responsible for
        !            68: disposal of the data mbuf chains on output operations.
        !            69: A non-zero return value gives a
        !            70: UNIX error number which should be passed to higher level software.
        !            71: The following paragraphs describe each
        !            72: of the requests possible.
        !            73: .IP PRU_ATTACH
        !            74: .br
        !            75: When a protocol is bound to a socket (with the \fIsocket\fP
        !            76: system call) the protocol module is called with this
        !            77: request.  It is the responsibility of the protocol module to
        !            78: allocate any resources necessary.
        !            79: The ``attach'' request
        !            80: will always precede any of the other requests, and should not
        !            81: occur more than once.
        !            82: .IP PRU_DETACH
        !            83: .br
        !            84: This is the antithesis of the attach request, and is used
        !            85: at the time a socket is deleted.  The protocol module may
        !            86: deallocate any resources assigned to the socket.
        !            87: .IP PRU_BIND
        !            88: .br
        !            89: When a socket is initially created it has no address bound
        !            90: to it.  This request indicates that an address should be bound to
        !            91: an existing socket.  The protocol module must verify that the
        !            92: requested address is valid and available for use.
        !            93: .IP PRU_LISTEN
        !            94: .br
        !            95: The ``listen'' request indicates the user wishes to listen
        !            96: for incoming connection requests on the associated socket.
        !            97: The protocol module should perform any state changes needed
        !            98: to carry out this request (if possible).  A ``listen'' request
        !            99: always precedes a request to accept a connection.
        !           100: .IP PRU_CONNECT
        !           101: .br
        !           102: The ``connect'' request indicates the user wants to a establish
        !           103: an association.  The \fIaddr\fP parameter supplied describes
        !           104: the peer to be connected to.  The effect of a connect request
        !           105: may vary depending on the protocol.  Virtual circuit protocols,
        !           106: such as TCP [Postel81b], use this request to initiate establishment of a
        !           107: TCP connection.  Datagram protocols, such as UDP [Postel80], simply
        !           108: record the peer's address in a private data structure and use
        !           109: it to tag all outgoing packets.  There are no restrictions
        !           110: on how many times a connect request may be used after an attach.
        !           111: If a protocol supports the notion of \fImulti-casting\fP, it
        !           112: is possible to use multiple connects to establish a multi-cast
        !           113: group.  Alternatively, an association may be broken by a
        !           114: PRU_DISCONNECT request, and a new association created with a
        !           115: subsequent connect request; all without destroying and creating
        !           116: a new socket.
        !           117: .IP PRU_ACCEPT
        !           118: .br
        !           119: Following a successful PRU_LISTEN request and the arrival
        !           120: of one or more connections, this request is made to
        !           121: indicate the user
        !           122: has accepted the first connection on the queue of
        !           123: pending connections.  The protocol module should fill
        !           124: in the supplied address buffer with the address of the
        !           125: connected party.
        !           126: .IP PRU_DISCONNECT
        !           127: .br
        !           128: Eliminate an association created with a PRU_CONNECT request.
        !           129: .IP PRU_SHUTDOWN
        !           130: .br
        !           131: This call is used to indicate no more data will be sent and/or
        !           132: received (the \fIaddr\fP parameter indicates the direction of
        !           133: the shutdown, as encoded in the \fIsoshutdown\fP system call).
        !           134: The protocol may, at its discretion, deallocate any data
        !           135: structures related to the shutdown and/or notify a connected peer
        !           136: of the shutdown.
        !           137: .IP PRU_RCVD
        !           138: .br
        !           139: This request is made only if the protocol entry in the protocol
        !           140: switch table includes the PR_WANTRCVD flag.
        !           141: When a user removes data from the receive queue this request
        !           142: will be sent to the protocol module.  It may be used to trigger
        !           143: acknowledgements, refresh windowing information, initiate
        !           144: data transfer, etc.
        !           145: .IP PRU_SEND
        !           146: .br
        !           147: Each user request to send data is translated into one or more
        !           148: PRU_SEND requests (a protocol may indicate that a single user
        !           149: send request must be translated into a single PRU_SEND request by
        !           150: specifying the PR_ATOMIC flag in its protocol description).
        !           151: The data to be sent is presented to the protocol as a list of
        !           152: mbufs and an address is, optionally, supplied in the \fIaddr\fP
        !           153: parameter.  The protocol is responsible for preserving the data
        !           154: in the socket's send queue if it is not able to send it immediately,
        !           155: or if it may need it at some later time (e.g. for retransmission).
        !           156: .IP PRU_ABORT
        !           157: .br
        !           158: This request indicates an abnormal termination of service.  The
        !           159: protocol should delete any existing association(s).
        !           160: .IP PRU_CONTROL
        !           161: .br
        !           162: The ``control'' request is generated when a user performs a
        !           163: UNIX \fIioctl\fP system call on a socket (and the ioctl is not
        !           164: intercepted by the socket routines).  It allows protocol-specific
        !           165: operations to be provided outside the scope of the common socket
        !           166: interface.  The \fIaddr\fP parameter contains a pointer to a static
        !           167: kernel data area where relevant information may be obtained or returned.
        !           168: The \fIm\fP parameter contains the actual \fIioctl\fP request code
        !           169: (note the non-standard calling convention).
        !           170: The \fIrights\fP parameter contains a pointer to an \fIifnet\fP structure
        !           171: if the \fIioctl\fP operation pertains to a particular network interface.
        !           172: .IP PRU_SENSE
        !           173: .br
        !           174: The ``sense'' request is generated when the user makes an \fIfstat\fP
        !           175: system call on a socket; it requests status of the associated socket. 
        !           176: This currently returns a standard \fIstat\fP structure.
        !           177: It typically contains only the
        !           178: optimal transfer size for the connection (based on buffer size,
        !           179: windowing information and maximum packet size).
        !           180: The \fIm\fP parameter contains a pointer
        !           181: to a static kernel data area where the status buffer should be placed.
        !           182: .IP PRU_RCVOOB
        !           183: .br
        !           184: Any ``out-of-band'' data presently available is to be returned.  An
        !           185: mbuf is passed to the protocol module, and the protocol
        !           186: should either place
        !           187: data in the mbuf or attach new mbufs to the one supplied if there is
        !           188: insufficient space in the single mbuf.
        !           189: An error may be returned if out-of-band data is not (yet) available
        !           190: or has already been consumed.
        !           191: The \fIaddr\fP parameter contains any options such as MSG_PEEK
        !           192: to examine data without consuming it.
        !           193: .IP PRU_SENDOOB
        !           194: .br
        !           195: Like PRU_SEND, but for out-of-band data.
        !           196: .IP PRU_SOCKADDR
        !           197: .br
        !           198: The local address of the socket is returned, if any is currently
        !           199: bound to it.  The address (with protocol specific format) is returned
        !           200: in the \fIaddr\fP parameter.
        !           201: .IP PRU_PEERADDR
        !           202: .br
        !           203: The address of the peer to which the socket is connected is returned.
        !           204: The socket must be in a SS_ISCONNECTED state for this request to
        !           205: be made to the protocol.  The address format (protocol specific) is
        !           206: returned in the \fIaddr\fP parameter.
        !           207: .IP PRU_CONNECT2
        !           208: .br
        !           209: The protocol module is supplied two sockets and requested to
        !           210: establish a connection between the two without binding any
        !           211: addresses, if possible.  This call is used in implementing
        !           212: the
        !           213: .IR socketpair (2)
        !           214: system call.
        !           215: .PP
        !           216: The following requests are used internally by the protocol modules
        !           217: and are never generated by the socket routines.  In certain instances,
        !           218: they are handed to the \fIpr_usrreq\fP routine solely for convenience
        !           219: in tracing a protocol's operation (e.g. PRU_SLOWTIMO).
        !           220: .IP PRU_FASTTIMO
        !           221: .br
        !           222: A ``fast timeout'' has occurred.  This request is made when a timeout
        !           223: occurs in the protocol's \fIpr_fastimo\fP routine.  The \fIaddr\fP
        !           224: parameter indicates which timer expired.
        !           225: .IP PRU_SLOWTIMO
        !           226: .br
        !           227: A ``slow timeout'' has occurred.  This request is made when a timeout
        !           228: occurs in the protocol's \fIpr_slowtimo\fP routine.  The \fIaddr\fP
        !           229: parameter indicates which timer expired.
        !           230: .IP PRU_PROTORCV
        !           231: .br
        !           232: This request is used in the protocol-protocol interface, not by the
        !           233: routines.  It requests reception of data destined for the protocol and
        !           234: not the user.  No protocols currently use this facility.
        !           235: .IP PRU_PROTOSEND
        !           236: .br
        !           237: This request allows a protocol to send data destined for another
        !           238: protocol module, not a user.  The details of how data is marked
        !           239: ``addressed to protocol'' instead of ``addressed to user'' are
        !           240: left to the protocol modules.  No protocols currently use this facility.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.