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
|
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
|