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