Print this page
9704 move socket functions to libc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3socket/sockaddr.3socket.man.txt
+++ new/usr/src/man/man3c/sockaddr.3c.man.txt
1 -SOCKADDR(3SOCKET) Sockets Library Functions SOCKADDR(3SOCKET)
1 +SOCKADDR(3C) Standard C Library Functions SOCKADDR(3C)
2 2
3 3 NAME
4 4 sockaddr, sockaddr_dl, sockaddr_in, sockaddr_in6, sockaddr_ll,
5 5 sockaddr_storage, sockaddr_un - Socket Address Structures
6 6
7 +LIBRARY
8 + Standard C Library (libc, -lc)
9 +
7 10 SYNOPSIS
8 11 #include <sys/socket.h>
9 12
10 13 struct sockaddr sock;
11 14
12 15 #include <sys/socket.h>
13 16 #include <net/if_dl.h>
14 17
15 18 struct sockaddr_dl dl_sock;
16 19
17 20 #include <sys/socket.h>
18 21 #include <netinet/in.h>
19 22
20 23 struct sockaddr_in in_sock;
21 24
22 25 #include <sys/socket.h>
23 26 #include <netinet/in.h>
24 27
25 28 struct sockaddr_in6 in6_sock;
26 29
27 30 #include <sys/socket.h>
28 31
29 32 struct sockaddr_ll ll_sock;
30 33
31 34 #include <sys/socket.h>
32 35
|
↓ open down ↓ |
16 lines elided |
↑ open up ↑ |
33 36 struct sockaddr_storage storage_sock;
34 37
35 38 #include <sys/un.h>
36 39
37 40 struct sockaddr_un un_sock;
38 41
39 42 DESCRIPTION
40 43 The sockaddr family of structures are designed to represent network
41 44 addresses for different networking protocols. The structure struct
42 45 sockaddr is a generic structure that is used across calls to various
43 - socket library routines (libsocket(3LIB)) such as accept(3SOCKET) and
44 - bind(3SOCKET). Applications do not use the struct sockaddr directly, but
45 - instead cast the appropriate networking family specific sockaddr
46 - structure to a struct sockaddr *.
46 + socket routines such as accept(3C) and bind(3C). Applications do not use
47 + the struct sockaddr directly, but instead cast the appropriate networking
48 + family specific sockaddr structure to a struct sockaddr *.
47 49
48 50 Every structure in the sockaddr family begins with a member of the same
49 51 type, the sa_family_t, though the different structures all have different
50 52 names for the member. For example, the structure struct sockaddr has the
51 53 following members defined:
52 54
53 55 sa_family_t sa_family /* address family */
54 56 char sa_data[] /* socket address (variable-length data) */
55 57
56 58 The member sa_family corresponds to the socket family that's actually in
57 59 use. The following table describes the mapping between the address
58 60 family and the corresponding socket structure that's used. Note that
59 61 both the generic struct sockaddr and the struct sockaddr_storage are not
60 62 included, because these are both generic structures. More on the struct
61 63 sockaddr_storage can be found in the next section.
62 64
63 65 Socket Structure Address Family
64 66 struct sockaddr_dl AF_LINK
65 67 struct sockaddr_in AF_INET
66 68 struct sockaddr_in6 AF_INET6
67 69 struct sockaddr_ll AF_PACKET
68 70 struct sockaddr_un AF_UNIX
69 71
70 72 struct sockaddr_storage
71 73 The sockaddr_storage structure is a sockaddr that is not associated with
72 74 an address family. Instead, it is large enough to hold the contents of
73 75 any of the other sockaddr structures. It can be used to embed sufficient
74 76 storage for a sockaddr of any type within a larger structure.
75 77
76 78 The structure only has a single member defined. While there are other
77 79 members that are used to pad out the size of the struct sockaddr_storage,
78 80 they are not defined and must not be consumed. The only valid member is:
79 81
80 82 sa_family_t ss_family /* address family */
81 83
82 84 For example, struct sockaddr_storage is useful when running a service
83 85 that accepts traffic over both IPv4 and IPv6 where it is common to use a
84 86 single socket for both address families. In that case, rather than
85 87 guessing whether a struct sockaddr_in or a struct sockaddr_in6 is more
86 88 appropriate, one can simply use a struct sockaddr_storage and cast to the
87 89 appropriate family-specific structure type based on the value of the
|
↓ open down ↓ |
31 lines elided |
↑ open up ↑ |
88 90 member ss_family.
89 91
90 92 struct sockaddr_in
91 93 The sockaddr_in is the socket type which is used for for the Internet
92 94 Protocol version four (IPv4). It has the following members defined:
93 95
94 96 sa_family_t sin_family /* address family */
95 97 in_port_t sin_port /* IP port */
96 98 struct in_addr sin_addr /* IP address */
97 99
98 - The member sin_family must always have the value AF_INET for IPv4. The
100 + The member sin_family must always have the value AF_INET for IPv4 . The
99 101 members sin_port and sin_addr describe the IP address and IP port to use.
100 - In the case of a call to connect(3SOCKET) these represent the remote IP
102 + In the case of a call to connect(3C) these represent the remote IP
101 103 address and port to which the connection is being made. In the case of
102 - bind(3SOCKET) these represent the IP address and port on the local host
103 - to which the socket is to be bound. In the case of accept(3SOCKET) these
104 + bind(3C) these represent the IP address and port on the local host to
105 + which the socket is to be bound. In the case of accept(3C) these
104 106 represent the remote IP address and port of the machine whose connection
105 107 was accepted.
106 108
107 - The member sin_port is always stored in Network Byte Order. On many
109 + The member sin_port is always stored in network byte order. On many
108 110 systems, this differs from the native host byte order. Applications
109 - should read from the member with the function ntohs(3SOCKET) and write to
110 - the member with the function htons(3SOCKET). The member sin_addr is the
111 - four byte IPv4 address. It is also stored in network byte order. The
112 - common way to write out the address is to use the function inet_pton(3C)
113 - which converts between a human readable IP address such as "10.1.2.3" and
114 - the corresponding representation.
111 + should read from the member with the function ntohs(3C) and write to the
112 + member with the function htons(3C). The member sin_addr is the four byte
113 + IPv4 address. It is also stored in network byte order. The common way
114 + to write out the address is to use the function inet_pton(3C) which
115 + converts between a human readable IP address such as `10.1.2.3' and the
116 + corresponding representation.
115 117
116 118 Example 1 shows how to prepare an IPv4 socket and deal with network byte-
117 119 order. See inet(7P) and ip(7P) for more information on IPv4, socket
118 120 options, etc.
119 121
120 122 struct sockaddr_in6
121 123 The sockaddr_in6 structure is the sockaddr for the Internet Protocol
122 124 version six (IPv6). Unlike the struct sockaddr_in, the struct
123 125 sockaddr_in6 has additional members beyond those shown here which are
124 126 required to be initialized to zero through a function such as bzero(3C)
125 127 or memset(3C). If the entire struct sockaddr_in6 is not zeroed before
126 128 use, applications will experience undefined behavior. The struct
127 129 sockaddr_in6 has the following public members:
128 130
129 131 sa_family_t sin6_family /* address family */
|
↓ open down ↓ |
5 lines elided |
↑ open up ↑ |
130 132 in_port_t sin6_port /* IPv6 port */
131 133 struct in6_addr sin6_addr /* IPv6 address */
132 134 uint32_t sin6_flowinfo; /* traffic class and flow info */
133 135 uint32_t sin6_scope_id; /* interface scope */
134 136
135 137 The member sin6_family must always have the value AF_INET6. The members
136 138 sin6_port and sin6_addr are the IPv6 equivalents of the struct
137 139 sockaddr_in sin_port and sin_addr. Like their IPv4 counterparts, both of
138 140 these members must be in network byte order. The member sin6_port
139 141 describes the IPv6 port and should be manipulated with the functions
140 - ntohs(3SOCKET) and htons(3SOCKET). The member sin6_addr describes the
141 - 16-byte IPv6 address. In addition to the function inet_pton(3C), the
142 - header file <netinet/in.h> defines many macros for manipulating and
143 - testing IPv6 addresses.
142 + ntohs(3C) and htons(3C). The member sin6_addr describes the 16-byte IPv6
143 + address. In addition to the function inet_pton(3C), the header file
144 + <netinet/in.h> defines many macros for manipulating and testing IPv6
145 + addresses.
144 146
145 147 The member sin6_flowinfo contains the traffic class and flow label
146 148 associated with the IPv6 header. The member sin6_scope_id may contain an
147 149 identifier which varies based on the scope of the address in sin6_addr.
148 150 Applications do not need to initialize sin6_scope_id; it will be
149 151 populated by the operating system as a result of various library calls.
150 152
151 153 Example 2 shows how to prepare an IPv6 socket. For more information on
152 154 IPv6, please see inet6(7P) and ip6(7P).
153 155
154 156 struct sockaddr_un
155 157 The sockaddr_un structure specifies the address of a socket used to
156 158 communicate between processes running on a single system, commonly known
157 159 as a UNIX domain socket. Sockets of this type are identified by a path
158 160 in the file system. The struct sockaddr_un has the following members:
159 161
160 162 sa_family_t sun_family /* address family */
161 163 char sun_path[108] /* path name */
162 164
163 165 The member sun_family must always have the value AF_UNIX. The member
164 166 sun_path is populated with a NUL terminated array of characters that
165 167 specify a file system path. The maximum length of any such path,
166 168 including the NUL terminator, is 108 bytes.
167 169
168 170 struct sockaddr_dl
169 171 The sockaddr_dl structure is used to describe a layer 2 link-level
170 172 address. This is used as part of various socket ioctls, such as those
171 173 for arp(7P). The structure has the following members:
172 174
173 175 ushort_t sdl_family; /* address family */
174 176 ushort_t sdl_index; /* if != 0, system interface index */
175 177 uchar_t sdl_type; /* interface type */
176 178 uchar_t sdl_nlen; /* interface name length */
177 179 uchar_t sdl_alen; /* link level address length */
178 180 uchar_t sdl_slen; /* link layer selector length */
179 181 char sdl_data[244]; /* contains both if name and ll address
180 182
181 183 The member sdl_family must always have the value AF_LINK. When the
|
↓ open down ↓ |
28 lines elided |
↑ open up ↑ |
182 184 member sdl_index is non-zero this refers to the interface identifier that
183 185 corresponds to the struct sockaddr_dl. This identifier is the same
184 186 identifier that's shown by tools like ifconfig(1M) and used in the SIOC*
185 187 set of socket ioctls. The member sdl_type refers to the media that is
186 188 used for the socket. The most common case is that the medium for the
187 189 interface is Ethernet which has the value IFT_ETHER. The full set of
188 190 types is derived from RFC1573 and recorded in the file <net/if_types.h>.
189 191 The member sdl_slen describes the length of a selector, if it exists, for
190 192 the specified medium. This is used in protocols such as Trill.
191 193
192 - The sdl_data, sdl_nlen and sdl_alen members together describe a character
193 - string containing the interface name and the link-layer network address.
194 - The name starts at the beginning of sdl_data, i.e. at sdl_data[0]. The
195 - name of the interface occupies the next sdl_nlen bytes and is not NUL
196 - terminated. The link-layer network address begins immediately after the
197 - interface name, and is sdl_alen bytes long. The macro LLADDR(struct
198 - sockaddr_dl *) returns the start of the link-layer network address. The
199 - interpretation of the link-layer address depends on the value of
200 - sdl_type. For example, if the type is IFT_ETHER then the address is
201 - expressed as a 6-byte MAC address.
194 + The sdl_data, sdl_nlen, and sdl_alen members together describe a
195 + character string containing the interface name and the link-layer network
196 + address. The name starts at the beginning of sdl_data, i.e. at
197 + sdl_data[0]. The name of the interface occupies the next sdl_nlen bytes
198 + and is not NUL terminated. The link-layer network address begins
199 + immediately after the interface name, and is sdl_alen bytes long. The
200 + macro LLADDR(struct sockaddr_dl *) returns the start of the link-layer
201 + network address. The interpretation of the link-layer address depends on
202 + the value of sdl_type. For example, if the type is IFT_ETHER then the
203 + address is expressed as a 6-byte MAC address.
202 204
203 205 struct sockaddr_ll
204 206 The sockaddr_ll is used as part of a socket type which is responsible for
205 207 packet capture: AF_PACKET sockets. It is generally designed for use with
206 208 Ethernet networks. The members of the struct sockaddr_ll are:
207 209
208 210 uint16_t sll_family; /* address family */
209 211 uint16_t sll_protocol; /* link layer protocol */
210 212 int32_t sll_ifindex; /* interface index */
211 213 uint16_t sll_hatype; /* ARP hardware type */
212 214 uint8_t sll_pkttype; /* packet type */
213 215 uint8_t sll_halen; /* hardware address length */
214 216 uint8_t sll_addr[8]; /* hardware type */
215 217
216 218 The member sll_family must be AF_PACKET. The member sll_protocol refers
217 219 to a link-layer protocol. For example, when capturing Ethernet frames
218 220 the value of sll_protocol is the Ethertype. This member is written in
219 - network byte order and applications should use htons(3SOCKET) and
220 - ntohs(3SOCKET) to read and write the member.
221 + network byte order and applications should use htons(3C) and ntohs(3C) to
222 + read and write the member.
221 223
222 224 The member sll_ifindex is the interface's index. It is used as an
223 225 identifier in various ioctls and included in the output of ifconfig(1M).
224 - When calling bind(3SOCKET) it should be filled in with the index that
226 + When calling bind(3C) it should be filled in with the index that
225 227 corresponds to the interface for which packets should be captured on.
226 228
227 229 The member sll_pkttype describes the type of the packet based on a list
228 230 of types in the header file <netpacket/packet.h>. These types include:
229 231 PACKET_OUTGOING, a packet that was leaving the host and has been looped
230 232 back for packet capture; PACKET_HOST, a packet that was destined for this
231 233 host; PACKET_BROADCAST, a packet that was broadcast across the link-
232 234 layer; PACKET_MULTICAST, a packet that was sent to a link-layer multicast
233 235 address; and PACKET_OTHERHOST, a packet that was captured only because
234 236 the device in question was in promiscuous mode.
235 237
236 238 The member sll_hatype contains the hardware type as defined by arp(7P).
237 239 The list of types can be found in <net/if_arp.h>. The member sll_halen
238 240 contains the length, in bytes, of the hardware address, while the member
239 241 sll_addr contains the actual address in network byte order.
240 242
241 243 EXAMPLES
242 244 Example 1 Preparing an IPv4 sockaddr_in to connect to a remote host
245 + The following example shows how one would open a socket and
246 + prepare it to connect to the remote host whose address is the IP
247 + address 127.0.0.1 on port 80.
243 248
244 - The following example shows how one would open a socket and prepare it to
245 - connect to the remote host whose address is the IP address 127.0.0.1 on
246 - port 80. This program should be compiled with the C compiler cc and
247 - linked against the libraries libsocket and libnsl. If this example was
248 - named ip4.c, then the full link line would be cc ip4.c -lsocket -lnsl.
249 + #include <sys/types.h>
250 + #include <sys/socket.h>
251 + #include <stdio.h>
252 + #include <netinet/in.h>
253 + #include <inttypes.h>
254 + #include <strings.h>
249 255
250 - #include <sys/types.h>
251 - #include <sys/socket.h>
252 - #include <stdio.h>
253 - #include <netinet/in.h>
254 - #include <inttypes.h>
255 - #include <strings.h>
256 + int
257 + main(void)
258 + {
259 + int sock;
260 + struct sockaddr_in in;
256 261
257 - int
258 - main(void)
259 - {
260 - int sock;
261 - struct sockaddr_in in;
262 + if ((sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
263 + perror("socket");
264 + return (1);
265 + }
262 266
263 - if ((sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
264 - perror("socket");
265 - return (1);
266 - }
267 + bzero(&in, sizeof (struct sockaddr_in));
268 + in.sin_family = AF_INET;
269 + in.sin_port = htons(80);
270 + if (inet_pton(AF_INET, "127.0.0.1", &in.sin_addr) != 1) {
271 + perror("inet_pton");
272 + return (1);
273 + }
267 274
268 - bzero(&in, sizeof (struct sockaddr_in));
269 - in.sin_family = AF_INET;
270 - in.sin_port = htons(80);
271 - if (inet_pton(AF_INET, "127.0.0.1", &in.sin_addr) != 1) {
272 - perror("inet_pton");
273 - return (1);
274 - }
275 + if (connect(sock, (struct sockaddr *)&in,
276 + sizeof (struct sockaddr_in)) != 0) {
277 + perror("connect");
278 + return (1);
279 + }
275 280
276 - if (connect(sock, (struct sockaddr *)&in,
277 - sizeof (struct sockaddr_in)) != 0) {
278 - perror("connect");
279 - return (1);
281 + /* use socket */
282 +
283 + return (0);
280 284 }
281 285
282 - /* use socket */
286 + Example 2 Preparing an IPv6 sockaddr_in6 to bind to a local address
287 + The following example shows how one would open a socket and
288 + prepare it to bind to the local IPv6 address ::1 port on port
289 + 12345.
283 290
284 - return (0);
285 - }
291 + #include <sys/types.h>
292 + #include <sys/socket.h>
293 + #include <stdio.h>
294 + #include <netinet/in.h>
295 + #include <inttypes.h>
296 + #include <strings.h>
286 297
287 - Example 2 Preparing an IPv6 sockaddr_in6 to bind to a local address
298 + int
299 + main(void)
300 + {
301 + int sock6;
302 + struct sockaddr_in6 in6;
288 303
289 - The following example shows how one would open a socket and prepare it to
290 - bind to the local IPv6 address ::1 port on port 12345. This program
291 - should be compiled with the C compiler cc and linked against the
292 - libraries libsocket and libnsl. If this example was named ip6.c, then
293 - the full compiler line would be cc ip6.c -lsocket -lnsl.
304 + if ((sock6 = socket(AF_INET6, SOCK_STREAM, 0)) < 0) {
305 + perror("socket");
306 + return (1);
307 + }
294 308
295 - #include <sys/types.h>
296 - #include <sys/socket.h>
297 - #include <stdio.h>
298 - #include <netinet/in.h>
299 - #include <inttypes.h>
300 - #include <strings.h>
309 + bzero(&in6, sizeof (struct sockaddr_in6));
310 + in6.sin6_family = AF_INET6;
311 + in6.sin6_port = htons(12345);
312 + if (inet_pton(AF_INET6, "::1", &in6.sin6_addr) != 1) {
313 + perror("inet_pton");
314 + return (1);
315 + }
301 316
302 - int
303 - main(void)
304 - {
305 - int sock6;
306 - struct sockaddr_in6 in6;
317 + if (bind(sock6, (struct sockaddr *)&in6,
318 + sizeof (struct sockaddr_in6)) != 0) {
319 + perror("bind");
320 + return (1);
321 + }
307 322
308 - if ((sock6 = socket(AF_INET6, SOCK_STREAM, 0)) < 0) {
309 - perror("socket");
310 - return (1);
311 - }
323 + /* use server socket */
312 324
313 - bzero(&in6, sizeof (struct sockaddr_in6));
314 - in6.sin6_family = AF_INET6;
315 - in6.sin6_port = htons(12345);
316 - if (inet_pton(AF_INET6, "::1", &in6.sin6_addr) != 1) {
317 - perror("inet_pton");
318 - return (1);
325 + return (0);
319 326 }
320 327
321 - if (bind(sock6, (struct sockaddr *)&in6,
322 - sizeof (struct sockaddr_in6)) != 0) {
323 - perror("bind");
324 - return (1);
325 - }
326 -
327 - /* use server socket */
328 -
329 - return (0);
330 - }
331 -
332 328 SEE ALSO
333 - socket(3HEAD), un.h(3HEAD), accept(3SOCKET), bind(3SOCKET),
334 - connect(3SOCKET), socket(3SOCKET), arp(7P), inet(7P), inet6(7P), ip(7P),
335 - ip6(7P)
329 + accept(3C), bind(3C), connect(3C), socket(3C), socket.h(3HEAD),
330 + un.h(3HEAD), arp(7P), inet(7P), inet6(7P), ip(7P), ip6(7P)
336 331
337 -illumos April 9, 2016 illumos
332 +illumos August 2, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX