Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
2 | .\" 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 | .\" @(#)socket.2 6.8 (Berkeley) 3/10/91 | |
33 | .\" | |
34 | .Dd March 10, 1991 | |
35 | .Dt SOCKET 2 | |
36 | .Os BSD 4.2 | |
37 | .Sh NAME | |
38 | .Nm socket | |
39 | .Nd create an endpoint for communication | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <sys/types.h> | |
42 | .Fd #include <sys/socket.h> | |
43 | .Ft int | |
44 | .Fn socket "int domain" "int type" "int protocol" | |
45 | .Sh DESCRIPTION | |
46 | .Fn Socket | |
47 | creates an endpoint for communication and returns a descriptor. | |
48 | .Pp | |
49 | The | |
50 | .Fa domain | |
51 | parameter specifies a communications domain within which | |
52 | communication will take place; this selects the protocol family | |
53 | which should be used. | |
54 | These families are defined in the include file | |
55 | .Ao Pa sys/socket.h Ac . | |
56 | The currently understood formats are | |
57 | .Pp | |
58 | .Bd -literal -offset indent -compact | |
59 | AF_UNIX (UNIX internal protocols), | |
60 | AF_INET (ARPA Internet protocols), | |
61 | AF_ISO (ISO protocols), | |
62 | AF_NS (Xerox Network Systems protocols), and | |
63 | AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer). | |
64 | .Ed | |
65 | .Pp | |
66 | The socket has the indicated | |
67 | .Fa type , | |
68 | which specifies the semantics of communication. Currently | |
69 | 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 | A | |
80 | .Dv SOCK_STREAM | |
81 | type provides sequenced, reliable, | |
82 | two-way connection based byte streams. | |
83 | An out-of-band data transmission mechanism may be supported. | |
84 | A | |
85 | .Dv SOCK_DGRAM | |
86 | socket supports | |
87 | datagrams (connectionless, unreliable messages of | |
88 | a fixed (typically small) maximum length). | |
89 | A | |
90 | .Dv SOCK_SEQPACKET | |
91 | socket may provide a sequenced, reliable, | |
92 | two-way connection-based data transmission path for datagrams | |
93 | of fixed maximum length; a consumer may be required to read | |
94 | an entire packet with each read system call. | |
95 | This facility is protocol specific, and presently implemented | |
96 | only for | |
97 | .Dv PF_NS . | |
98 | .Dv SOCK_RAW | |
99 | sockets provide access to internal network protocols and interfaces. | |
100 | The types | |
101 | .Dv SOCK_RAW , | |
102 | which is available only to the super-user, and | |
103 | .Dv SOCK_RDM , | |
104 | which is planned, | |
105 | but not yet implemented, are not described here. | |
106 | .Pp | |
107 | The | |
108 | .Fa protocol | |
109 | specifies a particular protocol to be used with the socket. | |
110 | Normally only a single protocol exists to support a particular | |
111 | socket type within a given protocol family. However, it is possible | |
112 | that many protocols may exist, in which case a particular protocol | |
113 | must be specified in this manner. The protocol number to use is | |
114 | particular to the \*(lqcommunication domain\*(rq in which communication | |
115 | is to take place; see | |
116 | .Xr protocols 5 . | |
117 | .Pp | |
118 | Sockets of type | |
119 | .Dv SOCK_STREAM | |
120 | are full-duplex byte streams, similar | |
121 | to pipes. A stream socket must be in a | |
122 | .Em connected | |
123 | state before any data may be sent or received | |
124 | on it. A connection to another socket is created with a | |
125 | .Xr connect 2 | |
126 | call. Once connected, data may be transferred using | |
127 | .Xr read 2 | |
128 | and | |
129 | .Xr write 2 | |
130 | calls or some variant of the | |
131 | .Xr send 2 | |
132 | and | |
133 | .Xr recv 2 | |
134 | calls. When a session has been completed a | |
135 | .Xr close 2 | |
136 | may be performed. | |
137 | Out-of-band data may also be transmitted as described in | |
138 | .Xr send 2 | |
139 | and received as described in | |
140 | .Xr recv 2 . | |
141 | .Pp | |
142 | The communications protocols used to implement a | |
143 | .Dv SOCK_STREAM | |
144 | insure that data | |
145 | is not lost or duplicated. If a piece of data for which the | |
146 | peer protocol has buffer space cannot be successfully transmitted | |
147 | within a reasonable length of time, then | |
148 | the connection is considered broken and calls | |
149 | will indicate an error with | |
150 | -1 returns and with | |
151 | .Dv ETIMEDOUT | |
152 | as the specific code | |
153 | in the global variable | |
154 | .Va errno . | |
155 | The protocols optionally keep sockets | |
156 | .Dq warm | |
157 | by forcing transmissions | |
158 | roughly every minute in the absence of other activity. | |
159 | An error is then indicated if no response can be | |
160 | elicited on an otherwise | |
161 | idle connection for a extended period (e.g. 5 minutes). | |
162 | A | |
163 | .Dv SIGPIPE | |
164 | signal is raised if a process sends | |
165 | on a broken stream; this causes naive processes, | |
166 | which do not handle the signal, to exit. | |
167 | .Pp | |
168 | .Dv SOCK_SEQPACKET | |
169 | sockets employ the same system calls | |
170 | as | |
171 | .Dv SOCK_STREAM | |
172 | sockets. The only difference | |
173 | is that | |
174 | .Xr read 2 | |
175 | calls will return only the amount of data requested, | |
176 | and any remaining in the arriving packet will be discarded. | |
177 | .Pp | |
178 | .Dv SOCK_DGRAM | |
179 | and | |
180 | .Dv SOCK_RAW | |
181 | sockets allow sending of datagrams to correspondents | |
182 | named in | |
183 | .Xr send 2 | |
184 | calls. Datagrams are generally received with | |
185 | .Xr recvfrom 2 , | |
186 | which returns the next datagram with its return address. | |
187 | .Pp | |
188 | An | |
189 | .Xr fcntl 2 | |
190 | call can be used to specify a process group to receive | |
191 | a | |
192 | .Dv SIGURG | |
193 | signal when the out-of-band data arrives. | |
194 | It may also enable non-blocking I/O | |
195 | and asynchronous notification of I/O events | |
196 | via | |
197 | .Dv SIGIO . | |
198 | .Pp | |
199 | The operation of sockets is controlled by socket level | |
200 | .Em options . | |
201 | These options are defined in the file | |
202 | .Ao Pa sys/socket.h Ac . | |
203 | .Xr Setsockopt 2 | |
204 | and | |
205 | .Xr getsockopt 2 | |
206 | are used to set and get options, respectively. | |
207 | .Sh RETURN VALUES | |
208 | A -1 is returned if an error occurs, otherwise the return | |
209 | value is a descriptor referencing the socket. | |
210 | .Sh ERRORS | |
211 | The | |
212 | .Fn socket | |
213 | call fails if: | |
214 | .Bl -tag -width EPROTONOPSUPPORTA | |
215 | .It Bq Er EPROTONOSUPPORT | |
216 | The protocol type or the specified protocol is not supported | |
217 | within this domain. | |
218 | .It Bq Er EMFILE | |
219 | The per-process descriptor table is full. | |
220 | .It Bq Er ENFILE | |
221 | The system file table is full. | |
222 | .It Bq Er EACCESS | |
223 | Permission to create a socket of the specified type and/or protocol | |
224 | is denied. | |
225 | .It Bq Er ENOBUFS | |
226 | Insufficient buffer space is available. | |
227 | The socket cannot be created until sufficient resources are freed. | |
228 | .El | |
229 | .Sh SEE ALSO | |
230 | .Xr accept 2 , | |
231 | .Xr bind 2 , | |
232 | .Xr connect 2 , | |
233 | .Xr getprotoent 3 , | |
234 | .Xr getsockname 2 , | |
235 | .Xr getsockopt 2 , | |
236 | .Xr ioctl 2 , | |
237 | .Xr listen 2 , | |
238 | .Xr read 2 , | |
239 | .Xr recv 2 , | |
240 | .Xr select 2 , | |
241 | .Xr send 2 , | |
242 | .Xr shutdown 2 , | |
243 | .Xr socketpair 2 , | |
244 | .Xr write 2 | |
245 | .Rs | |
246 | .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" | |
247 | .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" | |
248 | .Re | |
249 | .Rs | |
250 | .%T "BSD Interprocess Communication Tutorial" | |
251 | .%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" | |
252 | .Re | |
253 | .Sh HISTORY | |
254 | The | |
255 | .Nm | |
256 | function call appeared in | |
257 | .Bx 4.2 . |