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