| blob | 6912d0659369f94119a4a68c10a9c35b03226f03 |
1 .\" $NetBSD: socket.2,v 1.41 2013/03/01 18:25:16 joerg Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)socket.2 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd February 5, 2013
33 .Dt SOCKET 2
34 .Os
35 .Sh NAME
36 .Nm socket
37 .Nd create an endpoint for communication
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/socket.h
42 .Ft int
43 .Fn socket "int domain" "int type" "int protocol"
44 .Sh DESCRIPTION
45 .Fn socket
46 creates an endpoint for communication and returns a descriptor.
47 .Pp
48 The
49 .Fa domain
50 parameter specifies a communications domain within which
51 communication will take place; this selects the protocol family
52 which should be used.
53 These families are defined in the include file
54 .Ao Pa sys/socket.h Ac .
55 The currently understood formats are:
56 .Pp
57 .Bd -literal -offset indent -compact
58 PF_LOCAL local (previously UNIX) domain protocols
59 PF_INET ARPA Internet protocols
60 PF_INET6 IPv6 (Internet Protocol version 6) protocols
61 PF_NS Xerox Network Systems protocols
62 PF_APPLETALK AppleTalk protocols
63 PF_BLUETOOTH Bluetooth protocols
64 .Ed
65 .Pp
66 The socket has the indicated
67 .Fa type ,
68 which specifies the semantics of communication.
69 Currently defined types are:
70 .Pp
71 .Bd -literal -offset indent -compact
72 SOCK_STREAM
73 SOCK_DGRAM
74 SOCK_RAW
75 SOCK_SEQPACKET
76 SOCK_RDM
77 .Ed
78 .Pp
79 The following flags can be or'ed to the type to condition the returned
80 file descriptor:
81 The following flags are valid:
82 .Bl -column SOCK_NONBLOCK -offset indent
83 .It Dv SOCK_CLOEXEC
84 Set the close on exec property.
85 .It Dv SOCK_NONBLOCK
86 Sets non-blocking I/O.
87 .It Dv SOCK_NOSIGPIPE
88 Return
89 .Er EPIPE
90 instead of raising
91 .Dv SIGPIPE .
92 .El
93 .Pp
94 A
95 .Dv SOCK_STREAM
96 type provides sequenced, reliable,
97 two-way connection based byte streams.
98 An out-of-band data transmission mechanism may be supported.
99 A
100 .Dv SOCK_DGRAM
101 socket supports
102 datagrams (connectionless, unreliable messages of
103 a fixed (typically small) maximum length).
104 A
105 .Dv SOCK_SEQPACKET
106 socket may provide a sequenced, reliable,
107 two-way connection-based data transmission path for datagrams
108 of fixed maximum length; a consumer may be required to read
109 an entire packet with each read system call.
110 This facility is protocol specific, and presently implemented
111 only for
112 .Dv PF_NS .
113 .Dv SOCK_RAW
114 sockets provide access to internal network protocols and interfaces.
115 The types
116 .Dv SOCK_RAW ,
117 which is available only to the super-user, and
118 .Dv SOCK_RDM ,
119 which is planned,
120 but not yet implemented, are not described here.
121 .Pp
122 The
123 .Fa protocol
124 specifies a particular protocol to be used with the socket.
125 Normally only a single protocol exists to support a particular
126 socket type within a given protocol family.
127 However, it is possible that many protocols may exist, in which case
128 a particular protocol must be specified in this manner.
129 The protocol number to use is
130 particular to the \*(lqcommunication domain\*(rq in which communication
131 is to take place; see
132 .Xr protocols 5 .
133 .Pp
134 Sockets of type
135 .Dv SOCK_STREAM
136 are full-duplex byte streams.
137 A stream socket must be in a
138 .Em connected
139 state before any data may be sent or received
140 on it.
141 A connection to another socket is created with a
142 .Xr connect 2
143 call.
144 Once connected, data may be transferred using
145 .Xr read 2
146 and
147 .Xr write 2
148 calls or some variant of the
149 .Xr send 2
150 and
151 .Xr recv 2
152 calls.
153 When a session has been completed a
154 .Xr close 2
155 may be performed.
156 Out-of-band data may also be transmitted as described in
157 .Xr send 2
158 and received as described in
159 .Xr recv 2 .
160 .Pp
161 The communications protocols used to implement a
162 .Dv SOCK_STREAM
163 ensure that data
164 is not lost or duplicated.
165 If a piece of data for which the
166 peer protocol has buffer space cannot be successfully transmitted
167 within a reasonable length of time, then
168 the connection is considered broken and calls
169 will indicate an error with
170 \-1 returns and with
171 .Er ETIMEDOUT
172 as the specific code
173 in the global variable
174 .Va errno .
175 The protocols optionally keep sockets
176 .Dq warm
177 by forcing transmissions
178 roughly every minute in the absence of other activity.
179 An error is then indicated if no response can be
180 elicited on an otherwise
181 idle connection for an extended period (e.g., 5 minutes).
182 A
183 .Dv SIGPIPE
184 signal is raised if a process sends
185 on a broken stream; this causes naive processes,
186 which do not handle the signal, to exit.
187 .Pp
188 .Dv SOCK_SEQPACKET
189 sockets employ the same system calls
190 as
191 .Dv SOCK_STREAM
192 sockets.
193 The only difference is that
194 .Xr read 2
195 calls will return only the amount of data requested,
196 and any remaining in the arriving packet will be discarded.
197 .Pp
198 .Dv SOCK_DGRAM
199 and
200 .Dv SOCK_RAW
201 sockets allow sending of datagrams to correspondents
202 named in
203 .Xr send 2
204 calls.
205 Datagrams are generally received with
206 .Xr recvfrom 2 ,
207 which returns the next datagram with its return address.
208 .Pp
209 An
210 .Xr fcntl 2
211 call can be used to specify a process group to receive
212 a
213 .Dv SIGURG
214 signal when the out-of-band data arrives.
215 It may also enable non-blocking I/O
216 and asynchronous notification of I/O events
217 via
218 .Dv SIGIO .
219 .Pp
220 The operation of sockets is controlled by socket level
221 .Em options .
222 These options are defined in the file
223 .Ao Pa sys/socket.h Ac .
224 The
225 .Xr setsockopt 2
226 and
227 .Xr getsockopt 2
228 system calls are used to set and get options, respectively.
229 .Sh RETURN VALUES
230 A \-1 is returned if an error occurs, otherwise the return
231 value is a descriptor referencing the socket.
232 .Sh ERRORS
233 The
234 .Fn socket
235 call fails if:
236 .Bl -tag -width Er
237 .It Bq Er EACCES
238 Permission to create a socket of the specified type and/or protocol
239 is denied.
240 .It Bq Er EAFNOSUPPORT
241 The address family (domain) is not supported or
242 the specified domain is not supported by this protocol family.
243 .It Bq Er EMFILE
244 The per-process descriptor table is full.
245 .It Bq Er ENFILE
246 The system file table is full.
247 .It Bq Er ENOBUFS
248 Insufficient buffer space is available.
249 The socket cannot be created until sufficient resources are freed.
250 .It Bq Er EPROTONOSUPPORT
251 The protocol family is not supported or
252 the specified protocol is not supported within this domain.
253 .It Bq Er EPROTOTYPE
254 The socket type is not supported by the protocol.
255 .El
256 .Sh SEE ALSO
257 .Xr accept 2 ,
258 .Xr bind 2 ,
259 .Xr connect 2 ,
260 .Xr getsockname 2 ,
261 .Xr getsockopt 2 ,
262 .Xr ioctl 2 ,
263 .Xr listen 2 ,
264 .Xr poll 2 ,
265 .Xr read 2 ,
266 .Xr recv 2 ,
267 .Xr select 2 ,
268 .Xr send 2 ,
269 .Xr setsockopt 2 ,
270 .Xr shutdown 2 ,
271 .Xr socketpair 2 ,
272 .Xr write 2 ,
273 .Xr getprotoent 3
274 .Rs
275 .%T "An Introductory 4.4BSD Interprocess Communication Tutorial"
276 .%A Stuart Sechrest
277 .Re
278 .Pq see Pa /usr/share/doc/psd/20.ipctut
279 .Rs
280 .%T "Advanced 4.4BSD IPC Tutorial"
281 .%A Samuel J. Leffler
282 .%A Robert S. Fabry
283 .%A William N. Joy
284 .%A Phil Lapsley
285 .%A Steve Miller
286 .%A Chris Torek
287 .Re
288 .Pq see Pa /usr/share/doc/psd/21.ipc
289 .Sh HISTORY
290 The
291 .Fn socket
292 function call appeared in
293 .Bx 4.2 .