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