91980aed4c3bbd1067be553cf0fd463520751752
[dragonfly.git] / lib / libc / sys / socket.2
1 .\" Copyright (c) 1983, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     From: @(#)socket.2      8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/sys/socket.2,v 1.12.2.11 2002/12/29 16:35:34 schweikh Exp $
34 .\" $DragonFly: src/lib/libc/sys/socket.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
35 .\"
36 .Dd November 24, 1997
37 .Dt SOCKET 2
38 .Os
39 .Sh NAME
40 .Nm socket
41 .Nd create an endpoint for communication
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In sys/types.h
46 .In sys/socket.h
47 .Ft int
48 .Fn socket "int domain" "int type" "int protocol"
49 .Sh DESCRIPTION
50 .Fn Socket
51 creates an endpoint for communication and returns a descriptor.
52 .Pp
53 The
54 .Fa domain
55 parameter specifies a communications domain within which
56 communication will take place; this selects the protocol family
57 which should be used.
58 These families are defined in the include file
59 .Ao Pa sys/socket.h Ac .
60 The currently understood formats are:
61 .Pp
62 .Bd -literal -offset indent -compact
63 PF_LOCAL        Host-internal protocols, formerly called PF_UNIX,
64 PF_UNIX         Host-internal protocols, deprecated, use PF_LOCAL,
65 PF_INET         Internet version 4 protocols,
66 PF_IMPLINK      ARPAnet IMP addresses,
67 PF_PUP          PUP protocols, like BSP,
68 PF_CHAOS        MIT CHAOS protocols,
69 PF_NS           Xerox Network Systems protocols,
70 PF_ISO          ISO protocols,
71 PF_OSI          Open Systems Interconnection protocols,
72 PF_ECMA         European Computer Manufacturers,
73 PF_DATAKIT      Datakit protocols,
74 PF_CCITT        ITU-T protocols, like X.25,
75 PF_SNA          IBM SNA,
76 PF_DECnet       DECnet,
77 PF_DLI          DEC Direct Data Link Interface protocol,
78 PF_LAT          LAT protocol,
79 PF_HYLINK       NSC Hyperchannel,
80 PF_APPLETALK    AppleTalk protocols,
81 PF_ROUTE        Internal Routing protocol,
82 PF_LINK         Link layer interface,
83 PF_XTP          eXpress Transfer Protocol,
84 PF_COIP         Connection-Oriented IP, aka ST II,
85 PF_CNT          Computer Network Technology,
86 PF_SIP          Simple Internet Protocol,
87 PF_IPX          Novell Internet Packet eXchange protocol,
88 PF_RTIP         Help Identify RTIP packets,
89 PF_PIP          Help Identify PIP packets,
90 PF_ISDN         Integrated Services Digital Network,
91 PF_KEY          Internal key-management function,
92 PF_INET6        Internet version 6 protocols,
93 PF_NATM         Native ATM access,
94 PF_ATM          ATM,
95 PF_NETGRAPH     Netgraph sockets
96 .Ed
97 .Pp
98 The socket has the indicated
99 .Fa type ,
100 which specifies the semantics of communication.  Currently
101 defined types are:
102 .Pp
103 .Bd -literal -offset indent -compact
104 SOCK_STREAM     Stream socket,
105 SOCK_DGRAM      Datagram socket,
106 SOCK_RAW        Raw-protocol interface,
107 SOCK_RDM        Reliably-delivered packet,
108 SOCK_SEQPACKET  Sequenced packet stream
109 .Ed
110 .Pp
111 A
112 .Dv SOCK_STREAM
113 type provides sequenced, reliable,
114 two-way connection based byte streams.
115 An out-of-band data transmission mechanism may be supported.
116 A
117 .Dv SOCK_DGRAM
118 socket supports
119 datagrams (connectionless, unreliable messages of
120 a fixed (typically small) maximum length).
121 A
122 .Dv SOCK_SEQPACKET
123 socket may provide a sequenced, reliable,
124 two-way connection-based data transmission path for datagrams
125 of fixed maximum length; a consumer may be required to read
126 an entire packet with each read system call.
127 This facility is protocol specific, and presently implemented
128 only for
129 .Dv PF_NS .
130 .Dv SOCK_RAW
131 sockets provide access to internal network protocols and interfaces.
132 The types
133 .Dv SOCK_RAW ,
134 which is available only to the super-user, and
135 .Dv SOCK_RDM ,
136 which is planned,
137 but not yet implemented, are not described here.
138 .Pp
139 The
140 .Fa protocol
141 specifies a particular protocol to be used with the socket.
142 Normally only a single protocol exists to support a particular
143 socket type within a given protocol family.  However, it is possible
144 that many protocols may exist, in which case a particular protocol
145 must be specified in this manner.  The protocol number to use is
146 particular to the
147 .Dq "communication domain"
148 in which communication
149 is to take place; see
150 .Xr protocols 5 .
151 .Pp
152 Sockets of type
153 .Dv SOCK_STREAM
154 are full-duplex byte streams, similar
155 to pipes.  A stream socket must be in a
156 .Em connected
157 state before any data may be sent or received
158 on it.  A connection to another socket is created with a
159 .Xr connect 2
160 call.
161 Once connected, data may be transferred using
162 .Xr read 2
163 and
164 .Xr write 2
165 calls or some variant of the
166 .Xr send 2
167 and
168 .Xr recv 2
169 calls.
170 (Some protocol families, such as the Internet family,
171 support the notion of an
172 .Dq implied connect ,
173 which permits data to be sent piggybacked onto a connect operation by
174 using the
175 .Xr sendto 2
176 call.)
177 When a session has been completed a
178 .Xr close 2
179 may be performed.
180 Out-of-band data may also be transmitted as described in
181 .Xr send 2
182 and received as described in
183 .Xr recv 2 .
184 .Pp
185 The communications protocols used to implement a
186 .Dv SOCK_STREAM
187 insure that data
188 is not lost or duplicated.  If a piece of data for which the
189 peer protocol has buffer space cannot be successfully transmitted
190 within a reasonable length of time, then
191 the connection is considered broken and calls
192 will indicate an error with
193 -1 returns and with
194 .Er ETIMEDOUT
195 as the specific code
196 in the global variable
197 .Va errno .
198 The protocols optionally keep sockets
199 .Dq warm
200 by forcing transmissions
201 roughly every minute in the absence of other activity.
202 An error is then indicated if no response can be
203 elicited on an otherwise
204 idle connection for a extended period (e.g. 5 minutes).
205 A
206 .Dv SIGPIPE
207 signal is raised if a process sends
208 on a broken stream; this causes naive processes,
209 which do not handle the signal, to exit.
210 .Pp
211 .Dv SOCK_SEQPACKET
212 sockets employ the same system calls
213 as
214 .Dv SOCK_STREAM
215 sockets.  The only difference
216 is that
217 .Xr read 2
218 calls will return only the amount of data requested,
219 and any remaining in the arriving packet will be discarded.
220 .Pp
221 .Dv SOCK_DGRAM
222 and
223 .Dv SOCK_RAW
224 sockets allow sending of datagrams to correspondents
225 named in
226 .Xr send 2
227 calls.  Datagrams are generally received with
228 .Xr recvfrom 2 ,
229 which returns the next datagram with its return address.
230 .Pp
231 An
232 .Xr fcntl 2
233 call can be used to specify a process group to receive
234 a
235 .Dv SIGURG
236 signal when the out-of-band data arrives.
237 It may also enable non-blocking I/O
238 and asynchronous notification of I/O events
239 via
240 .Dv SIGIO .
241 .Pp
242 The operation of sockets is controlled by socket level
243 .Em options .
244 These options are defined in the file
245 .Ao Pa sys/socket.h Ac .
246 .Xr Setsockopt 2
247 and
248 .Xr getsockopt 2
249 are used to set and get options, respectively.
250 .Sh RETURN VALUES
251 A -1 is returned if an error occurs, otherwise the return
252 value is a descriptor referencing the socket.
253 .Sh ERRORS
254 The
255 .Fn socket
256 call fails if:
257 .Bl -tag -width Er
258 .It Bq Er EPROTONOSUPPORT
259 The protocol type or the specified protocol is not supported
260 within this domain.
261 .It Bq Er EMFILE
262 The per-process descriptor table is full.
263 .It Bq Er ENFILE
264 The system file table is full.
265 .It Bq Er EACCES
266 Permission to create a socket of the specified type and/or protocol
267 is denied.
268 .It Bq Er ENOBUFS
269 Insufficient buffer space is available.
270 The socket cannot be created until sufficient resources are freed.
271 .El
272 .Sh SEE ALSO
273 .Xr accept 2 ,
274 .Xr bind 2 ,
275 .Xr connect 2 ,
276 .Xr getpeername 2 ,
277 .Xr getsockname 2 ,
278 .Xr getsockopt 2 ,
279 .Xr ioctl 2 ,
280 .Xr listen 2 ,
281 .Xr read 2 ,
282 .Xr recv 2 ,
283 .Xr select 2 ,
284 .Xr send 2 ,
285 .Xr shutdown 2 ,
286 .Xr socketpair 2 ,
287 .Xr write 2 ,
288 .Xr getprotoent 3 ,
289 .Xr netgraph 4 ,
290 .Xr protocols 5
291 .Rs
292 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
293 .%B PS1
294 .%N 7
295 .Re
296 .Rs
297 .%T "BSD Interprocess Communication Tutorial"
298 .%B PS1
299 .%N 8
300 .Re
301 .Sh HISTORY
302 The
303 .Fn socket
304 function call appeared in
305 .Bx 4.2 .