![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to socket.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to socket.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
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.