Return to socket.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/socket.2, 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: .\"    @(#)socket.2    6.5 (Berkeley) 5/23/86
        !             6: .\"
        !             7: .TH SOCKET 2 "May 23, 1986"
        !             8: .UC 5
        !             9: .SH NAME
        !            10: socket \- create an endpoint for communication
        !            11: .SH SYNOPSIS
        !            12: .nf
        !            13: .ft B
        !            14: #include <sys/types.h>
        !            15: #include <sys/socket.h>
        !            16: .PP
        !            17: .ft B
        !            18: s = socket(domain, type, protocol)
        !            19: int s, domain, type, protocol;
        !            20: .fi
        !            21: .SH DESCRIPTION
        !            22: .I Socket
        !            23: creates an endpoint for communication and returns a descriptor.
        !            24: .PP
        !            25: The
        !            26: .I domain
        !            27: parameter specifies a communications domain within which
        !            28: communication will take place; this selects the protocol family
        !            29: which should be used.
        !            30: The protocol family generally is the same as the address family
        !            31: for the addresses supplied in later operations on the socket.
        !            32: These families are defined in the include file
        !            33: .IR <sys/socket.h> .
        !            34: The currently understood formats are
        !            35: .PP
        !            36: .RS
        !            37: .nf
        !            38: .ta 1.25i 1.75i
        !            39: PF_UNIX        (UNIX internal protocols),
        !            40: PF_INET        (ARPA Internet protocols),
        !            41: PF_NS  (Xerox Network Systems protocols), and
        !            42: PF_IMPLINK     (IMP \*(lqhost at IMP\*(rq link layer).
        !            43: .fi
        !            44: .RE
        !            45: .PP
        !            46: The socket has the indicated
        !            47: .I type,
        !            48: which specifies the semantics of communication.  Currently
        !            49: defined types are:
        !            50: .PP
        !            51: .RS
        !            52: .nf
        !            53: SOCK_STREAM
        !            54: SOCK_DGRAM
        !            55: SOCK_RAW
        !            56: SOCK_SEQPACKET
        !            57: SOCK_RDM
        !            58: .fi
        !            59: .RE
        !            60: .PP
        !            61: A SOCK_STREAM type provides sequenced, reliable,
        !            62: two-way connection based byte streams.
        !            63: An out-of-band data transmission mechanism may be supported.
        !            64: A SOCK_DGRAM socket supports
        !            65: datagrams (connectionless, unreliable messages of
        !            66: a fixed (typically small) maximum length).
        !            67: A SOCK_SEQPACKET socket may provide a sequenced, reliable,
        !            68: two-way connection-based data transmission path for datagrams
        !            69: of fixed maximum length; a consumer may be required to read
        !            70: an entire packet with each read system call.
        !            71: This facility is protocol specific, and presently implemented
        !            72: only for PF_NS.
        !            73: SOCK_RAW sockets provide access to internal network protocols and interfaces.
        !            74: The types SOCK_RAW,
        !            75: which is available only to the super-user, and
        !            76: SOCK_RDM, which is planned,
        !            77: but not yet implemented, are not described here.
        !            78: .PP
        !            79: The
        !            80: .I protocol
        !            81: specifies a particular protocol to be used with the socket.
        !            82: Normally only a single protocol exists to support a particular
        !            83: socket type within a given protocol family.  However, it is possible
        !            84: that many protocols may exist, in which case a particular protocol
        !            85: must be specified in this manner.  The protocol number to use is
        !            86: particular to the \*(lqcommunication domain\*(rq in which communication
        !            87: is to take place; see
        !            88: .IR protocols (3N).
        !            89: .PP
        !            90: Sockets of type SOCK_STREAM
        !            91: are full-duplex byte streams, similar
        !            92: to pipes.  A stream socket must be in a
        !            93: .I connected
        !            94: state before any data may be sent or received
        !            95: on it.  A connection to another socket is created with a
        !            96: .IR connect (2)
        !            97: call.  Once connected, data may be transferred using
        !            98: .IR read (2)
        !            99: and
        !           100: .IR write (2)
        !           101: calls or some variant of the 
        !           102: .IR send (2)
        !           103: and
        !           104: .IR recv (2)
        !           105: calls.  When a session has been completed a
        !           106: .IR close (2)
        !           107: may be performed.
        !           108: Out-of-band data may also be transmitted as described in
        !           109: .IR send (2)
        !           110: and received as described in
        !           111: .IR recv (2).
        !           112: .PP
        !           113: The communications protocols used to implement a
        !           114: SOCK_STREAM insure that data
        !           115: is not lost or duplicated.  If a piece of data for which the
        !           116: peer protocol has buffer space cannot be successfully transmitted
        !           117: within a reasonable length of time, then
        !           118: the connection is considered broken and calls
        !           119: will indicate an error with
        !           120: \-1 returns and with ETIMEDOUT as the specific code
        !           121: in the global variable errno.
        !           122: The protocols optionally keep sockets \*(lqwarm\*(rq by
        !           123: forcing transmissions
        !           124: roughly every minute in the absence of other activity.
        !           125: An error is then indicated if no response can be
        !           126: elicited on an otherwise
        !           127: idle connection for a extended period (e.g. 5 minutes).
        !           128: A SIGPIPE signal is raised if a process sends
        !           129: on a broken stream; this causes naive processes,
        !           130: which do not handle the signal, to exit.
        !           131: .PP
        !           132: SOCK_SEQPACKET sockets employ the same system calls
        !           133: as SOCK_STREAM sockets.  The only difference
        !           134: is that 
        !           135: .IR read (2)
        !           136: calls will return only the amount of data requested,
        !           137: and any remaining in the arriving packet will be discarded.
        !           138: .PP
        !           139: SOCK_DGRAM and SOCK_RAW
        !           140: sockets allow sending of datagrams to correspondents
        !           141: named in
        !           142: .IR send (2)
        !           143: calls.  Datagrams are generally received with
        !           144: .IR recvfrom (2),
        !           145: which returns the next datagram with its return address.
        !           146: .PP
        !           147: An 
        !           148: .IR fcntl (2)
        !           149: call can be used to specify a process group to receive
        !           150: a SIGURG signal when the out-of-band data arrives.
        !           151: It may also enable non-blocking I/O
        !           152: and asynchronous notification of I/O events
        !           153: via SIGIO.
        !           154: .PP
        !           155: The operation of sockets is controlled by socket level
        !           156: .IR options .
        !           157: These options are defined in the file
        !           158: .RI < sys/socket.h >.
        !           159: .IR Setsockopt (2)
        !           160: and
        !           161: .IR getsockopt (2)
        !           162: are used to set and get options, respectively.
        !           163: .SH "RETURN VALUE
        !           164: A \-1 is returned if an error occurs, otherwise the return
        !           165: value is a descriptor referencing the socket.
        !           166: .SH "ERRORS
        !           167: The \fIsocket\fP call fails if:
        !           168: .TP 20
        !           169: [EPROTONOSUPPORT]
        !           170: The protocol type or the specified protocol is not supported
        !           171: within this domain.
        !           172: .TP 20
        !           173: [EMFILE]
        !           174: The per-process descriptor table is full.
        !           175: .TP 20
        !           176: [ENFILE]
        !           177: The system file table is full.
        !           178: .TP 20
        !           179: [EACCESS]
        !           180: Permission to create a socket of the specified type and/or protocol
        !           181: is denied.
        !           182: .TP 20
        !           183: [ENOBUFS]
        !           184: Insufficient buffer space is available.
        !           185: The socket cannot be created until sufficient resources are freed.
        !           186: .SH SEE ALSO
        !           187: accept(2), bind(2), connect(2), getsockname(2), getsockopt(2),
        !           188: ioctl(2), listen(2), read(2), recv(2),
        !           189: select(2), send(2), shutdown(2), socketpair(2), write(2)
        !           190: .br
        !           191: ``An Introductory 4.3BSD Interprocess Communication Tutorial.''
        !           192: (reprinted in UNIX Programmer's Supplementary Documents Volume 1, PS1:7)
        !           193: ``An Advanced 4.3BSD Interprocess Communication Tutorial.''
        !           194: (reprinted in UNIX Programmer's Supplementary Documents Volume 1, PS1:8)

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