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