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