1if_tcp(7P) Protocols if_tcp(7P)
2
6 if_tcp, if - general properties of Internet Protocol network interfaces
7
9 A network interface is a device for sending and receiving packets on a
10 network. It is usually a hardware device, although it can be imple‐
11 mented in software. Network interfaces used by the Internet Protocol
12 (IPv4 or IPv6) must be STREAMS devices conforming to the Data Link
13 Provider Interface (DLPI). See dlpi(7P).
14
16 An interface becomes available to IP when it is opened and the IP mod‐
17 ule is pushed onto the stream with the I_PUSH ioctl(2) command. (See
18 streamio(7I)). The SIOCSLIFNAME ioctl(2) is issued to specify the name
19 of the interface and to indicate whether it is IPv4 or IPv6. This may
20 be initiated by the kernel at boot time or by a user program after the
21 system is running. Each interface must be assigned an IP address with
22 the SIOCSLIFADDR ioctl() before it can be used. On interfaces where the
23 network-to-link layer address mapping is static, only the network num‐
24 ber is taken from the ioctl() request; the remainder is found in a
25 hardware specific manner. On interfaces which provide dynamic network-
26 to-link layer address mapping facilities (for example, Ethernets using
27 arp(7P)), the entire address specified in the ioctl() is used. A rout‐
28 ing table entry for destinations on the network of the interface is
29 installed automatically when an interface's address is set.
30 You cannot create IPMP IP interfaces using the procedure described
33 above. Instead, use ifconfig(1M).
34
36 The following ioctl() calls may be used to manipulate IP network inter‐
37 faces. Unless specified otherwise, the request takes an lifreq struc‐
38 ture as its parameter. This structure has the form:
39 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 int lifru_metric;
56 uint_t lifru_mtu;
57 int lif_muxid[2]; /* mux id's for arp & ip */
58 struct lif_nd_req lifru_nd_req;
59 struct lif_ifinfo_req lifru_ifinfo_req;
60 zoneid_t lifru_zone; /* SIOC[GS]LIFZONE */
61 } lifr_lifru;
62 #define lifr_addrlen lifr_lifru1.lifru_addrlen
64 #define lifr_ppa lifr_lifru1.lifru_ppa /* Driver's ppa */
65 #define lifr_addr lifr_lifru.lifru_addr /* address */
66 #define lifr_dstaddr lifr_lifru.lifru_dstaddr
67 #define lifr_broadaddr lifr_lifru.lifru_broadaddr /* broadcast addr. */
68 #define lifr_token lifr_lifru.lifru_token /* address token */
69 #define lifr_subnet lifr_lifru.lifru_subnet /* subnet prefix */
70 #define lifr_index lifr_lifru.lifru_index /* interface index */
71 #define lifr_flags lifr_lifru.lifru_flags /* flags */
72 #define lifr_metric lifr_lifru.lifru_metric /* metric */
73 #define lifr_mtu lifr_lifru.lifru_mtu /* mtu */
74 #define lifr_ip_muxid lifr_lifru.lif_muxid[0]
75 #define lifr_arp_muxid lifr_lifru.lif_muxid[1]
76 #define lifr_nd lifr_lifru.lifru_nd_req /* SIOCLIF*ND */
77 #define lifr_ifinfo lifr_lifru.lifru_ifinfo_req /* SIOC[GS]LIFLNKINFO */
78 #define lifr_zone lifr_lifru.lifru_zone /* SIOC[GS]LIFZONE */
79 };
80 SIOCSLIFADDR Set interface address.
83 SIOCGLIFADDR Get interface address.
86 SIOCSLIFDSTADDR Set point to point address for interface.
89 SIOCGLIFDSTADDR Get point to point address for interface.
92 SIOCSLIFFLAGS Set interface flags field. If the interface is
95 marked down, any processes currently routing packets
96 through the interface are notified.
97 SIOCGLIFFLAGS Get interface flags.
100 SIOCGLIFCONF Get interface configuration list. This request takes
103 a lifconf structure (see below) as a value-result
104 parameter. The lifc_family field can be set to
105 AF_UNSPEC to retrieve both AF_INET and AF_INET6
106 interfaces. The lifc_len field should be set to the
107 size of the buffer pointed to by lifc_buf.
108 The lifc_flags field should usually be set to zero,
110 but callers that need low-level knowledge of the
111 underlying IP interfaces that comprise an IPMP group
112 can set it to LIFC_UNDER_IPMP to request that
113 those interfaces be included in the result. Upon
114 success, lifc_len contains the length, in bytes, of
115 the array of lifreq structures pointed to by
116 lifc_req. For each lifreq structure, the lifr_name
117 and lifr_addr fields are valid.
118 SIOCGLIFNUM Get number of interfaces. This request returns an
121 integer which is the number of interface descrip‐
122 tions (struct lifreq) returned by the SIOCGLIFCONF
123 ioctl (in other words, indicates how large lifc_len
124 must be).
125 This request takes a struct lifnum (see below) as
127 a value-result parameter. The lifn_family field can
128 be set to AF_UNSPEC to count both AF_INET and
129 AF_INET6 interfaces. The lifn_flags field should
130 usually be set to zero, but callers that need low-
131 level knowledge of the underlying IP interfaces that
132 comprise an IPMP group can set it to
133 LIFC_UNDER_IPMP to request that those interfaces be
134 included in the count.
135 SIOCSLIFMTU Set the maximum transmission unit (MTU) size for
138 interface. Place the request in the lifru_mtu field.
139 The MTU can not exceed the physical MTU limitation
140 (which is reported in the DLPI DL_INFO_ACK mes‐
141 sage).
142 SIOCGLIFMTU Get the maximum transmission unit size for inter‐
145 face.
146 SIOCSLIFMETRIC Set the metric associated with the interface. The
149 metric is used by routing daemons such as
150 in.routed(1M).
151 SIOCGLIFMETRIC Get the metric associated with the interface.
154 SIOCGLIFMUXID Get the ip and arp muxid associated with the inter‐
157 face.
158 SIOCSLIFMUXID Set the ip and arp muxid associated with the inter‐
161 face.
162 SIOCGLIFINDEX Get the interface index associated with the inter‐
165 face.
166 SIOCSLIFINDEX Set the interface index associated with the inter‐
169 face.
170 SIOCGLIFZONE Get the zone associated with the interface.
173 SIOCSLIFZONE Set the zone associated with the interface. Only
176 applies for zones that use the shared-IP instance.
177 SIOCLIFADDIF Add a new logical interface on a physical interface
180 using an unused logical interface number.
181 SIOCLIFREMOVEIF Remove a logical interface by specifying its IP
184 address or logical interface name.
185 SIOCSLIFTOKEN Set the address token used to form IPv6 link-local
188 addresses and for stateless address autoconfigura‐
189 tion.
190 SIOCGLIFTOKEN Get the address token used to form IPv6 link-local
193 addresses and for stateless address autoconfigura‐
194 tion.
195 SIOCSLIFSUBNET Set the subnet prefix associated with the interface.
198 SIOCGLIFSUBNET Get the subnet prefix associated with the interface.
201 SIOCSLIFLNKINFO Set link specific parameters for the interface.
204 SIOCGLIFLNKINFO Get link specific parameters for the interface.
207 SIOCLIFDELND Delete a neighbor cache entry for IPv6.
210 SIOCLIFGETND Get a neighbor cache entry for IPv6.
213 SIOCLIFSETND Set a neighbor cache entry for IPv6.
216 SIOCSLIFUSESRC Set the interface from which to choose a source
219 address. The lifr_index field has the interface
220 index corresponding to the interface whose address
221 is to be used as the source address for packets
222 going out on the interface whose name is provided by
223 lifr_name. If the lifr_index field is set to zero,
224 the previous setting is cleared. See ifconfig(1M)
225 for examples of the usesrc option.
226 SIOCGLIFUSESRC Get the interface index of the interface whose
229 address is used as the source address for packets
230 going out on the interface provided by lifr_name
231 field. The value is retrieved in the lifr_index
232 field. See ifconfig(1M) for examples of the usesrc
233 option.
234 SIOCGLIFSRCOF Get the interface configuration list for interfaces
237 that use an address hosted on the interface provided
238 by the lifs_ifindex field in the lifsrcof struct
239 (see below), as a source address. The application
240 sets lifs_maxlen to the size (in bytes) of the buf‐
241 fer it has allocated for the data. On return, the
242 kernel sets lifs_len to the actual size required.
243 Note, the application could set lifs_maxlen to zero
244 to query the kernel of the required buffer size
245 instead of estimating a buffer size. The application
246 tests lifs_len <= lifs_maxlen -- if that's true,
247 the buffer was big enough and the application has an
248 accurate list. If it is false, it needs to allocate
249 a bigger buffer and try again, and lifs_len provides
250 a hint of how big to make the next trial. See ifcon‐
251 fig(1M) for examples of the usesrc option.
252 SIOCTONLINK Test if the address is directly reachable, for exam‐
255 ple, that it can be reached without going through a
256 router. This request takes an sioc_addrreq structure
257 (see below) as a value-result parameter. The sa_addr
258 field should be set to the address to test. The
259 sa_res field will contain a non-zero value if the
260 address is onlink.
261 SIOCTMYADDR Test if the address is assigned to this node. This
264 request takes an sioc_addrreq structure (see below)
265 as a value-result parameter. The sa_addr field
266 should be set to the address to test. The sa_res
267 field will contain a non-zero value if the address
268 is assigned to this node.
269 SIOCTMYSITE Test if the address is part of the same site as this
272 node. This request takes an sioc_addrreq structure
273 (see below) as a value-result parameter. The sa_addr
274 field should be set to the address to test. The
275 sa_res field will contain a non-zero value if the
276 address is in the same site.
277 The structure used by SIOCGLIFCONF has the form:
281 struct lifconf {
283 sa_family_t lifc_family;
284 int lifc_flags; /* request specific
285 /* interfaces */
286 int lifc_len; /* size of assoc. buffer */
287 union {
288 caddr_t lifcu_buf;
289 struct lifreq *lifcu_req;
290 } lifc_lifcu;
291 #define lifc_buf lifc_lifcu.lifcu_buf /* buffer address */
293 #define lifc_req lifc_lifcu.lifcu_req /* array of structs returned */
294 };
295 The structure used by SIOCGLIFNUM has the form:
299 struct lifnum {
301 sa_family_t lifn_family;
302 int lifn_flags; /* req. specf. interfaces */
303 int lifn_count; /* Result */
304 };
305 The structure used by SIOCTONLINK, SIOCTMYADDR and SIOCTMYSITE has the
309 form:
310 struct sioc_addrreq {
312 struct sockaddr_storage sa_addr; /* Address to test */
313 int sa_res; /* Result - 0/1 */
314 };
315 The structure used by SIOCGLIFSRCOF has the form:
319 struct lifsrcof {
321 uint_t lifs_ifindex; /* addr on this interface */
322 /* used as the src addr */
323 size_t lifs_maxlen; /* size of buffer: input */
324 size_t lifs_len; /* size of buffer: output */
325 union {
326 caddr_t lifsu_buf;
327 struct lifreq *lifsu_req;
328 } lifs_lifsu;
329 #define lifs_buf lifs_lifsu.lifsu_buf /* buffer addr. */
330 #define lifs_req lifs_lifsu.lifsu_req /* array returned */
331 };
332 The following ioctl() calls are maintained for compatibility but only
336 apply to IPv4 network interfaces, since the data structures are too
337 small to hold an IPv6 address. Unless specified otherwise, the request
338 takes an ifreq structure as its parameter. This structure has the form:
339 struct ifreq {
341 #define IFNAMSIZ 16
342 char ifr_name[IFNAMSIZ]; /* interface name - e.g. "hme0" */
343 union {
344 struct sockaddr ifru_addr;
345 struct sockaddr ifru_dstaddr;
346 struct sockaddr ifru_broadaddr;
347 short ifru_flags;
348 int ifru_metric;
349 int if_muxid[2]; /* mux id's for arp and ip */
350 int ifru_index; /* interface index */
351 } ifr_ifru;
352 #define ifr_addr ifr_ifru.ifru_addr /* address */
354 #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */
355 #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */
356 #define ifr_flags ifr_ifru.ifru_flags /* flags */
357 #define ifr_index ifr_ifru.ifru_index /* interface index */
358 #define ifr_metric ifr_ifru.ifru_metric /* metric */
359 };
360 SIOCSIFADDR Set interface address.
363 SIOCGIFADDR Get interface address.
366 SIOCSIFDSTADDR Set point to point address for interface.
369 SIOCGIFDSTADDR Get point to point address for interface.
372 SIOCSIFFLAGS Set interface flags field. If the interface is marked
375 down, any processes currently routing packets through
376 the interface are notified.
377 SIOCGIFFLAGS Get interface flags.
380 SIOCGIFCONF Get interface configuration list. This request takes
383 an ifconf structure (see below) as a value-result
384 parameter. The ifc_len field should be set to the
385 size of the buffer pointed to by ifc_buf. Upon suc‐
386 cess, ifc_len will contain the length, in bytes, of
387 the array of ifreq structures pointed to by ifc_req.
388 For each ifreq structure, the ifr_name and ifr_addr
389 fields are valid. Though IPMP IP interfaces are
390 included in the array, underlying IP interfaces that
391 comprise those IPMP groups are not.
392 SIOCGIFNUM Get number of interfaces. This request returns an
395 integer which is the number of interface descriptions
396 (struct ifreq) returned by the SIOCGIFCONF ioctl (in
397 other words, indicates how large ifc_len must be).
398 Though IPMP IP interfaces are included in the array,
399 underlying IP interfaces that comprise those IPMP
400 groups are not.
401 SIOCSIFMTU Set the maximum transmission unit (MTU) size for
404 interface. Place the request in the ifr_metric field.
405 The MTU has to be smaller than physical MTU limita‐
406 tion (which is reported in the DLPI DL_INFO_ACK mes‐
407 sage).
408 SIOCGIFMTU Get the maximum transmission unit size for interface.
411 Upon success, the request is placed in the ifr_metric
412 field.
413 SIOCSIFMETRIC Set the metric associated with the interface. The
416 metric is used by routine daemons such as
417 in.routed(1M).
418 SIOCGIFMETRIC Get the metric associated with the interface.
421 SIOCGIFMUXID Get the ip and arp muxid associated with the inter‐
424 face.
425 SIOCSIFMUXID Set the ip and arp muxid associated with the inter‐
428 face.
429 SIOCGIFINDEX Get the interface index associated with the inter‐
432 face.
433 SIOCSIFINDEX Set the interface index associated with the inter‐
436 face.
437 The ifconf structure has the form:
441 struct ifconf {
443 int ifc_len; /* size of assoc. buffer */
444 union {
445 caddr_t ifcu_buf;
446 struct ifreq *ifcu_req;
447 } ifc_ifcu;
448 #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
450 #define ifc_req ifc_ifcu.ifcu_req /* array of structs returned */
451 };
452 IFF_ Flags
455 You can use the ifconfig(1M) command to display the IFF_ flags listed
456 below (with the leading IFF_ prefix removed). See the ifconfig(1M) man‐
457 page for a definition of each flag.
458 #define IFF_UP 0x0000000001 /* Address is up */
460 #define IFF_BROADCAST 0x0000000002 /* Broadcast address valid */
461 #define IFF_DEBUG 0x0000000004 /* Turn on debugging */
462 #define IFF_LOOPBACK 0x0000000008 /* Loopback net */
463 #define IFF_POINTOPOINT 0x0000000010 /* Interface is p-to-p */
465 #define IFF_NOTRAILERS 0x0000000020 /* Avoid use of trailers */
466 #define IFF_RUNNING 0x0000000040 /* Resources allocated */
467 #define IFF_NOARP 0x0000000080 /* No address res. protocol */
468 #define IFF_PROMISC 0x0000000100 /* Receive all packets */
470 #define IFF_ALLMULTI 0x0000000200 /* Receive all multicast pkts */
471 #define IFF_INTELLIGENT 0x0000000400 /* Protocol code on board */
472 #define IFF_MULTICAST 0x0000000800 /* Supports multicast */
473 #define IFF_MULTI_BCAST 0x0000001000 /* Multicast using broadcst. add. */
475 #define IFF_UNNUMBERED 0x0000002000 /* Non-unique address */
476 #define IFF_DHCPRUNNING 0x0000004000 /* DHCP controls interface */
477 #define IFF_PRIVATE 0x0000008000 /* Do not advertise */
478 #define IFF_NOXMIT 0x0000010000 /* Do not transmit pkts */
480 #define IFF_NOLOCAL 0x0000020000 /* No address - just on-link subnet */
481 #define IFF_DEPRECATED 0x0000040000 /* Address is deprecated */
482 #define IFF_ADDRCONF 0x0000080000 /* Addr. from stateless addrconf */
483 #define IFF_ROUTER 0x0000100000 /* Router on interface */
485 #define IFF_NONUD 0x0000200000 /* No NUD on interface */
486 #define IFF_ANYCAST 0x0000400000 /* Anycast address */
487 #define IFF_NORTEXCH 0x0000800000 /* Don't xchange rout. info */
488 #define IFF_IPV4 0x0001000000 /* IPv4 interface */
490 #define IFF_IPV6 0x0002000000 /* IPv6 interface */
491 #define IFF_NOFAILOVER 0x0008000000 /* in.mpathd test address */
492 #define IFF_FAILED 0x0010000000 /* Interface has failed */
493 #define IFF_STANDBY 0x0020000000 /* Interface is a hot-spare */
495 #define IFF_INACTIVE 0x0040000000 /* Functioning but not used */
496 #define IFF_OFFLINE 0x0080000000 /* Interface is offline */
497 #define IFF_XRESOLV 0x0100000000 /* IPv6 external resolver */
498 #define IFF_COS_ENABLED 0x0200000000 /* If CoS marking is supported */
500 #define IFF_PREFERRED 0x0400000000 /* Prefer as source address */
501 #define IFF_TEMPORARY 0x0800000000 /* RFC3041 */
502 #define IFF_FIXEDMTU 0x1000000000 /* MTU set with SIOCSLIFMTU */
503 #define IFF_VIRTUAL 0x2000000000 /* Cannot send/receive pkts */
505 #define IFF_DUPLICATE 0x4000000000 /* Local address in use */
506 #define IFF_IPMP 0x8000000000 /* IPMP IP interface */
507
510 EPERM Calling process has insufficient privileges.
511 ENXIO The lifr_name member of the lifreq structure contains an
514 invalid value.
515 For SIOCGLIFSRCOF, the lifs_ifindex member of the lifsrcof
517 structure contains an invalid value.
518 For SIOCSLIFUSESRC, this error is returned if the
520 lifr_index is set to an invalid value.
521 EBADADDR Wrong address family or malformed address.
524 EINVAL For SIOCSLIFMTU, this error is returned when the requested
527 MTU size is invalid. This error indicates the MTU size is
528 greater than the MTU size supported by the DLPI provider or
529 less than 68 (for IPv4) or less than 1280 (for IPv6).
530 For SIOCSLIFUSESRC, this error is returned if either the
532 lifr_index or lifr_name identify interfaces that are
533 already part of an existing IPMP group.
534 EEXIST For SIOCLIFADDIF, this error is returned if the lifr_name
537 member in the lifreq structure corresponds to an interface
538 that already has the PPA specified by lifr_ppa plumbed.
539
542 ifconfig(1M), in.routed(1M), ioctl(2), streamio(7I), arp(7P), dlpi(7P),
543 ip(7P), ip6(7P)
544SunOS 5.11 14 Sep 2009 if_tcp(7P)