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