Return to 2.3.t CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 06.sysman

Annotation of 43BSDReno/share/doc/ps1/06.sysman/2.3.t, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)2.3.t       6.3 (Berkeley) 5/12/86
        !             6: .\"
        !             7: .sh "Interprocess communications
        !             8: .NH 3
        !             9: Interprocess communication primitives
        !            10: .NH 4
        !            11: Communication domains
        !            12: .PP
        !            13: The system provides access to an extensible set of 
        !            14: communication \fIdomains\fP.  A communication domain
        !            15: is identified by a manifest constant defined in the
        !            16: file \fI<sys/socket.h>\fP.
        !            17: Important standard domains supported by the system are the ``unix''
        !            18: domain, AF_UNIX, for communication within the system, the ``Internet''
        !            19: domain for communication in the DARPA Internet, AF_INET,
        !            20: and the ``NS'' domain, AF_NS, for communication
        !            21: using the Xerox Network Systems protocols.
        !            22: Other domains can be added to the system.
        !            23: .NH 4
        !            24: Socket types and protocols
        !            25: .PP
        !            26: Within a domain, communication takes place between communication endpoints
        !            27: known as \fIsockets\fP.  Each socket has the potential to exchange
        !            28: information with other sockets of an appropriate type within the domain.
        !            29: .PP
        !            30: Each socket has an associated
        !            31: abstract type, which describes the semantics of communication using that
        !            32: socket.  Properties such as reliability, ordering, and prevention
        !            33: of duplication of messages are determined by the type.
        !            34: The basic set of socket types is defined in \fI<sys/socket.h>\fP:
        !            35: .DS
        !            36: /* Standard socket types */
        !            37: ._d
        !            38: #define        SOCK_DGRAM      1       /* datagram */
        !            39: #define        SOCK_STREAM     2       /* virtual circuit */
        !            40: #define        SOCK_RAW        3       /* raw socket */
        !            41: #define        SOCK_RDM        4       /* reliably-delivered message */
        !            42: #define        SOCK_SEQPACKET  5       /* sequenced packets */
        !            43: .DE
        !            44: The SOCK_DGRAM type models the semantics of datagrams in network communication:
        !            45: messages may be lost or duplicated and may arrive out-of-order.
        !            46: A datagram socket may send messages to and receive messages from multiple
        !            47: peers.
        !            48: The SOCK_RDM type models the semantics of reliable datagrams: messages
        !            49: arrive unduplicated and in-order, the sender is notified if
        !            50: messages are lost.
        !            51: The \fIsend\fP and \fIreceive\fP operations (described below)
        !            52: generate reliable/unreliable datagrams.
        !            53: The SOCK_STREAM type models connection-based virtual circuits: two-way
        !            54: byte streams with no record boundaries.
        !            55: Connection setup is required before data communication may begin.
        !            56: The SOCK_SEQPACKET type models a connection-based,
        !            57: full-duplex, reliable, sequenced packet exchange;
        !            58: the sender is notified if messages are lost, and messages are never
        !            59: duplicated or presented out-of-order.
        !            60: Users of the last two abstractions may use the facilities for
        !            61: out-of-band transmission to send out-of-band data.
        !            62: .PP
        !            63: SOCK_RAW is used for unprocessed access to internal network layers
        !            64: and interfaces; it has no specific semantics.
        !            65: .PP
        !            66: Other socket types can be defined.
        !            67: .PP
        !            68: Each socket may have a specific \fIprotocol\fP associated with it.
        !            69: This protocol is used within the domain to provide the semantics
        !            70: required by the socket type.
        !            71: Not all socket types are supported by each domain;
        !            72: support depends on the existence and the implementation
        !            73: of a suitable protocol within the domain.
        !            74: For example, within the ``Internet'' domain, the SOCK_DGRAM type may be
        !            75: implemented by the UDP user datagram protocol, and the SOCK_STREAM
        !            76: type may be implemented by the TCP transmission control protocol, while
        !            77: no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets exist.
        !            78: .NH 4
        !            79: Socket creation, naming and service establishment
        !            80: .PP
        !            81: Sockets may be \fIconnected\fP or \fIunconnected\fP.  An unconnected
        !            82: socket descriptor is obtained by the \fIsocket\fP call:
        !            83: .DS
        !            84: s = socket(domain, type, protocol);
        !            85: result int s; int domain, type, protocol;
        !            86: .DE
        !            87: The socket domain and type are as described above,
        !            88: and are specified using the definitions from \fI<sys/socket.h>\fP.
        !            89: The protocol may be given as 0, meaning any suitable protocol.
        !            90: One of several possible protocols may be selected using identifiers
        !            91: obtained from a library routine, \fIgetprotobyname\fP.
        !            92: .PP
        !            93: An unconnected socket descriptor of a connection-oriented type
        !            94: may yield a connected socket descriptor
        !            95: in one of two ways: either by actively connecting to another socket,
        !            96: or by becoming associated with a name in the communications domain and
        !            97: \fIaccepting\fP a connection from another socket.
        !            98: Datagram sockets need not establish connections before use.
        !            99: .PP
        !           100: To accept connections or to receive datagrams,
        !           101: a socket must first have a binding
        !           102: to a name (or address) within the communications domain.
        !           103: Such a binding may be established by a \fIbind\fP call:
        !           104: .DS
        !           105: bind(s, name, namelen);
        !           106: int s; struct sockaddr *name; int namelen;
        !           107: .DE
        !           108: Datagram sockets may have default bindings established when first
        !           109: sending data if not explicitly bound earlier.
        !           110: In either case,
        !           111: a socket's bound name may be retrieved with a \fIgetsockname\fP call:
        !           112: .DS
        !           113: getsockname(s, name, namelen);
        !           114: int s; result struct sockaddr *name; result int *namelen;
        !           115: .DE
        !           116: while the peer's name can be retrieved with \fIgetpeername\fP:
        !           117: .DS
        !           118: getpeername(s, name, namelen);
        !           119: int s; result struct sockaddr *name; result int *namelen;
        !           120: .DE
        !           121: Domains may support sockets with several names.
        !           122: .NH 4
        !           123: Accepting connections
        !           124: .PP
        !           125: Once a binding is made to a connection-oriented socket,
        !           126: it is possible to \fIlisten\fP for connections:
        !           127: .DS
        !           128: listen(s, backlog);
        !           129: int s, backlog;
        !           130: .DE
        !           131: The \fIbacklog\fP specifies the maximum count of connections
        !           132: that can be simultaneously queued awaiting acceptance.
        !           133: .PP
        !           134: An \fIaccept\fP call:
        !           135: .DS
        !           136: t = accept(s, name, anamelen);
        !           137: result int t; int s; result struct sockaddr *name; result int *anamelen;
        !           138: .DE
        !           139: returns a descriptor for a new, connected, socket
        !           140: from the queue of pending connections on \fIs\fP.
        !           141: If no new connections are queued for acceptance,
        !           142: the call will wait for a connection unless non-blocking I/O has been enabled.
        !           143: .NH 4
        !           144: Making connections
        !           145: .PP
        !           146: An active connection to a named socket is made by the \fIconnect\fP call:
        !           147: .DS
        !           148: connect(s, name, namelen);
        !           149: int s; struct sockaddr *name; int namelen;
        !           150: .DE
        !           151: Although datagram sockets do not establish connections,
        !           152: the \fIconnect\fP call may be used with such sockets
        !           153: to create an \fIassociation\fP with the foreign address.
        !           154: The address is recorded for use in future \fIsend\fP calls,
        !           155: which then need not supply destination addresses.
        !           156: Datagrams will be received only from that peer,
        !           157: and asynchronous error reports may be received.
        !           158: .PP
        !           159: It is also possible to create connected pairs of sockets without
        !           160: using the domain's name space to rendezvous; this is done with the
        !           161: \fIsocketpair\fP call\(dg:
        !           162: .FS
        !           163: \(dg 4.3BSD supports \fIsocketpair\fP creation only in the ``unix''
        !           164: communication domain.
        !           165: .FE
        !           166: .DS
        !           167: socketpair(domain, type, protocol, sv);
        !           168: int domain, type, protocol; result int sv[2];
        !           169: .DE
        !           170: Here the returned \fIsv\fP descriptors correspond to those obtained with
        !           171: \fIaccept\fP and \fIconnect\fP.
        !           172: .PP
        !           173: The call
        !           174: .DS
        !           175: pipe(pv)
        !           176: result int pv[2];
        !           177: .DE
        !           178: creates a pair of SOCK_STREAM sockets in the UNIX domain,
        !           179: with pv[0] only writable and pv[1] only readable.
        !           180: .NH 4
        !           181: Sending and receiving data
        !           182: .PP
        !           183: Messages may be sent from a socket by:
        !           184: .DS
        !           185: cc = sendto(s, buf, len, flags, to, tolen);
        !           186: result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen;
        !           187: .DE
        !           188: if the socket is not connected or:
        !           189: .DS
        !           190: cc = send(s, buf, len, flags);
        !           191: result int cc; int s; caddr_t buf; int len, flags;
        !           192: .DE
        !           193: if the socket is connected.
        !           194: The corresponding receive primitives are:
        !           195: .DS
        !           196: msglen = recvfrom(s, buf, len, flags, from, fromlenaddr);
        !           197: result int msglen; int s; result caddr_t buf; int len, flags;
        !           198: result caddr_t from; result int *fromlenaddr;
        !           199: .DE
        !           200: and
        !           201: .DS
        !           202: msglen = recv(s, buf, len, flags);
        !           203: result int msglen; int s; result caddr_t buf; int len, flags;
        !           204: .DE
        !           205: .PP
        !           206: In the unconnected case,
        !           207: the parameters \fIto\fP and \fItolen\fP
        !           208: specify the destination or source of the message, while
        !           209: the \fIfrom\fP parameter stores the source of the message,
        !           210: and \fI*fromlenaddr\fP initially gives the size of the \fIfrom\fP
        !           211: buffer and is updated to reflect the true length of the \fIfrom\fP
        !           212: address.
        !           213: .PP
        !           214: All calls cause the message to be received in or sent from
        !           215: the message buffer of length \fIlen\fP bytes, starting at address \fIbuf\fP.
        !           216: The \fIflags\fP specify
        !           217: peeking at a message without reading it or sending or receiving
        !           218: high-priority out-of-band messages, as follows:
        !           219: .DS
        !           220: ._d
        !           221: #define        MSG_PEEK        0x1     /* peek at incoming message */
        !           222: #define        MSG_OOB 0x2     /* process out-of-band data */
        !           223: .DE
        !           224: .NH 4
        !           225: Scatter/gather and exchanging access rights
        !           226: .PP
        !           227: It is possible scatter and gather data and to exchange access rights
        !           228: with messages.  When either of these operations is involved,
        !           229: the number of parameters to the call becomes large.
        !           230: Thus the system defines a message header structure, in \fI<sys/socket.h>\fP,
        !           231: which can be
        !           232: used to conveniently contain the parameters to the calls:
        !           233: .DS
        !           234: .if t .ta .5i 1.25i 2i 2.7i
        !           235: .if n ._f
        !           236: struct msghdr {
        !           237:        caddr_t msg_name;               /* optional address */
        !           238:        int     msg_namelen;    /* size of address */
        !           239:        struct  iov *msg_iov;   /* scatter/gather array */
        !           240:        int     msg_iovlen;             /* # elements in msg_iov */
        !           241:        caddr_t msg_accrights;  /* access rights sent/received */
        !           242:        int     msg_accrightslen;       /* size of msg_accrights */
        !           243: };
        !           244: .DE
        !           245: Here \fImsg_name\fP and \fImsg_namelen\fP specify the source or destination
        !           246: address if the socket is unconnected; \fImsg_name\fP may be given as
        !           247: a null pointer if no names are desired or required.
        !           248: The \fImsg_iov\fP and \fImsg_iovlen\fP describe the scatter/gather
        !           249: locations, as described in section 2.1.3.
        !           250: Access rights to be sent along with the message are specified
        !           251: in \fImsg_accrights\fP, which has length \fImsg_accrightslen\fP.
        !           252: In the ``unix'' domain these are an array of integer descriptors,
        !           253: taken from the sending process and duplicated in the receiver.
        !           254: .PP
        !           255: This structure is used in the operations \fIsendmsg\fP and \fIrecvmsg\fP:
        !           256: .DS
        !           257: sendmsg(s, msg, flags);
        !           258: int s; struct msghdr *msg; int flags;
        !           259: 
        !           260: msglen = recvmsg(s, msg, flags);
        !           261: result int msglen; int s; result struct msghdr *msg; int flags;
        !           262: .DE
        !           263: .NH 4
        !           264: Using read and write with sockets
        !           265: .PP
        !           266: The normal UNIX \fIread\fP and \fIwrite\fP calls may be
        !           267: applied to connected sockets and translated into \fIsend\fP and \fIreceive\fP
        !           268: calls from or to a single area of memory and discarding any rights
        !           269: received.  A process may operate on a virtual circuit socket, a terminal
        !           270: or a file with blocking or non-blocking input/output
        !           271: operations without distinguishing the descriptor type.
        !           272: .NH 4
        !           273: Shutting down halves of full-duplex connections
        !           274: .PP
        !           275: A process that has a full-duplex socket such as a virtual circuit
        !           276: and no longer wishes to read from or write to this socket can
        !           277: give the call:
        !           278: .DS
        !           279: shutdown(s, direction);
        !           280: int s, direction;
        !           281: .DE
        !           282: where \fIdirection\fP is 0 to not read further, 1 to not
        !           283: write further, or 2 to completely shut the connection down.
        !           284: If the underlying protocol supports unidirectional or bidirectional shutdown,
        !           285: this indication will be passed to the peer.
        !           286: For example, a shutdown for writing might produce an end-of-file
        !           287: condition at the remote end.
        !           288: .NH 4
        !           289: Socket and protocol options
        !           290: .PP
        !           291: Sockets, and their underlying communication protocols, may
        !           292: support \fIoptions\fP.  These options may be used to manipulate
        !           293: implementation- or protocol-specific facilities. 
        !           294: The \fIgetsockopt\fP
        !           295: and \fIsetsockopt\fP calls are used to control options:
        !           296: .DS
        !           297: getsockopt(s, level, optname, optval, optlen)
        !           298: int s, level, optname; result caddr_t optval; result int *optlen;
        !           299: 
        !           300: setsockopt(s, level, optname, optval, optlen)
        !           301: int s, level, optname; caddr_t optval; int optlen;
        !           302: .DE
        !           303: The option \fIoptname\fP is interpreted at the indicated
        !           304: protocol \fIlevel\fP for socket \fIs\fP.  If a value is specified
        !           305: with \fIoptval\fP and \fIoptlen\fP, it is interpreted by
        !           306: the software operating at the specified \fIlevel\fP.  The \fIlevel\fP
        !           307: SOL_SOCKET is reserved to indicate options maintained
        !           308: by the socket facilities.  Other \fIlevel\fP values indicate
        !           309: a particular protocol which is to act on the option request;
        !           310: these values are normally interpreted as a ``protocol number''.
        !           311: .NH 3
        !           312: UNIX domain
        !           313: .PP
        !           314: This section describes briefly the properties of the UNIX communications
        !           315: domain.
        !           316: .NH 4
        !           317: Types of sockets
        !           318: .PP
        !           319: In the UNIX domain,
        !           320: the SOCK_STREAM abstraction provides pipe-like
        !           321: facilities, while SOCK_DGRAM provides (usually)
        !           322: reliable message-style communications.
        !           323: .NH 4
        !           324: Naming
        !           325: .PP
        !           326: Socket names are strings and may appear in the UNIX file
        !           327: system name space through portals\(dg.
        !           328: .FS
        !           329: \(dg The 4.3BSD implementation of the UNIX domain embeds
        !           330: bound sockets in the UNIX file system name space;
        !           331: this may change in future releases.
        !           332: .FE
        !           333: .NH 4
        !           334: Access rights transmission
        !           335: .PP
        !           336: The ability to pass UNIX descriptors with messages in this domain
        !           337: allows migration of service within the system and allows
        !           338: user processes to be used in building system facilities.
        !           339: .NH 3
        !           340: INTERNET domain
        !           341: .PP
        !           342: This section describes briefly how the Internet domain is
        !           343: mapped to the model described in this section.  More
        !           344: information will be found in the document describing the
        !           345: network implementation in 4.3BSD.
        !           346: .NH 4
        !           347: Socket types and protocols
        !           348: .PP
        !           349: SOCK_STREAM is supported by the Internet TCP protocol;
        !           350: SOCK_DGRAM by the UDP protocol.
        !           351: Each is layered atop the transport-level Internet Protocol (IP).
        !           352: The Internet Control Message Protocol is implemented atop/beside IP
        !           353: and is accessible via a raw socket.
        !           354: The SOCK_SEQPACKET
        !           355: has no direct Internet family analogue; a protocol
        !           356: based on one from the XEROX NS family and layered on
        !           357: top of IP could be implemented to fill this gap.
        !           358: .NH 4
        !           359: Socket naming
        !           360: .PP
        !           361: Sockets in the Internet domain have names composed of the 32 bit
        !           362: Internet address, and a 16 bit port number.
        !           363: Options may be used to
        !           364: provide IP source routing or security options.
        !           365: The 32-bit address is composed of network and host parts;
        !           366: the network part is variable in size and is frequency encoded.
        !           367: The host part may optionally be interpreted as a subnet field
        !           368: plus the host on subnet; this is is enabled by setting a network address
        !           369: mask at boot time.
        !           370: .NH 4
        !           371: Access rights transmission
        !           372: .PP
        !           373: No access rights transmission facilities are provided in the Internet domain.
        !           374: .NH 4
        !           375: Raw access
        !           376: .PP
        !           377: The Internet domain allows the super-user access to the raw facilities
        !           378: of IP.
        !           379: These interfaces are modeled as SOCK_RAW sockets.
        !           380: Each raw socket is associated with one IP protocol number,
        !           381: and receives all traffic received for that protocol.
        !           382: This allows administrative and debugging
        !           383: functions to occur,
        !           384: and enables user-level implementations of special-purpose protocols
        !           385: such as inter-gateway routing protocols.

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