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
+++ new/usr/src/man/man3socket/connect.3socket
1 1 '\" te
2 2 .\" Copyright (C) 2005, Sun Microsystems, Inc.
3 3 .\" All Rights Reserved
4 4 .\" Copyright (c) 2014, Joyent, Inc.
5 5 .\" Copyright 1989 AT&T All Rights Reserved
6 6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
7 7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
8 8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
9 9 .TH CONNECT 3SOCKET "Nov 25, 2014"
10 10 .SH NAME
11 11 connect \- initiate a connection on a socket
12 12 .SH SYNOPSIS
13 13 .LP
14 14 .nf
15 15 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
16 16 #include <sys/types.h>
17 17 #include <sys/socket.h>
18 18
19 19
20 20
21 21 \fBint\fR \fBconnect\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
22 22 .fi
23 23
24 24 .SH DESCRIPTION
25 25 .LP
26 26 The parameter \fIs\fR is a socket. If it is of type \fBSOCK_DGRAM\fR,
27 27 \fBconnect()\fR specifies the peer with which the socket is to be associated.
28 28 This address is the address to which datagrams are to be sent if a receiver is
29 29 not explicitly designated. This address is the only address from which
30 30 datagrams are to be received. If the socket \fIs\fR is of type
31 31 \fBSOCK_STREAM\fR, \fBconnect()\fR attempts to make a connection to another
32 32 socket. The other socket is specified by \fIname\fR. \fIname\fR is an address
33 33 in the communication space of the socket. Each communication space interprets
34 34 the \fIname\fR parameter in its own way. If \fIs\fR is not bound, then \fIs\fR
35 35 will be bound to an address selected by the underlying transport provider.
36 36 Generally, stream sockets can successfully \fBconnect()\fR only once. Datagram
37 37 sockets can use \fBconnect()\fR multiple times to change their association.
38 38 Datagram sockets can dissolve the association by connecting to a null address.
39 39 .SS Non-blocking Sockets
40 40 When a socket is created, it is by default a \fBblocking\fR socket. A socket may
41 41 be configured to be \fBnon-blocking\fR either at socket creation time or through
42 42 the use of \fBfcntl\fR(2). When a socket is set to be \fBnon-blocking\fR, a call
43 43 to connect initiates an asynchronous connection. If the connection cannot be
44 44 completed without blocking, such as when making a TCP connection to a remote
45 45 server, then the connection attempt is made in the background and \fBconnect\fR
46 46 returns -1 and errno is set to \fBEINPROGRESS\fR.
47 47 .LP
48 48 Applications can obtain the state of this connection attempt by polling the
49 49 socket's file descriptor for \fBPOLLOUT\fR. The event ports facility is the
50 50 preferred means of polling on the file descriptor, see \fBport_create\fR(3C) and
51 51 \fBport_get\fR(3C) for more information on event ports; however, applications
52 52 may also use traditional portable routines like \fBpoll\fR(2) and
53 53 \fBselect\fR(3C).
54 54 .LP
55 55 When an asynchronous connection has completed, the application must call
56 56 \fBgetsockopt\fR(3SOCKET) using the macro \fBSOL_SOCKET\fR as the \fIlevel\fR
57 57 argument and the macro \fBSO_ERROR\fR as the value of the \fIoption\fR argument.
58 58 If the value of the \fBSO_ERROR\fR socket option is zero, then the
59 59 connect was successfully established. Otherwise, the connection could not be
60 60 established and the value is the corresponding error code that would be commonly
61 61 found in \fBerrno\fR.
62 62 .LP
63 63 Even when a socket is in \fBnon-blocking\fR mode, a call to \fBconnect\fR may
64 64 fail synchronously. If any error other \fBEINPROGRESS\fR or \fBEINTR\fR occurs,
65 65 then there is no need for the application to poll for asynchronous completion.
66 66 Similarly, if a call to \fBconnect\fR returns successfully, then the socket
67 67 connection will be established and there is no need to poll for completion.
68 68 .SH EXAMPLES
69 69 .LP
70 70 \fBExample 1\fR Performing an asynchronous connection
71 71 .sp
72 72 .LP
73 73 The following sample C program shows how to create and connect to a remote host
74 74 using TCP. The program should be compiled and linked against libnsl and
75 75 libsocket. For example, if the contents of this example where in a file called
76 76 example.c, one would run cc example.c -lnsl -lsocket.
77 77 .sp
78 78 .in +2
79 79 .nf
80 80 #include <sys/types.h>
81 81 #include <sys/socket.h>
82 82 #include <netinet/in.h>
83 83 #include <arpa/inet.h>
84 84 #include <inttypes.h>
85 85 #include <stdio.h>
86 86 #include <strings.h>
87 87 #include <stdlib.h>
88 88 #include <errno.h>
89 89 #include <port.h>
90 90 #include <unistd.h>
91 91 #include <assert.h>
92 92
93 93 int
94 94 main(int argc, char *argv[])
95 95 {
96 96 char *eptr;
97 97 long port;
98 98 int sock, ret, eport;
99 99 struct sockaddr_in6 sin6;
100 100
101 101 if (argc != 3) {
102 102 fprintf(stderr, "connect: <IP> <port>\\n");
103 103 return (1);
104 104 }
105 105
106 106 bzero(&sin6, sizeof (struct sockaddr_in6));
107 107 sin6.sin6_family = AF_INET6;
108 108
109 109 /*
110 110 * Try to parse as an IPv6 address and then try v4.
111 111 */
112 112 ret = inet_pton(AF_INET6, argv[1], &sin6.sin6_addr);
113 113 if (ret == -1) {
114 114 perror("inet_pton");
115 115 return (1);
116 116 } else if (ret == 0) {
117 117 struct in_addr v4;
118 118 ret = inet_pton(AF_INET, argv[1], &v4);
119 119 if (ret == -1) {
120 120 perror("inet_pton");
121 121 return (1);
122 122 } else if (ret == 0) {
123 123 fprintf(stderr, "connect: %s is not a valid "
124 124 "IPv4 or IPv6 address\\n", argv[1]);
125 125 return (1);
126 126 }
127 127 /* N.B. Not a portable macro */
128 128 IN6_INADDR_TO_V4MAPPED(&v4, &sin6.sin6_addr);
129 129 }
130 130
131 131 errno = 0;
132 132 port = strtol(argv[2], &eptr, 10);
133 133 if (errno != 0 || *eptr != '\e0') {
134 134 fprintf(stderr, "failed to parse port %s\\n", argv[2]);
135 135 return (1);
136 136 }
137 137 if (port <= 0 || port > UINT16_MAX) {
138 138 fprintf(stderr, "invalid port: %ld\\n", port);
139 139 return (1);
140 140 }
141 141 sin6.sin6_port = htons(port);
142 142
143 143 sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
144 144 if (sock < 0) {
145 145 perror("socket");
146 146 return (1);
147 147 }
148 148
149 149 eport = port_create();
150 150 if (eport < 0) {
151 151 perror("port_create");
152 152 (void) close(sock);
153 153 return (1);
154 154 }
155 155
156 156 ret = connect(sock, (struct sockaddr *)&sin6,
157 157 sizeof (struct sockaddr_in6));
158 158 if (ret != 0 && errno != EINPROGRESS && errno != EINTR) {
159 159 perror("connect");
160 160 (void) close(sock);
161 161 (void) close(eport);
162 162 return (1);
163 163 }
164 164
165 165 if (ret != 0) {
166 166 port_event_t pe;
167 167 int err;
168 168 socklen_t sz = sizeof (err);
169 169 if (port_associate(eport, PORT_SOURCE_FD, sock, POLLOUT,
170 170 NULL) != 0) {
171 171 perror("port_associate");
172 172 (void) close(sock);
173 173 (void) close(eport);
174 174 return (1);
175 175 }
176 176 if (port_get(eport, &pe, NULL) != 0) {
177 177 perror("port_get");
178 178 (void) close(sock);
179 179 (void) close(eport);
180 180 return (1);
181 181 }
|
↓ open down ↓ |
181 lines elided |
↑ open up ↑ |
182 182 assert(pe.portev_source == PORT_SOURCE_FD);
183 183 assert(pe.portev_object == (uintptr_t)sock);
184 184 if (getsockopt(sock, SOL_SOCKET, SO_ERROR, &err, &sz) != 0) {
185 185 perror("getsockopt");
186 186 (void) close(sock);
187 187 (void) close(eport);
188 188 return (1);
189 189 }
190 190 if (err != 0) {
191 191 /* Asynch connect failed */
192 - fprintf(stderr, "asnchronous connect: %s\\n",
192 + fprintf(stderr, "asynchronous connect: %s\\n",
193 193 strerror(err));
194 194 (void) close(sock);
195 195 (void) close(eport);
196 196 return (1);
197 197 }
198 198 }
199 199
200 200 /* Read and write to the socket and then clean up */
201 201
202 202 return (0);
203 203 }
204 204 .fi
205 205 .in -2
206 206 .SH RETURN VALUES
207 207 .LP
208 208 If the connection or binding succeeds, \fB0\fR is returned. Otherwise,
209 209 \fB\(mi1\fR is returned and sets \fBerrno\fR to indicate the error.
210 210 .SH ERRORS
211 211 .LP
212 212 The call fails if:
213 213 .sp
214 214 .ne 2
215 215 .na
216 216 \fB\fBEACCES\fR\fR
217 217 .ad
218 218 .RS 17n
219 219 Search permission is denied for a component of the path prefix of the pathname
220 220 in \fIname\fR.
221 221 .RE
222 222
223 223 .sp
224 224 .ne 2
225 225 .na
226 226 \fB\fBEADDRINUSE\fR\fR
227 227 .ad
228 228 .RS 17n
229 229 The address is already in use.
230 230 .RE
231 231
232 232 .sp
233 233 .ne 2
234 234 .na
235 235 \fB\fBEADDRNOTAVAIL\fR\fR
236 236 .ad
237 237 .RS 17n
238 238 The specified address is not available on the remote machine.
239 239 .RE
240 240
241 241 .sp
242 242 .ne 2
243 243 .na
244 244 \fB\fBEAFNOSUPPORT\fR\fR
245 245 .ad
246 246 .RS 17n
247 247 Addresses in the specified address family cannot be used with this socket.
248 248 .RE
249 249
250 250 .sp
251 251 .ne 2
252 252 .na
253 253 \fB\fBEALREADY\fR\fR
254 254 .ad
255 255 .RS 17n
256 256 The socket is non-blocking, and a previous connection attempt has not yet been
257 257 completed.
258 258 .RE
259 259
260 260 .sp
261 261 .ne 2
262 262 .na
263 263 \fB\fBEBADF\fR\fR
264 264 .ad
265 265 .RS 17n
266 266 \fIs\fR is not a valid descriptor.
267 267 .RE
268 268
269 269 .sp
270 270 .ne 2
271 271 .na
272 272 \fB\fBECONNREFUSED\fR\fR
273 273 .ad
274 274 .RS 17n
275 275 The attempt to connect was forcefully rejected. The calling program should
276 276 \fBclose\fR(2) the socket descriptor, and issue another \fBsocket\fR(3SOCKET)
277 277 call to obtain a new descriptor before attempting another \fBconnect()\fR call.
278 278 .RE
279 279
280 280 .sp
281 281 .ne 2
282 282 .na
283 283 \fB\fBEINPROGRESS\fR\fR
284 284 .ad
285 285 .RS 17n
286 286 The socket is non-blocking, and the connection cannot be completed immediately.
287 287 See the section on \fBNon-blocking Sockets\fR for more information.
288 288 .RE
289 289
290 290 .sp
291 291 .ne 2
292 292 .na
293 293 \fB\fBEINTR\fR\fR
294 294 .ad
295 295 .RS 17n
296 296 The connection attempt was interrupted before any data arrived by the delivery
297 297 of a signal. The connection, however, will be established asynchronously.
298 298 .RE
299 299
300 300 .sp
301 301 .ne 2
302 302 .na
303 303 \fB\fBEINVAL\fR\fR
304 304 .ad
305 305 .RS 17n
306 306 \fInamelen\fR is not the size of a valid address for the specified address
307 307 family.
308 308 .RE
309 309
310 310 .sp
311 311 .ne 2
312 312 .na
313 313 \fB\fBEIO\fR\fR
314 314 .ad
315 315 .RS 17n
316 316 An I/O error occurred while reading from or writing to the file system.
317 317 .RE
318 318
319 319 .sp
320 320 .ne 2
321 321 .na
322 322 \fB\fBEISCONN\fR\fR
323 323 .ad
324 324 .RS 17n
325 325 The socket is already connected.
326 326 .RE
327 327
328 328 .sp
329 329 .ne 2
330 330 .na
331 331 \fB\fBELOOP\fR\fR
332 332 .ad
333 333 .RS 17n
334 334 Too many symbolic links were encountered in translating the pathname in
335 335 \fIname\fR.
336 336 .RE
337 337
338 338 .sp
339 339 .ne 2
340 340 .na
341 341 \fB\fBENETUNREACH\fR\fR
342 342 .ad
343 343 .RS 17n
344 344 The network is not reachable from this host.
345 345 .RE
346 346
347 347 .sp
348 348 .ne 2
349 349 .na
350 350 \fB\fBEHOSTUNREACH\fR\fR
351 351 .ad
352 352 .RS 17n
353 353 The remote host is not reachable from this host.
354 354 .RE
355 355
356 356 .sp
357 357 .ne 2
358 358 .na
359 359 \fB\fBENOENT\fR\fR
360 360 .ad
361 361 .RS 17n
362 362 A component of the path prefix of the pathname in \fIname\fR does not exist.
363 363 .RE
364 364
365 365 .sp
366 366 .ne 2
367 367 .na
368 368 \fB\fBENOENT\fR\fR
369 369 .ad
370 370 .RS 17n
371 371 The socket referred to by the pathname in \fIname\fR does not exist.
372 372 .RE
373 373
374 374 .sp
375 375 .ne 2
376 376 .na
377 377 \fB\fBENOSR\fR\fR
378 378 .ad
379 379 .RS 17n
380 380 There were insufficient \fBSTREAMS\fR resources available to complete the
381 381 operation.
382 382 .RE
383 383
384 384 .sp
385 385 .ne 2
386 386 .na
387 387 \fB\fBENXIO\fR\fR
388 388 .ad
389 389 .RS 17n
390 390 The server exited before the connection was complete.
391 391 .RE
392 392
393 393 .sp
394 394 .ne 2
395 395 .na
396 396 \fB\fBETIMEDOUT\fR\fR
397 397 .ad
398 398 .RS 17n
399 399 Connection establishment timed out without establishing a connection.
400 400 .RE
401 401
402 402 .sp
403 403 .ne 2
404 404 .na
405 405 \fB\fBEWOULDBLOCK\fR\fR
406 406 .ad
407 407 .RS 17n
408 408 The socket is marked as non-blocking, and the requested operation would block.
409 409 .RE
410 410
411 411 .sp
412 412 .LP
413 413 The following errors are specific to connecting names in the UNIX domain.
414 414 These errors might not apply in future versions of the UNIX \fBIPC\fR domain.
415 415 .sp
416 416 .ne 2
417 417 .na
418 418 \fB\fBENOTDIR\fR\fR
419 419 .ad
420 420 .RS 14n
421 421 A component of the path prefix of the pathname in \fIname\fR is not a
422 422 directory.
423 423 .RE
424 424
425 425 .sp
426 426 .ne 2
427 427 .na
428 428 \fB\fBENOTSOCK\fR\fR
429 429 .ad
430 430 .RS 14n
431 431 \fIs\fR is not a socket.
432 432 .RE
433 433
434 434 .sp
435 435 .ne 2
436 436 .na
437 437 \fB\fBENOTSOCK\fR\fR
438 438 .ad
439 439 .RS 14n
440 440 \fIname\fR is not a socket.
441 441 .RE
442 442
443 443 .sp
444 444 .ne 2
445 445 .na
446 446 \fB\fBEPROTOTYPE\fR\fR
447 447 .ad
448 448 .RS 14n
449 449 The file that is referred to by \fIname\fR is a socket of a type other than
450 450 type \fIs\fR. For example, \fIs\fR is a \fBSOCK_DGRAM\fR socket, while
451 451 \fIname\fR refers to a \fBSOCK_STREAM\fR socket.
452 452 .RE
453 453
454 454 .SH ATTRIBUTES
455 455 .LP
456 456 See \fBattributes\fR(5) for descriptions of the following attributes:
457 457 .sp
458 458
459 459 .sp
460 460 .TS
461 461 box;
462 462 c | c
463 463 l | l .
464 464 ATTRIBUTE TYPE ATTRIBUTE VALUE
465 465 _
466 466 MT-Level Safe
467 467 .TE
468 468
469 469 .SH SEE ALSO
470 470 .LP
471 471 \fBclose\fR(2), \fBaccept\fR(3SOCKET), \fBgetsockname\fR(3SOCKET),
472 472 \fBselect\fR(3C), \fBsocket\fR(3SOCKET), \fBsockaddr\fR(3SOCKET),
473 473 \fBsocket.h\fR(3HEAD), \fBattributes\fR(5)
|
↓ open down ↓ |
271 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX