| blob | 781dcf14f10b92d03c8db39c6c8a98c7fd6200e3 |
1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved.
3 .\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
6 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
7 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" 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.
10 .\" 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.
11 .\" 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]
12 .TH SOCKET.H 3HEAD "Jan 28, 2009"
13 .SH NAME
14 socket.h, socket \- Internet Protocol family
15 .SH SYNOPSIS
16 .LP
17 .nf
18 \fB#include <sys/socket.h>\fR
19 .fi
21 .SH DESCRIPTION
22 .LP
23 The \fB<sys/socket.h>\fR header defines the unsigned integral type
24 \fBsa_family_t\fR through \fBtypedef\fR.
25 .sp
26 .LP
27 The \fB<sys/socket.h>\fR header defines the \fBsockaddr\fR structure that
28 includes the following members:
29 .sp
30 .in +2
31 .nf
32 sa_family_t sa_family /* address family */
33 char sa_data[] /* socket address (variable-length
34 data) */
35 .fi
36 .in -2
38 .SS "\fBlibxnet\fR Interfaces"
39 .LP
40 The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
41 \fBlibxnet\fR interfaces that includes the following members:
42 .sp
43 .in +2
44 .nf
45 void *msg_name /* optional address */
46 socklen_t msg_namelen /* size of address */
47 struct iovec *msg_iov /* scatter/gather array */
48 int msg_iovlen /* members in msg_iov */
49 void *msg_control /* ancillary data, see below */
50 socklen_t msg_controllen /* ancillary data buffer len */
51 int msg_flags /* flags on received message */
52 .fi
53 .in -2
55 .sp
56 .LP
57 The \fB<sys/socket.h>\fR header defines the \fBcmsghdr\fR structure for
58 \fBlibxnet\fR that includes the following members:
59 .sp
60 .in +2
61 .nf
62 socklen_t cmsg_len /* data byte count, including hdr */
63 int cmsg_level /* originating protocol */
64 int cmsg_type /* protocol-specific type */
65 .fi
66 .in -2
68 .sp
69 .LP
70 Ancillary data consists of a sequence of pairs, each consisting of a
71 \fBcmsghdr\fR structure followed by a data array. The data array contains the
72 ancillary data message, and the \fBcmsghdr\fR structure contains descriptive
73 information that allows an application to correctly parse the data.
74 .sp
75 .LP
76 The values for \fBcmsg_level\fR will be legal values for the level argument to
77 the \fBgetsockopt()\fR and \fBsetsockopt()\fR functions. The \fBSCM_RIGHTS\fR
78 type is supported for level \fBSOL_SOCKET\fR.
79 .sp
80 .LP
81 Ancillary data is also possible at the socket level. The \fB<sys/socket.h>\fR
82 header defines the following macros for use as the \fBcmsg_type\fR values when
83 \fBcmsg_level\fR is \fBSOL_SOCKET\fR.
84 .sp
85 .ne 2
86 .na
87 \fB\fBSCM_RIGHTS\fR\fR
88 .ad
89 .RS 14n
90 Indicates that the data array contains the access rights to be sent or
91 received.
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fBSCM_UCRED\fR\fR
98 .ad
99 .RS 14n
100 Indicates that the data array contains a \fBucred_t\fR to be received. The
101 \fBucred_t\fR is the credential of the sending process at the time the message
102 was sent. This is a Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
103 .RE
105 .sp
106 .LP
107 The IPv4 data formats generally use the same values for data passed back in
108 \fBcmsghdr\fR as for \fBsetsockopt()\fR to enable the feature. The IPv4 data
109 formats are listed below with the associated payload for each.
110 .sp
111 .ne 2
112 .na
113 \fB\fBIPPROTO_IP\fR\fR
114 .ad
115 .br
116 .na
117 \fB\fBIP_RECVDSTADDR\fR\fR
118 .ad
119 .sp .6
120 .RS 4n
121 \fBipaddr_t\fR, IP address
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBIPPROTO_IP\fR\fR
128 .ad
129 .br
130 .na
131 \fB\fBIP_RECVOPTS\fR\fR
132 .ad
133 .sp .6
134 .RS 4n
135 variable-length IP options, up to 40 bytes
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBIPPROTO_IP\fR\fR
142 .ad
143 .br
144 .na
145 \fB\fBIP_RECVIF\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 \fBuint_t\fR, \fBifIndex\fR number
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBIPPROTO_IP\fR\fR
156 .ad
157 .br
158 .na
159 \fB\fBIP_RECVSLLA\fR\fR
160 .ad
161 .sp .6
162 .RS 4n
163 \fBstruct sockaddr_dl\fR, link layer address
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBIPPROTO_IP\fR\fR
170 .ad
171 .br
172 .na
173 \fB\fBIP_RECVTTL\fR\fR
174 .ad
175 .sp .6
176 .RS 4n
177 \fBuint8_t\fR
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fBSOL_SOCKET\fR\fR
184 .ad
185 .br
186 .na
187 \fB\fBSO_RECVUCRED\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 \fBucred_t\fR \(em \fBcmsghdr.cmsg_type\fR is \fBSCM_UCRED\fR, not
192 \fBSO_RECVUCRED\fR
193 .RE
195 .sp
196 .LP
197 The IPv6 data formats use different values for enabling the option and for
198 passing the value back to the application. The IPv6 data formats are listed
199 below with the associated payload for each.
200 .sp
201 .ne 2
202 .na
203 \fB\fBIPPROTO_IPV6\fR\fR
204 .ad
205 .br
206 .na
207 \fB\fBIPV6_RECVPKTINFO\fR\fR
208 .ad
209 .sp .6
210 .RS 4n
211 \fBin_pktinfo\fR, \fBcmsg_type\fR \fBIPV6_PKTINFO\fR
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fBIPPROTO_IPV6\fR\fR
218 .ad
219 .br
220 .na
221 \fB\fBIPV6_RECVTCLASS\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 \fBuint_t\fR, \fBcmsg_type\fR \fBIPV6_TCLASS\fR
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBIPPROTO_IPV6\fR\fR
232 .ad
233 .br
234 .na
235 \fB\fBIPV6_RECVPATHMTU\fR\fR
236 .ad
237 .sp .6
238 .RS 4n
239 \fBip6_mtuinfo\fR, \fBcmsg_type\fR \fBIPV6_PATHMTU\fR
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fBIPPROTO_IPV6\fR\fR
246 .ad
247 .br
248 .na
249 \fB\fBIPV6_RECVHOPLIMIT\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
253 \fBuint_t\fR, \fBcmsg_type\fR \fBIPV6_HOPLIMIT\fR
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fBIPPROTO_IPV6\fR\fR
260 .ad
261 .br
262 .na
263 \fB\fBIPV6_RECVHOPOPTS\fR\fR
264 .ad
265 .sp .6
266 .RS 4n
267 variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_HOPOPTS\fR
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBIPPROTO_IPV6\fR\fR
274 .ad
275 .br
276 .na
277 \fB\fBIPV6_RECVDSTOPTS\fR\fR
278 .ad
279 .sp .6
280 .RS 4n
281 variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_DSTOPTS\fR
282 .RE
284 .sp
285 .ne 2
286 .na
287 \fB\fBIPPROTO_IPV6\fR\fR
288 .ad
289 .br
290 .na
291 \fB\fBIPV6_RECVRTHDR\fR\fR
292 .ad
293 .sp .6
294 .RS 4n
295 variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_RTHDR\fR
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBIPPROTO_IPV6\fR\fR
302 .ad
303 .br
304 .na
305 \fB\fBIPV6_RECVRTHDRDSTOPTS\fR\fR
306 .ad
307 .sp .6
308 .RS 4n
309 variable-length IPv6 options, \fBcmsg_type\fR \fBIPV6_DSTOPTS\fR
310 .RE
312 .sp
313 .LP
314 The \fB<sys/socket.h>\fR header defines the following macros to gain access to
315 the data arrays in the ancillary data associated with a message header:
316 .sp
317 .ne 2
318 .na
319 \fB\fBCMSG_DATA(\fR\fIcmsg\fR)\fR
320 .ad
321 .sp .6
322 .RS 4n
323 If the argument is a pointer to a \fBcmsghdr\fR structure, this macro returns
324 an unsigned character pointer to the data array associated with the
325 \fBcmsghdr\fR structure.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBCMSG_NXTHDR(\fR\fImhdr\fR, \fIcmsg\fR)\fR
332 .ad
333 .sp .6
334 .RS 4n
335 If the first argument is a pointer to a \fBmsghdr\fR structure and the second
336 argument is a pointer to a \fBcmsghdr\fR structure in the ancillary data,
337 pointed to by the \fBmsg_control\fR field of that \fBmsghdr\fR structure, this
338 macro returns a pointer to the next \fBcmsghdr\fR structure, or a null pointer
339 if this structure is the last \fBcmsghdr\fR in the ancillary data.
340 .RE
342 .sp
343 .ne 2
344 .na
345 \fB\fBCMSG_FIRSTHDR(\fR\fImhdr\fR)\fR
346 .ad
347 .sp .6
348 .RS 4n
349 If the argument is a pointer to a \fBmsghdr\fR structure, this macro returns a
350 pointer to the first \fBcmsghdr\fR structure in the ancillary data associated
351 with this \fBmsghdr\fR structure, or a null pointer if there is no ancillary
352 data associated with the \fBmsghdr\fR structure.
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fB\fBCMSG_SPACE\fR(\fIlen\fR)\fR
359 .ad
360 .sp .6
361 .RS 4n
362 Given the length of an ancillary data object, \fBCMSG_SPACE()\fR returns the
363 space required by the object and its \fBcmsghdr\fR structure, including any
364 padding needed to satisfy alignment requirements. This macro can be used, for
365 example, to allocate space dynamically for the ancillary data. This macro
366 should not be used to initialize the \fBcmsg_len\fR member of a \fBcmsghdr\fR
367 structure. Use the \fBCMSG_LEN()\fR macro instead.
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fB\fBCMSG_LEN\fR(\fIlen\fR)\fR
374 .ad
375 .sp .6
376 .RS 4n
377 Given the length of an ancillary data object, \fBCMSG_LEN()\fR returns the
378 value to store in the cmsg_len member of the \fBcmsghdr\fR structure, taking
379 into account any padding needed to satisfy alignment requirements.
380 .RE
382 .sp
383 .LP
384 The \fB<sys/socket.h>\fR header defines the \fBlinger\fR structure that
385 includes the following members:
386 .sp
387 .in +2
388 .nf
389 int l_onoff /* indicates whether linger option is enabled */
390 int l_linger /* linger time, in seconds */
391 .fi
392 .in -2
394 .sp
395 .LP
396 The \fB<sys/socket.h>\fR header defines the following macros:
397 .sp
398 .ne 2
399 .na
400 \fB\fBSOCK_DGRAM\fR\fR
401 .ad
402 .RS 18n
403 Datagram socket
404 .RE
406 .sp
407 .ne 2
408 .na
409 \fB\fBSOCK_STREAM\fR\fR
410 .ad
411 .RS 18n
412 Byte-stream socket
413 .RE
415 .sp
416 .ne 2
417 .na
418 \fB\fBSOCK_SEQPACKET\fR\fR
419 .ad
420 .RS 18n
421 Sequenced-packet socket
422 .RE
424 .sp
425 .LP
426 The \fB<sys/socket.h>\fR header defines the following macros for use as the
427 \fIlevel\fR argument of \fBsetsockopt()\fR and \fBgetsockopt()\fR.
428 .sp
429 .ne 2
430 .na
431 \fB\fBSOL_SOCKET\fR\fR
432 .ad
433 .RS 14n
434 Options to be accessed at the socket level, not the protocol level.
435 .RE
437 .sp
438 .ne 2
439 .na
440 \fB\fBSOL_ROUTE\fR\fR
441 .ad
442 .RS 14n
443 Options to be accessed at the routing socket level, not the protocol level.
444 .RE
446 .sp
447 .LP
448 The \fB<sys/socket.h>\fR header defines the following macros for use as the
449 \fIoption_name\fR argument of \fBgetsockopt()\fR or \fBsetsockopt()\fR calls:
450 .sp
451 .ne 2
452 .na
453 \fB\fBSO_DEBUG\fR\fR
454 .ad
455 .RS 17n
456 Debugging information is being recorded.
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fBSO_ACCEPTCONN\fR\fR
463 .ad
464 .RS 17n
465 Socket is accepting connections.
466 .RE
468 .sp
469 .ne 2
470 .na
471 \fB\fBSO_BROADCAST\fR\fR
472 .ad
473 .RS 17n
474 Transmission of broadcast messages is supported.
475 .RE
477 .sp
478 .ne 2
479 .na
480 \fB\fBSO_REUSEADDR\fR\fR
481 .ad
482 .RS 17n
483 Reuse of local addresses is supported.
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fBSO_KEEPALIVE\fR\fR
490 .ad
491 .RS 17n
492 Connections are kept alive with periodic messages.
493 .RE
495 .sp
496 .ne 2
497 .na
498 \fB\fBSO_LINGER\fR\fR
499 .ad
500 .RS 17n
501 Socket lingers on close.
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fB\fBSO_OOBINLINE\fR\fR
508 .ad
509 .RS 17n
510 Out-of-band data is transmitted in line.
511 .RE
513 .sp
514 .ne 2
515 .na
516 \fB\fBSO_SNDBUF\fR\fR
517 .ad
518 .RS 17n
519 Send buffer size.
520 .RE
522 .sp
523 .ne 2
524 .na
525 \fB\fBSO_RCVBUF\fR\fR
526 .ad
527 .RS 17n
528 Receive buffer size.
529 .RE
531 .sp
532 .ne 2
533 .na
534 \fB\fBSO_ERROR\fR\fR
535 .ad
536 .RS 17n
537 Socket error status.
538 .RE
540 .sp
541 .ne 2
542 .na
543 \fB\fBSO_TYPE\fR\fR
544 .ad
545 .RS 17n
546 Socket type.
547 .RE
549 .sp
550 .ne 2
551 .na
552 \fB\fBSO_RECVUCRED\fR\fR
553 .ad
554 .RS 17n
555 Request the reception of user credential ancillary data. This is a
556 Sun-specific, Evolving interface. See \fBucred_get\fR(3C).
557 .RE
559 .sp
560 .ne 2
561 .na
562 \fB\fBSO_MAC_EXEMPT\fR\fR
563 .ad
564 .RS 17n
565 Mandatory Access Control (\fBMAC\fR) exemption for unlabeled peers. This option
566 is available only if the system is configured with Trusted Extensions.
567 .RE
569 .sp
570 .ne 2
571 .na
572 \fB\fBSO_ALLZONES\fR\fR
573 .ad
574 .RS 17n
575 Bypass zone boundaries (privileged).
576 .RE
578 .sp
579 .LP
580 The \fB<sys/socket.h>\fR header defines the following macros for use as the
581 valid values for the \fBmsg_flags\fR field in the \fBmsghdr\fR structure, or
582 the flags parameter in \fBrecvfrom()\fR, \fBrecvmsg()\fR, \fBsendto()\fR, or
583 \fBsendmsg()\fR calls:
584 .sp
585 .ne 2
586 .na
587 \fB\fBMSG_CTRUNC\fR\fR
588 .ad
589 .RS 15n
590 Control data truncated.
591 .RE
593 .sp
594 .ne 2
595 .na
596 \fB\fBMSG_EOR\fR\fR
597 .ad
598 .RS 15n
599 Terminates a record (if supported by the protocol).
600 .RE
602 .sp
603 .ne 2
604 .na
605 \fB\fBMSG_OOB\fR\fR
606 .ad
607 .RS 15n
608 Out-of-band data.
609 .RE
611 .sp
612 .ne 2
613 .na
614 \fB\fBMSG_PEEK\fR\fR
615 .ad
616 .RS 15n
617 Leave received data in queue.
618 .RE
620 .sp
621 .ne 2
622 .na
623 \fB\fBMSG_TRUNC\fR\fR
624 .ad
625 .RS 15n
626 Normal data truncated.
627 .RE
629 .sp
630 .ne 2
631 .na
632 \fB\fBMSG_WAITALL\fR\fR
633 .ad
634 .RS 15n
635 Wait for complete message.
636 .RE
638 .sp
639 .LP
640 The \fB<sys/socket.h>\fR header defines the following macros:
641 .sp
642 .ne 2
643 .na
644 \fB\fBAF_UNIX\fR\fR
645 .ad
646 .RS 11n
647 UNIX domain sockets
648 .RE
650 .sp
651 .ne 2
652 .na
653 \fB\fBAF_INET\fR\fR
654 .ad
655 .RS 11n
656 Internet domain sockets
657 .RE
659 .sp
660 .LP
661 The \fB<sys/socket.h>\fR header defines the following macros:
662 .sp
663 .ne 2
664 .na
665 \fB\fBSHUT_RD\fR\fR
666 .ad
667 .RS 13n
668 Disables further receive operations.
669 .RE
671 .sp
672 .ne 2
673 .na
674 \fB\fBSHUT_WR\fR\fR
675 .ad
676 .RS 13n
677 Disables further send operations.
678 .RE
680 .sp
681 .ne 2
682 .na
683 \fB\fBSHUT_RDWR\fR\fR
684 .ad
685 .RS 13n
686 Disables further send and receive operations.
687 .RE
689 .SS "\fBlibsocket\fR Interfaces"
690 .LP
691 The \fB<sys/socket.h>\fR header defines the \fBmsghdr\fR structure for
692 \fBlibsocket\fR interfaces that includes the following members:
693 .sp
694 .in +2
695 .nf
696 void *msg_name /* optional address */
697 socklen_t msg_namelen /* size of address */
698 struct iovec *msg_iov /* scatter/gather array */
699 int msg_iovlen /* # elements in msg_iov */
700 caddr_t msg_accrights /* access rights sent/received */
701 .fi
702 .in -2
704 .sp
705 .LP
706 The \fImsg_name\fR and \fImsg_namelen\fR parameters specify the destination
707 address when the socket is unconnected The \fImsg_name\fR can be specified as a
708 \fINULL\fR pointer if no names are desired or required. The \fImsg_iov\fR and
709 \fImsg_iovlen\fR parameters describe the scatter-gather locations, as described
710 in \fBread\fR(2). The \fImsg_accrights\fR parameter specifies the buffer in
711 which access rights sent along with the message are received. The
712 \fImsg_accrightslen\fR specifies the length of the buffer.
713 .SH ATTRIBUTES
714 .LP
715 See \fBattributes\fR(5) for descriptions of the following attributes:
716 .sp
718 .sp
719 .TS
720 box;
721 c | c
722 l | l .
723 ATTRIBUTE TYPE ATTRIBUTE VALUE
724 _
725 Interface Stability Standard
726 .TE
728 .SH SEE ALSO
729 .LP
730 \fBaccept\fR(3SOCKET), \fBaccept\fR(3XNET), \fBbind\fR(3SOCKET),
731 \fBbind\fR(3XNET), \fBconnect\fR(3SOCKET), \fBconnect\fR(3XNET),
732 \fBgetpeername\fR(3SOCKET), \fBgetpeername\fR(3XNET), \fBgetpeerucred\fR(3C),
733 \fBgetsockname\fR(3SOCKET), \fBgetsockname\fR(3XNET),
734 \fBgetsockopt\fR(3SOCKET), \fBgetsockopt\fR(3XNET), \fBlibsocket\fR(3LIB),
735 \fBlisten\fR(3SOCKET), \fBlisten\fR(3XNET), \fBrecv\fR(3SOCKET),
736 \fBrecv\fR(3XNET), \fBrecvfrom\fR(3SOCKET), \fBrecvfrom\fR(3XNET),
737 \fBrecvmsg\fR(3SOCKET), \fBrecvmsg\fR(3XNET), \fBsend\fR(3SOCKET),
738 \fBsend\fR(3XNET), \fBsendmsg\fR(3SOCKET), \fBsendmsg\fR(3XNET),
739 \fBsendto\fR(3SOCKET), \fBsendto\fR(3XNET), \fBsetsockopt\fR(3SOCKET),
740 \fBsetsockopt\fR(3XNET), \fBshutdown\fR(3SOCKET), \fBshutdown\fR(3XNET),
741 \fBsockaddr\fR(3SOCKET),
742 \fBsocket\fR(3SOCKET), \fBsocket\fR(3XNET), \fBsocketpair\fR(3SOCKET),
743 \fBsocketpair\fR(3XNET), \fBucred_get\fR(3C), \fBattributes\fR(5),
744 \fBstandards\fR(5)