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