Return to socket.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/socket.2, revision 1.1

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