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