1 Protocols if_tcp(7P)
2
3 NAME
4 if_tcp, if - general properties of Internet Protocol network
5 interfaces
6
7 DESCRIPTION
8 A network interface is a device for sending and receiving
9 packets on a network. It is usually a hardware device,
10 although it can be implemented in software. Network inter-
11 faces used by the Internet Protocol (IPv4 or IPv6) must be
12 STREAMS devices conforming to the Data Link Provider Inter-
13 face (DLPI). See dlpi(7P).
14
15 APPLICATION PROGRAMMING INTERFACE
16 An interface becomes available to IP when it is opened and
17 the IP module is pushed onto the stream with the I_PUSH
18 ioctl(2) command. (See streamio(7I)). The SIOCSLIFNAME
19 ioctl(2) is issued to specify the name of the interface and
20 to indicate whether it is IPv4 or IPv6. This may be ini-
21 tiated by the kernel at boot time or by a user program after
22 the system is running. Each interface must be assigned an IP
23 address with the SIOCSLIFADDR ioctl() before it can be used.
24 On interfaces where the network-to-link layer address map-
25 ping is static, only the network number is taken from the
26 ioctl() request; the remainder is found in a hardware
27 specific manner. On interfaces which provide dynamic
28 network-to-link layer address mapping facilities (for exam-
29 ple, 10Mb/s Ethernets using arp(7P)), the entire address
30 specified in the ioctl() is used. A routing table entry for
31 destinations on the network of the interface is installed
32 automatically when an interface's address is set.
33
34 IOCTLS
35 The following ioctl() calls may be used to manipulate IP
36 network interfaces. Unless specified otherwise, the request
37 takes an lifreq structure as its parameter. This structure
38 has the form:
39
40 struct lifreq {
41 #define LIFNAMSIZ 32
42 char lifr_name[LIFNAMSIZ]; /* if name, e.g. "le1" */
43 union {
44 int lifru_addrlen; /* for subnet/token etc */
45 uint_t lifru_ppa; /* SIOCSLIFNAME */
46 } lifr_lifru1;
47 union {
48 struct sockaddr_storage lifru_addr;
49 struct sockaddr_storage lifru_dstaddr;
50 struct sockaddr_storage lifru_broadaddr;
51 struct sockaddr_storage lifru_token; /* With lifr_addrlen */
52 struct sockaddr_storage lifru_subnet; /* With lifr_addrlen */
53 int lifru_index; /* interface index */
54 uint64_t lifru_flags; /* SIOC?LIFFLAGS */
55
56 SunOS 5.10 Last change: 14 Nov 2008 1
57
58 Protocols if_tcp(7P)
59
60 int lifru_metric;
61 uint_t lifru_mtu;
62 int lif_muxid[2]; /* mux id's for arp & ip */
63 struct lif_nd_req lifru_nd_req;
64 struct lif_ifinfo_req lifru_ifinfo_req;
65 zoneid_t lifru_zone; /* SIOC[GS]LIFZONE */
66 } lifr_lifru;
67
68 #define lifr_addrlen lifr_lifru1.lifru_addrlen
69 #define lifr_ppa lifr_lifru1.lifru_ppa /* Driver's ppa */
70 #define lifr_addr lifr_lifru.lifru_addr /* address */
71 #define lifr_dstaddr lifr_lifru.lifru_dstaddr
72 #define lifr_broadaddr lifr_lifru.lifru_broadaddr /* broadcast addr. */
73 #define lifr_token lifr_lifru.lifru_token /* address token */
74 #define lifr_subnet lifr_lifru.lifru_subnet /* subnet prefix */
75 #define lifr_index lifr_lifru.lifru_index /* interface index */
76 #define lifr_flags lifr_lifru.lifru_flags /* flags */
77 #define lifr_metric lifr_lifru.lifru_metric /* metric */
78 #define lifr_mtu lifr_lifru.lifru_mtu /* mtu */
79 #define lifr_ip_muxid lifr_lifru.lif_muxid[0]
80 #define lifr_arp_muxid lifr_lifru.lif_muxid[1]
81 #define lifr_nd lifr_lifru.lifru_nd_req /* SIOCLIF*ND */
82 #define lifr_ifinfo lifr_lifru.lifru_ifinfo_req /* SIOC[GS]LIFLNKINFO */
83 #define lifr_zone lifr_lifru.lifru_zone /* SIOC[GS]LIFZONE */
84 };
85
86 SIOCSLIFADDR Set interface address.
87
88 SIOCGLIFADDR Get interface address.
89
90 SIOCSLIFDSTADDR Set point to point address for inter-
91 face.
92
93 SIOCGLIFDSTADDR Get point to point address for inter-
94 face.
95
96 SIOCSLIFFLAGS Set interface flags field. If the inter-
97 face is marked down, any processes
98 currently routing packets through the
99 interface are notified.
100
101 SIOCGLIFFLAGS Get interface flags.
102
103 SIOCGLIFCONF Get interface configuration list. This
104 request takes an lifconf structure (see
105
106 SunOS 5.10 Last change: 14 Nov 2008 2
107
108 Protocols if_tcp(7P)
109
110 below) as a value-result parameter. The
111 lifc_family field can be set to
112 AF_UNSPEC to retrieve both AF_INET and
113 AF_INET6 interfaces. The lifc_flags
114 field should be set to zero. The
115 lifc_len field should be set to the size
116 of the buffer pointed to by lifc_buf.
117 Upon success, lifc_len will contain the
118 length, in bytes, of the array of lifreq
119 structures pointed to by lifc_req. For
120 each lifreq structure, the lifr_name and
121 lifr_addr fields will be valid.
122
123 SIOCGLIFNUM Get number of interfaces. This request
124 returns an integer which is the number
125 of interface descriptions (struct
126 lifreq) that will be returned by the
127 SIOCGLIFCONF ioctl; that is, it gives an
128 indication of how large lifc_len has to
129 be. This request takes an lifnum struc-
130 ture (see below) as a value-result
131 parameter. The lifn_family field should
132 be set to AF_UNSPEC to count both
133 AF_INET and AF_INET6 interfaces. The
134 lifn_flags field should be initially set
135 to zero.
136
137 SIOCSLIFMTU Set the maximum transmission unit (MTU)
138 size for interface. Place the request in
139 the lifru_mtu field. The MTU can not
140 exceed the physical MTU limitation
141 (which is reported in the DLPI
142 DL_INFO_ACK message).
143
144 SIOCGLIFMTU Get the maximum transmission unit size
145 for interface.
146
147 SIOCSLIFMETRIC Set the metric associated with the
148 interface. The metric is used by rout-
149 ing daemons such as in.routed(1M).
150
151 SIOCGLIFMETRIC Get the metric associated with the
152 interface.
153
154 SIOCGLIFMUXID Get the ip and arp muxid associated with
155 the interface.
156
157 SunOS 5.10 Last change: 14 Nov 2008 3
158
159 Protocols if_tcp(7P)
160
161 SIOCSLIFMUXID Set the ip and arp muxid associated with
162 the interface.
163
164 SIOCGLIFINDEX Get the interface index associated with
165 the interface.
166
167 SIOCSLIFINDEX Set the interface index associated with
168 the interface.
169
170 SIOCGLIFZONE Get the zone associated with the inter-
171 face.
172
173 SIOCSLIFZONE Set the zone associated with the inter-
174 face. Only applies for zones that use
175 the shared-IP instance.
176
177 SIOCLIFADDIF Add a new logical interface on a physi-
178 cal interface using an unused logical
179 unit number. If the physical interface
180 is part of an IP multipathing group, the
181 logical interface may be added to a dif-
182 ferent physical interface in the same
183 group. Upon return, the lifr_name field
184 contains the name of the actual logical
185 interface created.
186
187 SIOCLIFREMOVEIF Remove a logical interface by specifying
188 its IP address or logical interface
189 name. When the IP address is specified
190 and the interface is part of an IP mul-
191 tipathing group, the logical interface
192 is removed from the physical interface
193 in the group which holds the IP address.
194
195 SIOCSLIFTOKEN Set the address token used to form IPv6
196 link-local addresses and for stateless
197 address autoconfiguration.
198
199 SIOCGLIFTOKEN Get the address token used to form IPv6
200 link-local addresses and for stateless
201 address autoconfiguration.
202
203 SunOS 5.10 Last change: 14 Nov 2008 4
204
205 Protocols if_tcp(7P)
206
207 SIOCSLIFSUBNET Set the subnet prefix associated with
208 the interface.
209
210 SIOCGLIFSUBNET Get the subnet prefix associated with
211 the interface.
212
213 SIOCSLIFLNKINFO Set link specific parameters for the
214 interface.
215
216 SIOCGLIFLNKINFO Get link specific parameters for the
217 interface.
218
219 SIOCLIFDELND Delete a neighbor cache entry for IPv6.
220
221 SIOCLIFGETND Get a neighbor cache entry for IPv6.
222
223 SIOCLIFSETND Set a neighbor cache entry for IPv6.
224
225 SIOCSLIFUSESRC Set the interface from which to choose a
226 source address. The lifr_index field has
227 the interface index corresponding to the
228 interface whose address is to be used as
229 the source address for packets going out
230 on the interface whose name is provided
231 by lifr_name. If the lifr_index field is
232 set to zero, the previous setting is
233 cleared. See ifconfig(1M) for examples
234 of the usesrc option.
235
236 SIOCGLIFUSESRC Get the interface index of the interface
237 whose address is used as the source
238 address for packets going out on the
239 interface provided by lifr_name field.
240 The value is retrieved in the lifr_index
241 field. See ifconfig(1M) for examples of
242 the usesrc option.
243
244 SIOCGLIFSRCOF Get the interface configuration list for
245 interfaces that use an address hosted on
246 the interface provided by the
247 lifs_ifindex field in the lifsrcof
248 struct (see below), as a source address.
249 The application sets lifs_maxlen to the
250
251 SunOS 5.10 Last change: 14 Nov 2008 5
252
253 Protocols if_tcp(7P)
254
255 size (in bytes) of the buffer it has
256 allocated for the data. On return, the
257 kernel sets lifs_len to the actual size
258 required. Note, the application could
259 set lifs_maxlen to zero to query the
260 kernel of the required buffer size
261 instead of estimating a buffer size. The
262 application tests lifs_len <=
263 lifs_maxlen -- if that's true, the
264 buffer was big enough and the applica-
265 tion has an accurate list. If it is
266 false, it needs to allocate a bigger
267 buffer and try again, and lifs_len pro-
268 vides a hint of how big to make the next
269 trial. See ifconfig(1M) for examples of
270 the usesrc option.
271
272 SIOCTONLINK Test if the address is directly reach-
273 able, for example, that it can be
274 reached without going through a router.
275 This request takes an sioc_addrreq
276 structure (see below) as a value-result
277 parameter. The sa_addr field should be
278 set to the address to test. The sa_res
279 field will contain a non-zero value if
280 the address is onlink.
281
282 SIOCTMYADDR Test if the address is assigned to this
283 node. This request takes an sioc_addrreq
284 structure (see below) as a value-result
285 parameter. The sa_addr field should be
286 set to the address to test. The sa_res
287 field will contain a non-zero value if
288 the address is assigned to this node.
289
290 SIOCTMYSITE Test if the address is part of the same
291 site as this node. This request takes an
292 sioc_addrreq structure (see below) as a
293 value-result parameter. The sa_addr
294 field should be set to the address to
295 test. The sa_res field will contain a
296 non-zero value if the address is in the
297 same site.
298
299 The structure used by SIOCGLIFCONF has the form:
300
301 struct lifconf {
302 sa_family_t lifc_family;
303
304 SunOS 5.10 Last change: 14 Nov 2008 6
305
306 Protocols if_tcp(7P)
307
308 int lifc_flags; /* request specific
309 /* interfaces */
310 int lifc_len; /* size of assoc. buffer */
311 union {
312 caddr_t lifcu_buf;
313 struct lifreq *lifcu_req;
314 } lifc_lifcu;
315
316 #define lifc_buf lifc_lifcu.lifcu_buf /* buffer address */
317 #define lifc_req lifc_lifcu.lifcu_req /* array of structs returned */
318 };
319
320 The structure used by SIOCGLIFNUM has the form:
321 struct lifnum {
322 sa_family_t lifn_family;
323 int lifn_flags; /* req. specf. interfaces */
324 int lifn_count; /* Result */
325 };
326
327 The structure used by SIOCTONLINK, SIOCTMYADDR and SIOCTMYSITE has the form:
328
329 struct sioc_addrreq {
330 struct sockaddr_storage sa_addr; /* Address to test */
331 int sa_res; /* Result - 0/1 */
332 };
333
334 The structure used by SIOCGLIFSRCOF has the form:
335
336 struct lifsrcof {
337 uint_t lifs_ifindex; /* addr on this interface */
338 /* used as the src addr */
339 size_t lifs_maxlen; /* size of buffer: input */
340 size_t lifs_len; /* size of buffer: output */
341 union {
342 caddr_t lifsu_buf;
343 struct lifreq *lifsu_req;
344 } lifs_lifsu;
345 #define lifs_buf lifs_lifsu.lifsu_buf /* buffer addr. */
346 #define lifs_req lifs_lifsu.lifsu_req /* array returned */
347 };
348
349 The following ioctl() calls are maintained for compatibility
350 but only apply to IPv4 network interfaces, since the data
351 structures are too small to hold an IPv6 address. Unless
352 specified otherwise, the request takes an ifreq structure as
353 its parameter. This structure has the form:
354
355 struct ifreq {
356
357 SunOS 5.10 Last change: 14 Nov 2008 7
358
359 Protocols if_tcp(7P)
360
361 #define IFNAMSIZ 16
362 char ifr_name[IFNAMSIZ]; /* interface name - e.g. "hme0" */
363 union {
364 struct sockaddr ifru_addr;
365 struct sockaddr ifru_dstaddr;
366 struct sockaddr ifru_broadaddr;
367 short ifru_flags;
368 int ifru_metric;
369 int if_muxid[2]; /* mux id's for arp and ip */
370 int ifru_index; /* interface index */
371 } ifr_ifru;
372
373 #define ifr_addr ifr_ifru.ifru_addr /* address */
374 #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */
375 #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
376 #define ifr_flags ifr_ifru.ifru_flags /* flags */
377 #define ifr_index ifr_ifru.ifru_index /* interface index */
378 #define ifr_metric ifr_ifru.ifru_metric /* metric */
379 };
380
381 SIOCSIFADDR Set interface address.
382
383 SIOCGIFADDR Get interface address.
384
385 SIOCSIFDSTADDR Set point to point address for interface.
386
387 SIOCGIFDSTADDR Get point to point address for interface.
388
389 SIOCSIFFLAGS Set interface flags field. If the inter-
390 face is marked down, any processes
391 currently routing packets through the
392 interface are notified.
393
394 SIOCGIFFLAGS Get interface flags.
395
396 SIOCGIFCONF Get interface configuration list. This
397 request takes an ifconf structure (see
398 below) as a value-result parameter. The
399 ifc_len field should be set to the size
400 of the buffer pointed to by ifc_buf. Upon
401 success, ifc_len will contain the length,
402 in bytes, of the array of ifreq struc-
403 tures pointed to by ifc_req. For each
404 ifreq structure, the ifr_name and
405 ifr_addr fields will be valid.
406
407 SunOS 5.10 Last change: 14 Nov 2008 8
408
409 Protocols if_tcp(7P)
410
411 SIOCGIFNUM Get number of interfaces. This request
412 returns an integer which is the number of
413 interface descriptions (struct ifreq)
414 that will be returned by the SIOCGIFCONF
415 ioctl; that is, it gives an indication of
416 how large ifc_len has to be.
417
418 SIOCSIFMTU Set the maximum transmission unit (MTU)
419 size for interface. Place the request in
420 the ifr_metric field. The MTU has to be
421 smaller than physical MTU limitation
422 (which is reported in the DLPI
423 DL_INFO_ACK message).
424
425 SIOCGIFMTU Get the maximum transmission unit size
426 for interface. Upon success, the request
427 is placed in the ifr_metric field.
428
429 SIOCSIFMETRIC Set the metric associated with the inter-
430 face. The metric is used by routine dae-
431 mons such as in.routed(1M).
432
433 SIOCGIFMETRIC Get the metric associated with the inter-
434 face.
435
436 SIOCGIFMUXID Get the ip and arp muxid associated with
437 the interface.
438
439 SIOCSIFMUXID Set the ip and arp muxid associated with
440 the interface.
441
442 SIOCGIFINDEX Get the interface index associated with
443 the interface.
444
445 SIOCSIFINDEX Set the interface index associated with
446 the interface.
447
448 The ifconf structure has the form:
449
450 struct ifconf {
451 int ifc_len; /* size of assoc. buffer */
452 union {
453
454 SunOS 5.10 Last change: 14 Nov 2008 9
455
456 Protocols if_tcp(7P)
457
458 caddr_t ifcu_buf;
459 struct ifreq *ifcu_req;
460 } ifc_ifcu;
461
462 #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
463 #define ifc_req ifc_ifcu.ifcu_req /* array of structs returned */
464 };
465
466 IFF_ Flags
467 You can use the ifconfig(1M) command to display the IFF_
468 flags listed below (with the leading IFF_ prefix removed).
469 See the ifconfig(1M) manpage for a definition of each flag.
470
471 #define IFF_UP 0x0000000001 /* Interface is up */
472 #define IFF_BROADCAST 0x0000000002 /* Broadcast address valid */
473 #define IFF_DEBUG 0x0000000004 /* Turn on debugging */
474 #define IFF_LOOPBACK 0x0000000008 /* Loopback net */
475
476 #define IFF_POINTOPOINT 0x0000000010 /* Interface is p-to-p */
477 #define IFF_NOTRAILERS 0x0000000020 /* Avoid use of trailers */
478 #define IFF_RUNNING 0x0000000040 /* Resources allocated */
479 #define IFF_NOARP 0x0000000080 /* No address res. protocol */
480
481 #define IFF_PROMISC 0x0000000100 /* Receive all packets */
482 #define IFF_ALLMULTI 0x0000000200 /* Receive all multicast pkts */
483 #define IFF_INTELLIGENT 0x0000000400 /* Protocol code on board */
484 #define IFF_MULTICAST 0x0000000800 /* Supports multicast */
485
486 #define IFF_MULTI_BCAST 0x0000001000 /* Multicast using broadcst. add. */
487 #define IFF_UNNUMBERED 0x0000002000 /* Non-unique address */
488 #define IFF_DHCPRUNNING 0x0000004000 /* DHCP controls interface */
489 #define IFF_PRIVATE 0x0000008000 /* Do not advertise */
490
491 #define IFF_NOXMIT 0x0000010000 /* Do not transmit pkts */
492 #define IFF_NOLOCAL 0x0000020000 /* No address - just on-link subnet */
493 #define IFF_DEPRECATED 0x0000040000 /* Interface addr. deprecated */
494 #define IFF_ADDRCONF 0x0000080000 /* Addr. from stateless addrconf */
495
496 #define IFF_ROUTER 0x0000100000 /* Router on interface */
497 #define IFF_NONUD 0x0000200000 /* No NUD on interface */
498 #define IFF_ANYCAST 0x0000400000 /* Anycast address */
499 #define IFF_NORTEXCH 0x0000800000 /* Don't xchange rout. info */
500
501 #define IFF_IPV4 0x0001000000 /* IPv4 interface */
502 #define IFF_IPV6 0x0002000000 /* IPv6 interface */
503 #define IFF_NOFAILOVER 0x0008000000 /* No failover on NIC fail. */
504 #define IFF_FAILED 0x0010000000 /* NIC has failed */
505
506 #define IFF_STANDBY 0x0020000000 /* Standby NIC-use on fail. */
507 #define IFF_INACTIVE 0x0040000000 /* Stndby active or not? */
508 #define IFF_OFFLINE 0x0080000000 /* NIC offlined */
509
510 SunOS 5.10 Last change: 14 Nov 2008 10
511
512 Protocols if_tcp(7P)
513
514 #define IFF_XRESOLV 0x0100000000 /* IPv6 external resolver */
515
516 #define IFF_COS_ENABLED 0x0200000000 /* If CoS marking is supported */
517 #define IFF_PREFERRED 0x0400000000 /* Prefer as source address */
518 #define IFF_TEMPORARY 0x0800000000 /* RFC3041 */
519 #define IFF_FIXEDMTU 0x1000000000 /* MTU set with SIOCSLIFMTU */
520
521 #define IFF_VIRTUAL 0x2000000000 /* Cannot send/receive pkts */
522 #define IFF_DUPLICATE 0x4000000000 /* Local address in use */
523
524 ERRORS
525 EPERM Calling process has insufficient privileges.
526
527 ENXIO The lifr_name member of the lifreq structure
528 contains an invalid value.
529
530 For SIOCGLIFSRCOF, the lifs_ifindex member of
531 the lifsrcof structure contains an invalid
532 value.
533
534 For SIOCSLIFUSESRC, this error is returned if
535 the lifr_index is set to an invalid value.
536
537 EBADADDR Wrong address family or malformed address.
538
539 EBUSY For SIOCSLIFFLAGS, this error is returned when
540 the order of bringing the physical interface
541 (for example, eri0) and a logical interface
542 associated with the same physical interface
543 (for example, eri0:1) up or down is violated.
544 The physical interface must be configured up
545 first and cannot be configured down until all
546 the corresponding logical interfaces have been
547 configured down.
548
549 EINVAL For SIOCSLIFMTU, this error is returned when
550 the requested MTU size is invalid. This error
551 indicates the MTU size is greater than the MTU
552 size supported by the DLPI provider or less
553 than 68 (for IPv4) or less than 1280 (for
554 IPv6).
555
556 For SIOCSLIFUSESRC, this error is returned if
557 either the lifr_index or lifr_name identify
558 interfaces that are already part of an existing
559 IPMP group.
560
561 SunOS 5.10 Last change: 14 Nov 2008 11
562
563 Protocols if_tcp(7P)
564
565 EEXIST For SIOCLIFADDIF, this error is returned if the
566 lifr_name member in the lifreq structure
567 corresponds to an interface that already has
568 the PPA specified by lifr_ppa plumbed.
569
570 SEE ALSO
571 ifconfig(1M), in.routed(1M), ioctl(2), streamio(7I),
572 arp(7P), dlpi(7P), ip(7P), ip6(7P)
573