Return to socket.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/socket.2, revision 1.1

1.1     ! root        1: .TH SOCKET 2 "18 July 1983"
        !             2: .UC 4
        !             3: .SH NAME
        !             4: socket \- create an endpoint for communication
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .ft B
        !             8: #include <sys/types.h>
        !             9: #include <sys/socket.h>
        !            10: .PP
        !            11: .ft B
        !            12: s = socket(af, type, protocol)
        !            13: int s, af, type, protocol;
        !            14: .fi
        !            15: .SH DESCRIPTION
        !            16: .I Socket
        !            17: creates an endpoint for communication and returns a descriptor.
        !            18: .PP
        !            19: The
        !            20: .I af
        !            21: parameter specifies an address format with which addresses specified
        !            22: in later operations using the socket should be interpreted.  These
        !            23: formats are defined in the include file
        !            24: .IR <sys/socket.h> .
        !            25: The currently understood formats are
        !            26: .PP
        !            27: .RS
        !            28: .nf
        !            29: .ta 1.25i 1.75i
        !            30: AF_UNIX        (UNIX path names),
        !            31: AF_INET        (ARPA Internet addresses),
        !            32: AF_PUP (Xerox PUP-I Internet addresses), and
        !            33: AF_IMPLINK     (IMP \*(lqhost at IMP\*(rq addresses).
        !            34: .fi
        !            35: .RE
        !            36: .PP
        !            37: The socket has the indicated
        !            38: .I type
        !            39: which specifies the semantics of communication.  Currently
        !            40: defined types are:
        !            41: .PP
        !            42: .RS
        !            43: .nf
        !            44: SOCK_STREAM
        !            45: SOCK_DGRAM
        !            46: SOCK_RAW
        !            47: SOCK_SEQPACKET
        !            48: SOCK_RDM
        !            49: .fi
        !            50: .RE
        !            51: .PP
        !            52: A SOCK_STREAM type provides sequenced, reliable,
        !            53: two-way connection based byte streams with an out-of-band data
        !            54: transmission mechanism.
        !            55: A SOCK_DGRAM socket supports
        !            56: datagrams (connectionless, unreliable messages of
        !            57: a fixed (typically small) maximum length).
        !            58: SOCK_RAW sockets provide access to internal network interfaces.
        !            59: The types SOCK_RAW,
        !            60: which is available only to the super-user, and
        !            61: SOCK_SEQPACKET and SOCK_RDM, which are planned,
        !            62: but not yet implemented, are not described here.
        !            63: .PP
        !            64: The
        !            65: .I protocol
        !            66: specifies a particular protocol to be used with the socket.
        !            67: Normally only a single protocol exists to support a particular
        !            68: socket type using a given address format.  However, it is possible
        !            69: that many protocols may exist in which case a particular protocol
        !            70: must be specified in this manner.  The protocol number to use is
        !            71: particular to the \*(lqcommunication domain\*(rq in which communication
        !            72: is to take place; see
        !            73: .IR services (3N)
        !            74: and
        !            75: .IR protocols (3N).
        !            76: .PP
        !            77: Sockets of type SOCK_STREAM
        !            78: are full-duplex byte streams, similar
        !            79: to pipes.  A stream socket must be in a
        !            80: .I connected
        !            81: state before any data may be sent or received
        !            82: on it.  A connection to another socket is created with a
        !            83: .IR connect (2)
        !            84: call.  Once connected, data may be transferred using
        !            85: .IR read (2)
        !            86: and
        !            87: .IR write (2)
        !            88: calls or some variant of the 
        !            89: .IR send (2)
        !            90: and
        !            91: .IR recv (2)
        !            92: calls.  When a session has been completed a
        !            93: .IR close (2)
        !            94: may be performed.
        !            95: Out-of-band data may also be transmitted as described in
        !            96: .IR send (2)
        !            97: and received as described in
        !            98: .IR recv (2).
        !            99: .PP
        !           100: The communications protocols used to implement a
        !           101: SOCK_STREAM insure that data
        !           102: is not lost or duplicated.  If a piece of data for which the
        !           103: peer protocol has buffer space cannot be successfully transmitted
        !           104: within a reasonable length of time, then
        !           105: the connection is considered broken and calls
        !           106: will indicate an error with
        !           107: \-1 returns and with ETIMEDOUT as the specific code
        !           108: in the global variable errno.
        !           109: The protocols optionally keep sockets \*(lqwarm\*(rq by
        !           110: forcing transmissions
        !           111: roughly every minute in the absence of other activity.
        !           112: An error is then indicated if no response can be
        !           113: elicited on an otherwise
        !           114: idle connection for a extended period (e.g. 5 minutes).
        !           115: A SIGPIPE signal is raised if a process sends
        !           116: on a broken stream; this causes naive processes,
        !           117: which do not handle the signal, to exit.
        !           118: .PP
        !           119: SOCK_DGRAM and SOCK_RAW
        !           120: sockets allow sending of datagrams to correspondents
        !           121: named in
        !           122: .IR send (2)
        !           123: calls.  It is also possible to receive datagrams at
        !           124: such a socket with
        !           125: .IR recv (2).
        !           126: .PP
        !           127: An 
        !           128: .IR fcntl (2)
        !           129: call can be used to specify a process group to receive
        !           130: a SIGURG signal when the out-of-band data arrives.
        !           131: .PP
        !           132: The operation of sockets is controlled by socket level
        !           133: .IR options .
        !           134: These options are defined in the file
        !           135: .RI < sys/socket.h >
        !           136: and explained below.  
        !           137: .I Setsockopt
        !           138: and
        !           139: .IR getsockopt (2)
        !           140: are used to set and get options, respectively.
        !           141: .PP
        !           142: .RS
        !           143: .DT
        !           144: .nf
        !           145: SO_DEBUG               turn on recording of debugging information
        !           146: SO_REUSEADDR   allow local address reuse
        !           147: SO_KEEPALIVE   keep connections alive
        !           148: SO_DONTROUTE   do no apply routing on outgoing messages
        !           149: SO_LINGER              linger on close if data present
        !           150: SO_DONTLINGER  do not linger on close
        !           151: .fi
        !           152: .RE
        !           153: .PP
        !           154: SO_DEBUG enables debugging in the underlying protocol modules.
        !           155: SO_REUSEADDR indicates the rules used in validating addresses supplied
        !           156: in a
        !           157: .IR bind (2)
        !           158: call should allow reuse of local addresses.  SO_KEEPALIVE enables the
        !           159: periodic transmission of messages on a connected socket.  Should the
        !           160: connected party fail to respond to these messages, the connection is
        !           161: considered broken and processes using the socket are notified via a
        !           162: SIGPIPE signal.  SO_DONTROUTE indicates that outgoing messages should
        !           163: bypass the standard routing facilities.  Instead, messages are directed
        !           164: to the appropriate network interface according to the network portion
        !           165: of the destination address.  SO_LINGER
        !           166: and SO_DONTLINGER control the actions taken when unsent messags
        !           167: are queued on socket and a 
        !           168: .IR close (2)
        !           169: is performed.
        !           170: If the socket promises reliable delivery of data and SO_LINGER is set,
        !           171: the system will block the process on the 
        !           172: .I close
        !           173: attempt until it is able to transmit the data or until it decides it
        !           174: is unable to deliver the information (a timeout period, termed the
        !           175: linger interval, is specified in the
        !           176: .IR setsockopt 
        !           177: call when SO_LINGER is requested). 
        !           178: If SO_DONTLINGER is specified and a 
        !           179: .I close
        !           180: is issued, the system will process the close in a manner which allows
        !           181: the process to continue as quickly as possible.
        !           182: .SH "RETURN VALUE
        !           183: A \-1 is returned if an error occurs, otherwise the return
        !           184: value is a descriptor referencing the socket.
        !           185: .SH "ERRORS
        !           186: The \fIsocket\fP call fails if:
        !           187: .TP 20
        !           188: [EAFNOSUPPORT]
        !           189: The specified address family is not supported in this version
        !           190: of the system.
        !           191: .TP 20
        !           192: [ESOCKTNOSUPPORT]
        !           193: The specified socket type is not supported in this address family.
        !           194: .TP 20
        !           195: [EPROTONOSUPPORT]
        !           196: The specified protocol is not supported.
        !           197: .TP 20
        !           198: [EMFILE]
        !           199: The per-process descriptor table is full.
        !           200: .TP 20
        !           201: [ENOBUFS]
        !           202: No buffer space is available.  The socket cannot be created.
        !           203: .SH SEE ALSO
        !           204: accept(2), bind(2), connect(2), getsockname(2), getsockopt(2),
        !           205: ioctl(2), listen(2), recv(2),
        !           206: select(2), send(2), shutdown(2), socketpair(2)
        !           207: .br
        !           208: ``A 4.2BSD Interprocess Communication Primer''.
        !           209: .SH BUGS
        !           210: The use of keepalives is a questionable feature for this layer.

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