1 SOCKADDR(3C) Standard C Library Functions SOCKADDR(3C)
2
3 NAME
4 sockaddr, sockaddr_dl, sockaddr_in, sockaddr_in6, sockaddr_ll,
5 sockaddr_storage, sockaddr_un - Socket Address Structures
6
7 LIBRARY
8 Standard C Library (libc, -lc)
9
10 SYNOPSIS
11 #include <sys/socket.h>
12
13 struct sockaddr sock;
14
15 #include <sys/socket.h>
16 #include <net/if_dl.h>
17
18 struct sockaddr_dl dl_sock;
19
20 #include <sys/socket.h>
21 #include <netinet/in.h>
22
23 struct sockaddr_in in_sock;
24
25 #include <sys/socket.h>
26 #include <netinet/in.h>
27
28 struct sockaddr_in6 in6_sock;
29
30 #include <sys/socket.h>
31
32 struct sockaddr_ll ll_sock;
33
34 #include <sys/socket.h>
35
36 struct sockaddr_storage storage_sock;
37
38 #include <sys/un.h>
39
40 struct sockaddr_un un_sock;
41
42 DESCRIPTION
43 The sockaddr family of structures are designed to represent network
44 addresses for different networking protocols. The structure struct
45 sockaddr is a generic structure that is used across calls to various
46 socket routines such as accept(3C) and bind(3C). Applications do not use
47 the struct sockaddr directly, but instead cast the appropriate networking
48 family specific sockaddr structure to a struct sockaddr *.
49
50 Every structure in the sockaddr family begins with a member of the same
51 type, the sa_family_t, though the different structures all have different
52 names for the member. For example, the structure struct sockaddr has the
53 following members defined:
54
55 sa_family_t sa_family /* address family */
56 char sa_data[] /* socket address (variable-length data) */
57
58 The member sa_family corresponds to the socket family that's actually in
59 use. The following table describes the mapping between the address
60 family and the corresponding socket structure that's used. Note that
61 both the generic struct sockaddr and the struct sockaddr_storage are not
62 included, because these are both generic structures. More on the struct
63 sockaddr_storage can be found in the next section.
64
65 Socket Structure Address Family
66 struct sockaddr_dl AF_LINK
67 struct sockaddr_in AF_INET
68 struct sockaddr_in6 AF_INET6
69 struct sockaddr_ll AF_PACKET
70 struct sockaddr_un AF_UNIX
71
72 struct sockaddr_storage
73 The sockaddr_storage structure is a sockaddr that is not associated with
74 an address family. Instead, it is large enough to hold the contents of
75 any of the other sockaddr structures. It can be used to embed sufficient
76 storage for a sockaddr of any type within a larger structure.
77
78 The structure only has a single member defined. While there are other
79 members that are used to pad out the size of the struct sockaddr_storage,
80 they are not defined and must not be consumed. The only valid member is:
81
82 sa_family_t ss_family /* address family */
83
84 For example, struct sockaddr_storage is useful when running a service
85 that accepts traffic over both IPv4 and IPv6 where it is common to use a
86 single socket for both address families. In that case, rather than
87 guessing whether a struct sockaddr_in or a struct sockaddr_in6 is more
88 appropriate, one can simply use a struct sockaddr_storage and cast to the
89 appropriate family-specific structure type based on the value of the
90 member ss_family.
91
92 struct sockaddr_in
93 The sockaddr_in is the socket type which is used for for the Internet
94 Protocol version four (IPv4). It has the following members defined:
95
96 sa_family_t sin_family /* address family */
97 in_port_t sin_port /* IP port */
98 struct in_addr sin_addr /* IP address */
99
100 The member sin_family must always have the value AF_INET for IPv4 . The
101 members sin_port and sin_addr describe the IP address and IP port to use.
102 In the case of a call to connect(3C) these represent the remote IP
103 address and port to which the connection is being made. In the case of
104 bind(3C) these represent the IP address and port on the local host to
105 which the socket is to be bound. In the case of accept(3C) these
106 represent the remote IP address and port of the machine whose connection
107 was accepted.
108
109 The member sin_port is always stored in network byte order. On many
110 systems, this differs from the native host byte order. Applications
111 should read from the member with the function ntohs(3C) and write to the
112 member with the function htons(3C). The member sin_addr is the four byte
113 IPv4 address. It is also stored in network byte order. The common way
114 to write out the address is to use the function inet_pton(3C) which
115 converts between a human readable IP address such as `10.1.2.3' and the
116 corresponding representation.
117
118 Example 1 shows how to prepare an IPv4 socket and deal with network byte-
119 order. See inet(7P) and ip(7P) for more information on IPv4, socket
120 options, etc.
121
122 struct sockaddr_in6
123 The sockaddr_in6 structure is the sockaddr for the Internet Protocol
124 version six (IPv6). Unlike the struct sockaddr_in, the struct
125 sockaddr_in6 has additional members beyond those shown here which are
126 required to be initialized to zero through a function such as bzero(3C)
127 or memset(3C). If the entire struct sockaddr_in6 is not zeroed before
128 use, applications will experience undefined behavior. The struct
129 sockaddr_in6 has the following public members:
130
131 sa_family_t sin6_family /* address family */
132 in_port_t sin6_port /* IPv6 port */
133 struct in6_addr sin6_addr /* IPv6 address */
134 uint32_t sin6_flowinfo; /* traffic class and flow info */
135 uint32_t sin6_scope_id; /* interface scope */
136
137 The member sin6_family must always have the value AF_INET6. The members
138 sin6_port and sin6_addr are the IPv6 equivalents of the struct
139 sockaddr_in sin_port and sin_addr. Like their IPv4 counterparts, both of
140 these members must be in network byte order. The member sin6_port
141 describes the IPv6 port and should be manipulated with the functions
142 ntohs(3C) and htons(3C). The member sin6_addr describes the 16-byte IPv6
143 address. In addition to the function inet_pton(3C), the header file
144 <netinet/in.h> defines many macros for manipulating and testing IPv6
145 addresses.
146
147 The member sin6_flowinfo contains the traffic class and flow label
148 associated with the IPv6 header. The member sin6_scope_id may contain an
149 identifier which varies based on the scope of the address in sin6_addr.
150 Applications do not need to initialize sin6_scope_id; it will be
151 populated by the operating system as a result of various library calls.
152
153 Example 2 shows how to prepare an IPv6 socket. For more information on
154 IPv6, please see inet6(7P) and ip6(7P).
155
156 struct sockaddr_un
157 The sockaddr_un structure specifies the address of a socket used to
158 communicate between processes running on a single system, commonly known
159 as a UNIX domain socket. Sockets of this type are identified by a path
160 in the file system. The struct sockaddr_un has the following members:
161
162 sa_family_t sun_family /* address family */
163 char sun_path[108] /* path name */
164
165 The member sun_family must always have the value AF_UNIX. The member
166 sun_path is populated with a NUL terminated array of characters that
167 specify a file system path. The maximum length of any such path,
168 including the NUL terminator, is 108 bytes.
169
170 struct sockaddr_dl
171 The sockaddr_dl structure is used to describe a layer 2 link-level
172 address. This is used as part of various socket ioctls, such as those
173 for arp(7P). The structure has the following members:
174
175 ushort_t sdl_family; /* address family */
176 ushort_t sdl_index; /* if != 0, system interface index */
177 uchar_t sdl_type; /* interface type */
178 uchar_t sdl_nlen; /* interface name length */
179 uchar_t sdl_alen; /* link level address length */
180 uchar_t sdl_slen; /* link layer selector length */
181 char sdl_data[244]; /* contains both if name and ll address
182
183 The member sdl_family must always have the value AF_LINK. When the
184 member sdl_index is non-zero this refers to the interface identifier that
185 corresponds to the struct sockaddr_dl. This identifier is the same
186 identifier that's shown by tools like ifconfig(1M) and used in the SIOC*
187 set of socket ioctls. The member sdl_type refers to the media that is
188 used for the socket. The most common case is that the medium for the
189 interface is Ethernet which has the value IFT_ETHER. The full set of
190 types is derived from RFC1573 and recorded in the file <net/if_types.h>.
191 The member sdl_slen describes the length of a selector, if it exists, for
192 the specified medium. This is used in protocols such as Trill.
193
194 The sdl_data, sdl_nlen, and sdl_alen members together describe a
195 character string containing the interface name and the link-layer network
196 address. The name starts at the beginning of sdl_data, i.e. at
197 sdl_data[0]. The name of the interface occupies the next sdl_nlen bytes
198 and is not NUL terminated. The link-layer network address begins
199 immediately after the interface name, and is sdl_alen bytes long. The
200 macro LLADDR(struct sockaddr_dl *) returns the start of the link-layer
201 network address. The interpretation of the link-layer address depends on
202 the value of sdl_type. For example, if the type is IFT_ETHER then the
203 address is expressed as a 6-byte MAC address.
204
205 struct sockaddr_ll
206 The sockaddr_ll is used as part of a socket type which is responsible for
207 packet capture: AF_PACKET sockets. It is generally designed for use with
208 Ethernet networks. The members of the struct sockaddr_ll are:
209
210 uint16_t sll_family; /* address family */
211 uint16_t sll_protocol; /* link layer protocol */
212 int32_t sll_ifindex; /* interface index */
213 uint16_t sll_hatype; /* ARP hardware type */
214 uint8_t sll_pkttype; /* packet type */
215 uint8_t sll_halen; /* hardware address length */
216 uint8_t sll_addr[8]; /* hardware type */
217
218 The member sll_family must be AF_PACKET. The member sll_protocol refers
219 to a link-layer protocol. For example, when capturing Ethernet frames
220 the value of sll_protocol is the Ethertype. This member is written in
221 network byte order and applications should use htons(3C) and ntohs(3C) to
222 read and write the member.
223
224 The member sll_ifindex is the interface's index. It is used as an
225 identifier in various ioctls and included in the output of ifconfig(1M).
226 When calling bind(3C) it should be filled in with the index that
227 corresponds to the interface for which packets should be captured on.
228
229 The member sll_pkttype describes the type of the packet based on a list
230 of types in the header file <netpacket/packet.h>. These types include:
231 PACKET_OUTGOING, a packet that was leaving the host and has been looped
232 back for packet capture; PACKET_HOST, a packet that was destined for this
233 host; PACKET_BROADCAST, a packet that was broadcast across the link-
234 layer; PACKET_MULTICAST, a packet that was sent to a link-layer multicast
235 address; and PACKET_OTHERHOST, a packet that was captured only because
236 the device in question was in promiscuous mode.
237
238 The member sll_hatype contains the hardware type as defined by arp(7P).
239 The list of types can be found in <net/if_arp.h>. The member sll_halen
240 contains the length, in bytes, of the hardware address, while the member
241 sll_addr contains the actual address in network byte order.
242
243 EXAMPLES
244 Example 1 Preparing an IPv4 sockaddr_in to connect to a remote host
245 The following example shows how one would open a socket and
246 prepare it to connect to the remote host whose address is the IP
247 address 127.0.0.1 on port 80.
248
249 #include <sys/types.h>
250 #include <sys/socket.h>
251 #include <stdio.h>
252 #include <netinet/in.h>
253 #include <inttypes.h>
254 #include <strings.h>
255
256 int
257 main(void)
258 {
259 int sock;
260 struct sockaddr_in in;
261
262 if ((sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
263 perror("socket");
264 return (1);
265 }
266
267 bzero(&in, sizeof (struct sockaddr_in));
268 in.sin_family = AF_INET;
269 in.sin_port = htons(80);
270 if (inet_pton(AF_INET, "127.0.0.1", &in.sin_addr) != 1) {
271 perror("inet_pton");
272 return (1);
273 }
274
275 if (connect(sock, (struct sockaddr *)&in,
276 sizeof (struct sockaddr_in)) != 0) {
277 perror("connect");
278 return (1);
279 }
280
281 /* use socket */
282
283 return (0);
284 }
285
286 Example 2 Preparing an IPv6 sockaddr_in6 to bind to a local address
287 The following example shows how one would open a socket and
288 prepare it to bind to the local IPv6 address ::1 port on port
289 12345.
290
291 #include <sys/types.h>
292 #include <sys/socket.h>
293 #include <stdio.h>
294 #include <netinet/in.h>
295 #include <inttypes.h>
296 #include <strings.h>
297
298 int
299 main(void)
300 {
301 int sock6;
302 struct sockaddr_in6 in6;
303
304 if ((sock6 = socket(AF_INET6, SOCK_STREAM, 0)) < 0) {
305 perror("socket");
306 return (1);
307 }
308
309 bzero(&in6, sizeof (struct sockaddr_in6));
310 in6.sin6_family = AF_INET6;
311 in6.sin6_port = htons(12345);
312 if (inet_pton(AF_INET6, "::1", &in6.sin6_addr) != 1) {
313 perror("inet_pton");
314 return (1);
315 }
316
317 if (bind(sock6, (struct sockaddr *)&in6,
318 sizeof (struct sockaddr_in6)) != 0) {
319 perror("bind");
320 return (1);
321 }
322
323 /* use server socket */
324
325 return (0);
326 }
327
328 SEE ALSO
329 accept(3C), bind(3C), connect(3C), socket(3C), socket.h(3HEAD),
330 un.h(3HEAD), arp(7P), inet(7P), inet6(7P), ip(7P), ip6(7P)
331
332 illumos August 2, 2018 illumos