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