1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015, Joyent, Inc. 13.\" 14.Dd April 9, 2016 15.Dt SOCKADDR 3SOCKET 16.Os 17.Sh NAME 18.Nm sockaddr , 19.Nm sockaddr_dl , 20.Nm sockaddr_in , 21.Nm sockaddr_in6 , 22.Nm sockaddr_ll , 23.Nm sockaddr_storage , 24.Nm sockaddr_un 25.Nd Socket Address Structures 26.Sh SYNOPSIS 27.In sys/socket.h 28.Lp 29.Sy struct sockaddr 30.Em sock ; 31.Lp 32.In sys/socket.h 33.In net/if_dl.h 34.Lp 35.Sy struct sockaddr_dl 36.Em dl_sock ; 37.Lp 38.In sys/socket.h 39.In netinet/in.h 40.Lp 41.Sy struct sockaddr_in 42.Em in_sock ; 43.Lp 44.In sys/socket.h 45.In netinet/in.h 46.Lp 47.Sy struct sockaddr_in6 48.Em in6_sock ; 49.Lp 50.In sys/socket.h 51.Lp 52.Sy struct sockaddr_ll 53.Em ll_sock ; 54.Lp 55.In sys/socket.h 56.Lp 57.Sy struct sockaddr_storage 58.Em storage_sock ; 59.Lp 60.In sys/un.h 61.Lp 62.Sy struct sockaddr_un 63.Em un_sock ; 64.Sh DESCRIPTION 65The 66.Nm 67family of structures are designed to represent network addresses for 68different networking protocols. 69The structure 70.Sy struct sockaddr 71is a generic structure that is used across calls to various socket 72library routines 73.Po 74.Xr libsocket 3LIB 75.Pc 76such as 77.Xr accept 3SOCKET 78and 79.Xr bind 3SOCKET . 80Applications do not use the 81.Sy struct sockaddr 82directly, but instead cast the appropriate networking family specific 83.Nm 84structure to a 85.Sy struct sockaddr * . 86.Lp 87Every structure in the 88.Nm 89family begins with a member of the same type, the 90.Sy sa_family_t , 91though the different structures all have different names for the member. 92For example, the structure 93.Sy struct sockaddr 94has the following members defined: 95.Bd -literal -offset indent 96sa_family_t sa_family /* address family */ 97char sa_data[] /* socket address (variable-length data) */ 98.Ed 99.Lp 100The member 101.Em sa_family 102corresponds to the socket family that's actually in use. 103The following table describes the mapping between the address family and the 104corresponding socket structure that's used. 105Note that both the generic 106.Sy struct sockaddr 107and the 108.Sy struct sockaddr_storage 109are not included, because these are both generic structures. 110More on the 111.Sy struct sockaddr_storage 112can be found in the next section. 113.Bl -column -offset indent ".Sy Socket Structure" ".Sy Address Family" 114.It Sy Socket Structure Ta Sy Address Family 115.It struct sockaddr_dl Ta AF_LINK 116.It struct sockaddr_in Ta AF_INET 117.It struct sockaddr_in6 Ta AF_INET6 118.It struct sockaddr_ll Ta AF_PACKET 119.It struct sockaddr_un Ta AF_UNIX 120.El 121.Ss struct sockaddr_storage 122The 123.Sy sockaddr_storage 124structure is a 125.Nm 126that is not associated with an address family. 127Instead, it is large enough to hold the contents of any of the other 128.Nm 129structures. 130It can be used to embed sufficient storage for a 131.Sy sockaddr 132of any type within a larger structure. 133.Lp 134The structure only has a single member defined. 135While there are other members that are used to pad out the size of the 136.Sy struct sockaddr_storage , 137they are not defined and must not be consumed. 138The only valid member is: 139.Bd -literal -offset indent 140sa_family_t ss_family /* address family */ 141.Ed 142.Lp 143For example, 144.Sy struct sockaddr_storage 145is useful when running a service that accepts traffic over both 146.Sy IPv4 147and 148.Sy IPv6 149where it is common to use a single socket for both address families. 150In that case, rather than guessing whether a 151.Sy struct sockaddr_in 152or a 153.Sy struct sockaddr_in6 154is more appropriate, one can simply use a 155.Sy struct sockaddr_storage 156and cast to the appropriate family-specific structure type based on the 157value of the member 158.Em ss_family . 159.Ss struct sockaddr_in 160The 161.Sy sockaddr_in 162is the socket type which is used for for the Internet Protocol version 163four (IPv4). 164It has the following members defined: 165.Bd -literal -offset indent 166sa_family_t sin_family /* address family */ 167in_port_t sin_port /* IP port */ 168struct in_addr sin_addr /* IP address */ 169.Ed 170.Lp 171The member 172.Em sin_family 173must always have the value 174.Sy AF_INET 175for 176.Sy IPv4 . 177The members 178.Em sin_port 179and 180.Em sin_addr 181describe the IP address and IP port to use. 182In the case of a call to 183.Xr connect 3SOCKET 184these represent the remote IP address and port to which the connection 185is being made. 186In the case of 187.Xr bind 3SOCKET 188these represent the IP address and port on the local host to which the socket 189is to be bound. 190In the case of 191.Xr accept 3SOCKET 192these represent the remote IP address and port of the machine whose 193connection was accepted. 194.Lp 195The member 196.Em sin_port 197is always stored in 198.Sy Network Byte Order . 199On many systems, this differs from the native host byte order. 200Applications should read from the member with the function 201.Xr ntohs 3SOCKET 202and write to the member with the function 203.Xr htons 3SOCKET . 204The member 205.Em sin_addr 206is the four byte IPv4 address. 207It is also stored in network byte order. 208The common way to write out the address is to use the function 209.Xr inet_pton 3SOCKET 210which converts between a human readable IP address such as "10.1.2.3" 211and the corresponding representation. 212.Lp 213Example 1 shows how to prepare an IPv4 socket and deal with 214network byte-order. 215See 216.Xr inet 7P 217and 218.Xr ip 7P 219for more information on IPv4, socket options, etc. 220.Ss struct sockaddr_in6 221The 222.Sy sockaddr_in6 223structure is the 224.Nm 225for the Internet Protocol version six (IPv6). 226Unlike the 227.Sy struct sockaddr_in , 228the 229.Sy struct sockaddr_in6 230has additional members beyond those shown here which are required to be 231initialized to zero through a function such as 232.Xr bzero 3C 233or 234.Xr memset 3C . 235If the entire 236.Sy struct sockaddr_in6 237is not zeroed before use, applications will experience undefined behavior. 238The 239.Sy struct sockaddr_in6 240has the following public members: 241.Bd -literal -offset indent 242sa_family_t sin6_family /* address family */ 243in_port_t sin6_port /* IPv6 port */ 244struct in6_addr sin6_addr /* IPv6 address */ 245uint32_t sin6_flowinfo; /* traffic class and flow info */ 246uint32_t sin6_scope_id; /* interface scope */ 247.Ed 248.Lp 249The member 250.Em sin6_family 251must always have the value 252.Sy AF_INET6 . 253The members 254.Em sin6_port 255and 256.Em sin6_addr 257are the IPv6 equivalents of the 258.Sy struct sockaddr_in 259.Em sin_port 260and 261.Em sin_addr . 262Like their IPv4 counterparts, both of these members must be in network 263byte order. 264The member 265.Em sin6_port 266describes the IPv6 port and should be manipulated with the functions 267.Xr ntohs 3SOCKET 268and 269.Xr htons 3SOCKET . 270The member 271.Em sin6_addr 272describes the 16-byte IPv6 address. 273In addition to the function 274.Xr inet_pton 3SOCKET , 275the header file 276.In netinet/in.h 277defines many macros for manipulating and testing IPv6 addresses. 278.Lp 279The member 280.Em sin6_flowinfo 281contains the traffic class and flow label associated with the IPv6 282header. 283The member 284.Em sin6_scope_id 285may contain an identifier which varies based on the scope of the address 286in 287.Em sin6_addr . 288Applications do not need to initialize 289.Em sin6_scope_id ; 290it will be populated by the operating system as a result of various library 291calls. 292.Lp 293Example 2 shows how to prepare an IPv6 socket. 294For more information on 295IPv6, please see 296.Xr inet6 7P 297and 298.Xr ip6 7P . 299.Ss struct sockaddr_un 300The 301.Sy sockaddr_un 302structure specifies the address of a socket used to communicate between 303processes running on a single system, commonly known as a 304.Em UNIX domain socket . 305Sockets of this type are identified by a path in the file system. 306The 307.Sy struct sockaddr_un 308has the following members: 309.Bd -literal -offset indent 310sa_family_t sun_family /* address family */ 311char sun_path[108] /* path name */ 312.Ed 313.Lp 314The member 315.Em sun_family 316must always have the value 317.Sy AF_UNIX . 318The member 319.Em sun_path 320is populated with a 321.Sy NUL 322terminated array of characters that specify a file system path. 323The maximum length of any such path, including the 324.Sy NUL 325terminator, is 108 bytes. 326.Ss struct sockaddr_dl 327The 328.Sy sockaddr_dl 329structure is used to describe a layer 2 link-level address. 330This is used as part of various socket ioctls, such as those for 331.Xr arp 7P . 332The structure has the following members: 333.Bd -literal -offset indent 334ushort_t sdl_family; /* address family */ 335ushort_t sdl_index; /* if != 0, system interface index */ 336uchar_t sdl_type; /* interface type */ 337uchar_t sdl_nlen; /* interface name length */ 338uchar_t sdl_alen; /* link level address length */ 339uchar_t sdl_slen; /* link layer selector length */ 340char sdl_data[244]; /* contains both if name and ll address 341.Ed 342.Lp 343The member 344.Em sdl_family 345must always have the value 346.Sy AF_LINK . 347When the member 348.Em sdl_index 349is non-zero this refers to the interface identifier that corresponds to 350the 351.Sy struct sockaddr_dl . 352This identifier is the same identifier that's shown by tools like 353.Xr ifconfig 1M 354and used in the SIOC* set of socket ioctls. 355The member 356.Em sdl_type 357refers to the media that is used for the socket. 358The most common case is that the medium for the interface is Ethernet which has 359the value 360.Sy IFT_ETHER . 361The full set of types is derived from RFC1573 and recorded in the file 362.In net/if_types.h . 363The member 364.Em sdl_slen 365describes the length of a selector, if it exists, for the specified 366medium. 367This is used in protocols such as Trill. 368.Lp 369The 370.Em sdl_data , 371.Em sdl_nlen 372and 373.Em sdl_alen 374members together describe a character string containing the interface name and 375the link-layer network address. 376The name starts at the beginning of 377.Em sdl_data , 378i.e. at 379.Em sdl_data[0] . 380The name of the interface occupies the next 381.Em sdl_nlen 382bytes and is not 383.Sy NUL 384terminated. 385The link-layer network address begins immediately after the interface name, 386and is 387.Em sdl_alen 388bytes long. 389The macro 390.Sy LLADDR(struct sockaddr_dl *) 391returns the start of the link-layer network address. 392The interpretation of the link-layer address depends on the value of 393.Em sdl_type . 394For example, if the type is 395.Sy IFT_ETHER 396then the address is expressed as a 6-byte MAC address. 397.Ss struct sockaddr_ll 398The 399.Sy sockaddr_ll 400is used as part of a socket type which is responsible for packet 401capture: 402.Sy AF_PACKET 403sockets. 404It is generally designed for use with Ethernet networks. 405The members of the 406.Sy struct sockaddr_ll 407are: 408.Bd -literal -offset indent 409uint16_t sll_family; /* address family */ 410uint16_t sll_protocol; /* link layer protocol */ 411int32_t sll_ifindex; /* interface index */ 412uint16_t sll_hatype; /* ARP hardware type */ 413uint8_t sll_pkttype; /* packet type */ 414uint8_t sll_halen; /* hardware address length */ 415uint8_t sll_addr[8]; /* hardware type */ 416.Ed 417.Lp 418The member 419.Em sll_family 420must be 421.Sy AF_PACKET . 422The member 423.Em sll_protocol 424refers to a link-layer protocol. 425For example, when capturing Ethernet frames the value of 426.Em sll_protocol 427is the Ethertype. 428This member is written in network byte order and applications should use 429.Xr htons 3SOCKET 430and 431.Xr ntohs 3SOCKET 432to read and write the member. 433.Lp 434The member 435.Em sll_ifindex 436is the interface's index. 437It is used as an identifier in various ioctls and included in the output of 438.Xr ifconfig 1M . 439When calling 440.Xr bind 3SOCKET 441it should be filled in with the index that corresponds to the interface 442for which packets should be captured on. 443.Lp 444The member 445.Em sll_pkttype 446describes the type of the packet based on a list of types in the header 447file 448.In netpacket/packet.h . 449These types include: 450.Sy PACKET_OUTGOING , 451a packet that was leaving the host and has been looped back for packet capture; 452.Sy PACKET_HOST , 453a packet that was destined for this host; 454.Sy PACKET_BROADCAST , 455a packet that was broadcast across the link-layer; 456.Sy PACKET_MULTICAST , 457a packet that was sent to a link-layer multicast address; and 458.Sy PACKET_OTHERHOST , 459a packet that was captured only because the device in question was in 460promiscuous mode. 461.Lp 462The member 463.Em sll_hatype 464contains the hardware type as defined by 465.Xr arp 7P . 466The list of types can be found in 467.In net/if_arp.h . 468The member 469.Em sll_halen 470contains the length, in bytes, of the hardware address, while the member 471.Em sll_addr 472contains the actual address in network byte order. 473.Sh EXAMPLES 474.Sy Example 1 475Preparing an IPv4 476.Sy sockaddr_in 477to connect to a remote host 478.Lp 479The following example shows how one would open a socket and prepare it 480to connect to the remote host whose address is the IP address 127.0.0.1 481on port 80. 482This program should be compiled with the C compiler 483.Sy cc 484and linked against the libraries libsocket and libnsl. 485If this example was named ip4.c, then the full link line would be 486.Ic cc ip4.c -lsocket -lnsl . 487.Bd -literal 488#include <sys/types.h> 489#include <sys/socket.h> 490#include <stdio.h> 491#include <netinet/in.h> 492#include <inttypes.h> 493#include <strings.h> 494 495int 496main(void) 497{ 498 int sock; 499 struct sockaddr_in in; 500 501 if ((sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) { 502 perror("socket"); 503 return (1); 504 } 505 506 bzero(&in, sizeof (struct sockaddr_in)); 507 in.sin_family = AF_INET; 508 in.sin_port = htons(80); 509 if (inet_pton(AF_INET, "127.0.0.1", &in.sin_addr) != 1) { 510 perror("inet_pton"); 511 return (1); 512 } 513 514 if (connect(sock, (struct sockaddr *)&in, 515 sizeof (struct sockaddr_in)) != 0) { 516 perror("connect"); 517 return (1); 518 } 519 520 /* use socket */ 521 522 return (0); 523} 524.Ed 525.Lp 526.Sy Example 2 527Preparing an IPv6 528.Sy sockaddr_in6 529to bind to a local address 530.Lp 531The following example shows how one would open a socket and prepare it 532to bind to the local IPv6 address ::1 port on port 12345. 533This program should be compiled with the C compiler 534.Sy cc 535and linked against the libraries libsocket and libnsl. 536If this example was named ip6.c, then the full compiler line would be 537.Ic cc ip6.c -lsocket -lnsl . 538.Bd -literal 539#include <sys/types.h> 540#include <sys/socket.h> 541#include <stdio.h> 542#include <netinet/in.h> 543#include <inttypes.h> 544#include <strings.h> 545 546int 547main(void) 548{ 549 int sock6; 550 struct sockaddr_in6 in6; 551 552 if ((sock6 = socket(AF_INET6, SOCK_STREAM, 0)) < 0) { 553 perror("socket"); 554 return (1); 555 } 556 557 bzero(&in6, sizeof (struct sockaddr_in6)); 558 in6.sin6_family = AF_INET6; 559 in6.sin6_port = htons(12345); 560 if (inet_pton(AF_INET6, "::1", &in6.sin6_addr) != 1) { 561 perror("inet_pton"); 562 return (1); 563 } 564 565 if (bind(sock6, (struct sockaddr *)&in6, 566 sizeof (struct sockaddr_in6)) != 0) { 567 perror("bind"); 568 return (1); 569 } 570 571 /* use server socket */ 572 573 return (0); 574} 575.Ed 576.Sh SEE ALSO 577.Xr socket 3HEAD , 578.Xr un.h 3HEAD , 579.Xr accept 3SOCKET , 580.Xr bind 3SOCKET , 581.Xr connect 3SOCKET , 582.Xr socket 3SOCKET , 583.Xr arp 7P , 584.Xr inet 7P , 585.Xr inet6 7P , 586.Xr ip 7P , 587.Xr ip6 7P 588