Print this page
10067 Miscellaneous man page typos
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Andy Fiddaman <andy@omniosce.org>
Reviewed by: Volker A. Brandt <vab@bb-c.de>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3socket/connect.3socket.man.txt
+++ new/usr/src/man/man3socket/connect.3socket.man.txt
1 1 CONNECT(3SOCKET) Sockets Library Functions CONNECT(3SOCKET)
2 2
3 3
4 4
5 5 NAME
6 6 connect - initiate a connection on a socket
7 7
8 8 SYNOPSIS
9 9 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
10 10 #include <sys/types.h>
11 11 #include <sys/socket.h>
12 12
13 13
14 14
15 15 int connect(int s, const struct sockaddr *name, int namelen);
16 16
17 17
18 18 DESCRIPTION
19 19 The parameter s is a socket. If it is of type SOCK_DGRAM, connect()
20 20 specifies the peer with which the socket is to be associated. This
21 21 address is the address to which datagrams are to be sent if a receiver
22 22 is not explicitly designated. This address is the only address from
23 23 which datagrams are to be received. If the socket s is of type
24 24 SOCK_STREAM, connect() attempts to make a connection to another socket.
25 25 The other socket is specified by name. name is an address in the
26 26 communication space of the socket. Each communication space interprets
27 27 the name parameter in its own way. If s is not bound, then s will be
28 28 bound to an address selected by the underlying transport provider.
29 29 Generally, stream sockets can successfully connect() only once.
30 30 Datagram sockets can use connect() multiple times to change their
31 31 association. Datagram sockets can dissolve the association by
32 32 connecting to a null address.
33 33
34 34 Non-blocking Sockets
35 35 When a socket is created, it is by default a blocking socket. A socket
36 36 may be configured to be non-blocking either at socket creation time or
37 37 through the use of fcntl(2). When a socket is set to be non-blocking, a
38 38 call to connect initiates an asynchronous connection. If the connection
39 39 cannot be completed without blocking, such as when making a TCP
40 40 connection to a remote server, then the connection attempt is made in
41 41 the background and connect returns -1 and errno is set to EINPROGRESS.
42 42
43 43 Applications can obtain the state of this connection attempt by polling
44 44 the socket's file descriptor for POLLOUT. The event ports facility is
45 45 the preferred means of polling on the file descriptor, see
46 46 port_create(3C) and port_get(3C) for more information on event ports;
47 47 however, applications may also use traditional portable routines like
48 48 poll(2) and select(3C).
49 49
50 50 When an asynchronous connection has completed, the application must
51 51 call getsockopt(3SOCKET) using the macro SOL_SOCKET as the level
52 52 argument and the macro SO_ERROR as the value of the option argument.
53 53 If the value of the SO_ERROR socket option is zero, then the connect
54 54 was successfully established. Otherwise, the connection could not be
55 55 established and the value is the corresponding error code that would be
56 56 commonly found in errno.
57 57
58 58 Even when a socket is in non-blocking mode, a call to connect may fail
59 59 synchronously. If any error other EINPROGRESS or EINTR occurs, then
60 60 there is no need for the application to poll for asynchronous
61 61 completion. Similarly, if a call to connect returns successfully, then
62 62 the socket connection will be established and there is no need to poll
63 63 for completion.
64 64
65 65 EXAMPLES
66 66 Example 1 Performing an asynchronous connection
67 67
68 68
69 69 The following sample C program shows how to create and connect to a
70 70 remote host using TCP. The program should be compiled and linked
71 71 against libnsl and libsocket. For example, if the contents of this
72 72 example where in a file called example.c, one would run cc example.c
73 73 -lnsl -lsocket.
74 74
75 75 #include <sys/types.h>
76 76 #include <sys/socket.h>
77 77 #include <netinet/in.h>
78 78 #include <arpa/inet.h>
79 79 #include <inttypes.h>
80 80 #include <stdio.h>
81 81 #include <strings.h>
82 82 #include <stdlib.h>
83 83 #include <errno.h>
84 84 #include <port.h>
85 85 #include <unistd.h>
86 86 #include <assert.h>
87 87
88 88 int
89 89 main(int argc, char *argv[])
90 90 {
91 91 char *eptr;
92 92 long port;
93 93 int sock, ret, eport;
94 94 struct sockaddr_in6 sin6;
95 95
96 96 if (argc != 3) {
97 97 fprintf(stderr, "connect: <IP> <port>\n");
98 98 return (1);
99 99 }
100 100
101 101 bzero(&sin6, sizeof (struct sockaddr_in6));
102 102 sin6.sin6_family = AF_INET6;
103 103
104 104 /*
105 105 * Try to parse as an IPv6 address and then try v4.
106 106 */
107 107 ret = inet_pton(AF_INET6, argv[1], &sin6.sin6_addr);
108 108 if (ret == -1) {
109 109 perror("inet_pton");
110 110 return (1);
111 111 } else if (ret == 0) {
112 112 struct in_addr v4;
113 113 ret = inet_pton(AF_INET, argv[1], &v4);
114 114 if (ret == -1) {
115 115 perror("inet_pton");
116 116 return (1);
117 117 } else if (ret == 0) {
118 118 fprintf(stderr, "connect: %s is not a valid "
119 119 "IPv4 or IPv6 address\n", argv[1]);
120 120 return (1);
121 121 }
122 122 /* N.B. Not a portable macro */
123 123 IN6_INADDR_TO_V4MAPPED(&v4, &sin6.sin6_addr);
124 124 }
125 125
126 126 errno = 0;
127 127 port = strtol(argv[2], &eptr, 10);
128 128 if (errno != 0 || *eptr != '\0') {
129 129 fprintf(stderr, "failed to parse port %s\n", argv[2]);
130 130 return (1);
131 131 }
132 132 if (port <= 0 || port > UINT16_MAX) {
133 133 fprintf(stderr, "invalid port: %ld\n", port);
134 134 return (1);
135 135 }
136 136 sin6.sin6_port = htons(port);
137 137
138 138 sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
139 139 if (sock < 0) {
140 140 perror("socket");
141 141 return (1);
142 142 }
143 143
144 144 eport = port_create();
145 145 if (eport < 0) {
146 146 perror("port_create");
147 147 (void) close(sock);
148 148 return (1);
149 149 }
150 150
151 151 ret = connect(sock, (struct sockaddr *)&sin6,
152 152 sizeof (struct sockaddr_in6));
153 153 if (ret != 0 && errno != EINPROGRESS && errno != EINTR) {
154 154 perror("connect");
155 155 (void) close(sock);
156 156 (void) close(eport);
157 157 return (1);
158 158 }
159 159
160 160 if (ret != 0) {
161 161 port_event_t pe;
162 162 int err;
163 163 socklen_t sz = sizeof (err);
164 164 if (port_associate(eport, PORT_SOURCE_FD, sock, POLLOUT,
165 165 NULL) != 0) {
166 166 perror("port_associate");
167 167 (void) close(sock);
168 168 (void) close(eport);
169 169 return (1);
170 170 }
171 171 if (port_get(eport, &pe, NULL) != 0) {
172 172 perror("port_get");
173 173 (void) close(sock);
174 174 (void) close(eport);
175 175 return (1);
176 176 }
|
↓ open down ↓ |
176 lines elided |
↑ open up ↑ |
177 177 assert(pe.portev_source == PORT_SOURCE_FD);
178 178 assert(pe.portev_object == (uintptr_t)sock);
179 179 if (getsockopt(sock, SOL_SOCKET, SO_ERROR, &err, &sz) != 0) {
180 180 perror("getsockopt");
181 181 (void) close(sock);
182 182 (void) close(eport);
183 183 return (1);
184 184 }
185 185 if (err != 0) {
186 186 /* Asynch connect failed */
187 - fprintf(stderr, "asnchronous connect: %s\n",
187 + fprintf(stderr, "asynchronous connect: %s\n",
188 188 strerror(err));
189 189 (void) close(sock);
190 190 (void) close(eport);
191 191 return (1);
192 192 }
193 193 }
194 194
195 195 /* Read and write to the socket and then clean up */
196 196
197 197 return (0);
198 198 }
199 199
200 200 RETURN VALUES
201 201 If the connection or binding succeeds, 0 is returned. Otherwise, -1 is
202 202 returned and sets errno to indicate the error.
203 203
204 204 ERRORS
205 205 The call fails if:
206 206
207 207 EACCES
208 208 Search permission is denied for a component of the
209 209 path prefix of the pathname in name.
210 210
211 211
212 212 EADDRINUSE
213 213 The address is already in use.
214 214
215 215
216 216 EADDRNOTAVAIL
217 217 The specified address is not available on the remote
218 218 machine.
219 219
220 220
221 221 EAFNOSUPPORT
222 222 Addresses in the specified address family cannot be
223 223 used with this socket.
224 224
225 225
226 226 EALREADY
227 227 The socket is non-blocking, and a previous connection
228 228 attempt has not yet been completed.
229 229
230 230
231 231 EBADF
232 232 s is not a valid descriptor.
233 233
234 234
235 235 ECONNREFUSED
236 236 The attempt to connect was forcefully rejected. The
237 237 calling program should close(2) the socket descriptor,
238 238 and issue another socket(3SOCKET) call to obtain a new
239 239 descriptor before attempting another connect() call.
240 240
241 241
242 242 EINPROGRESS
243 243 The socket is non-blocking, and the connection cannot
244 244 be completed immediately. See the section on Non-
245 245 blocking Sockets for more information.
246 246
247 247
248 248 EINTR
249 249 The connection attempt was interrupted before any data
250 250 arrived by the delivery of a signal. The connection,
251 251 however, will be established asynchronously.
252 252
253 253
254 254 EINVAL
255 255 namelen is not the size of a valid address for the
256 256 specified address family.
257 257
258 258
259 259 EIO
260 260 An I/O error occurred while reading from or writing to
261 261 the file system.
262 262
263 263
264 264 EISCONN
265 265 The socket is already connected.
266 266
267 267
268 268 ELOOP
269 269 Too many symbolic links were encountered in
270 270 translating the pathname in name.
271 271
272 272
273 273 ENETUNREACH
274 274 The network is not reachable from this host.
275 275
276 276
277 277 EHOSTUNREACH
278 278 The remote host is not reachable from this host.
279 279
280 280
281 281 ENOENT
282 282 A component of the path prefix of the pathname in name
283 283 does not exist.
284 284
285 285
286 286 ENOENT
287 287 The socket referred to by the pathname in name does
288 288 not exist.
289 289
290 290
291 291 ENOSR
292 292 There were insufficient STREAMS resources available to
293 293 complete the operation.
294 294
295 295
296 296 ENXIO
297 297 The server exited before the connection was complete.
298 298
299 299
300 300 ETIMEDOUT
301 301 Connection establishment timed out without
302 302 establishing a connection.
303 303
304 304
305 305 EWOULDBLOCK
306 306 The socket is marked as non-blocking, and the
307 307 requested operation would block.
308 308
309 309
310 310
311 311 The following errors are specific to connecting names in the UNIX
312 312 domain. These errors might not apply in future versions of the UNIX
313 313 IPC domain.
314 314
315 315 ENOTDIR
316 316 A component of the path prefix of the pathname in name is
317 317 not a directory.
318 318
319 319
320 320 ENOTSOCK
321 321 s is not a socket.
322 322
323 323
324 324 ENOTSOCK
325 325 name is not a socket.
326 326
327 327
328 328 EPROTOTYPE
329 329 The file that is referred to by name is a socket of a
330 330 type other than type s. For example, s is a SOCK_DGRAM
331 331 socket, while name refers to a SOCK_STREAM socket.
332 332
333 333
334 334 ATTRIBUTES
335 335 See attributes(5) for descriptions of the following attributes:
336 336
337 337
338 338
339 339
340 340 +---------------+-----------------+
341 341 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
342 342 +---------------+-----------------+
343 343 |MT-Level | Safe |
344 344 +---------------+-----------------+
345 345
346 346 SEE ALSO
347 347 close(2), accept(3SOCKET), getsockname(3SOCKET), select(3C),
348 348 socket(3SOCKET), sockaddr(3SOCKET), socket.h(3HEAD), attributes(5)
349 349
350 350
351 351
352 352 November 25, 2014 CONNECT(3SOCKET)
|
↓ open down ↓ |
155 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX