Protocols iftcp(7P)
NAME
iftcp, if - general properties of Internet Protocol network
interfaces
DESCRIPTION
A network interface is a device for sending and receiving
packets on a network. It is usually a hardware device,
although it can be implemented in software. Network inter-
faces used by the Internet Protocol (IPv4 or IPv6) must be
STREAMS devices conforming to the Data Link Provider Inter-
face (DLPI). See dlpi(7P).
APLICATION PROGRAMING INTERFACE
An interface becomes available to IP when it is opened and
the IP module is pushed onto the stream with the IPUSH
ioctl(2) command. (See streamio(7I)). The SIOCSLIFNAME
ioctl(2) is issued to specify the name of the interface and
to indicate whether it is IPv4 or IPv6. This may be ini-
tiated by the kernel at boot time or by a user program after
the system is running. Each interface must be assigned an IP
address with the SIOCSLIFADR ioctl() before it can be used.
On interfaces where the network-to-link layer address map-
ping is static, only the network number is taken from the
ioctl() request; the remainder is found in a hardware
specific manner. On interfaces which provide dynamic
network-to-link layer address mapping facilities (for exam-
ple, Ethernets using arp(7P)), the entire address specified
in the ioctl() is used. A routing table entry for destina-
tions on the network of the interface is installed automati-
cally when an interface's address is set.
You cannot create IPMP IP interfaces using the procedure
described above. Instead, use ifconfig(1M).
IOCTLS
The following ioctl() calls may be used to manipulate IP
network interfaces. Unless specified otherwise, the request
takes an lifreq structure as its parameter. This structure
has the form:
struct lifreq {
#define LIFNAMSIZ 32
char lifrname[LIFNAMSIZ]; /* if name, e.g. "le1" */
union {
int lifruaddrlen; /* for subnet/token etc */
uintt lifruppa; /* SIOCSLIFNAME */
} lifrlifru1;
union {
struct sockaddrstorage lifruaddr;
struct sockaddrstorage lifrudstaddr;
struct sockaddrstorage lifrubroadaddr;
SunOS 5.11 Last change: 5 Feb 2009 1
Protocols iftcp(7P)
struct sockaddrstorage lifrutoken; /* With lifraddrlen */
struct sockaddrstorage lifrusubnet; /* With lifraddrlen */
int lifruindex; /* interface index */
uint64t lifruflags; /* SIOC?LIFLAGS */
int lifrumetric;
uintt lifrumtu;
int lifmuxid[2]; /* mux id's for arp & ip */
struct lifndreq lifrundreq;
struct lififinforeq lifruifinforeq;
zoneidt lifruzone; /* SIOC[GS]LIFZONE */
} lifrlifru;
#define lifraddrlen lifrlifru1.lifruaddrlen
#define lifrppa lifrlifru1.lifruppa /* Driver's ppa */
#define lifraddr lifrlifru.lifruaddr /* address */
#define lifrdstaddr lifrlifru.lifrudstaddr
#define lifrbroadaddr lifrlifru.lifrubroadaddr /* broadcast addr. */
#define lifrtoken lifrlifru.lifrutoken /* address token */
#define lifrsubnet lifrlifru.lifrusubnet /* subnet prefix */
#define lifrindex lifrlifru.lifruindex /* interface index */
#define lifrflags lifrlifru.lifruflags /* flags */
#define lifrmetric lifrlifru.lifrumetric /* metric */
#define lifrmtu lifrlifru.lifrumtu /* mtu */
#define lifripmuxid lifrlifru.lifmuxid[0]
#define lifrarpmuxid lifrlifru.lifmuxid[1]
#define lifrnd lifrlifru.lifrundreq /* SIOCLIF*ND */
#define lifrifinfo lifrlifru.lifruifinforeq /* SIOC[GS]LIFLNKINFO */
#define lifrzone lifrlifru.lifruzone /* SIOC[GS]LIFZONE */
};
SIOCSLIFADR Set interface address.
SIOCGLIFADR Get interface address.
SIOCSLIFDSTADR Set point to point address for interface.
SIOCGLIFDSTADR Get point to point address for interface.
SIOCSLIFLAGS Set interface flags field. If the inter-
face is marked down, any processes
currently routing packets through the
interface are notified.
SIOCGLIFLAGS Get interface flags.
SunOS 5.11 Last change: 5 Feb 2009 2
Protocols iftcp(7P)
SIOCGLIFCONF Get interface configuration list. This
request takes a lifconf structure (see
below) as a value-result parameter. The
lifcfamily field can be set to
AFUNSPEC to retrieve both AFINET and
AFINET6 interfaces. The lifclen field
should be set to the size of the buffer
pointed to by lifcbuf.
The lifcflags field should usually be
set to zero, but callers that need low-
level knowledge of the underlying IP
interfaces that comprise an IPMP group
can set it to LIFCUNDERIPMP to
request that those interfaces be included
in the result. Upon success, lifclen
contains the length, in bytes, of the
array of lifreq structures pointed to
by lifcreq. For each lifreq structure,
the lifrname and lifraddr fields are
valid.
SIOCGLIFNUM Get number of interfaces. This request
returns an integer which is the number of
interface descriptions (struct lifreq)
returned by the SIOCGLIFCONF ioctl (in
other words, indicates how large lifclen
must be).
This request takes a struct lifnum
(see below) as a value-result parameter.
The lifnfamily field can be set to
AFUNSPEC to count both AFINET and
AFINET6 interfaces. The lifnflags field
should usually be set to zero, but call-
ers that need low-level knowledge of the
underlying IP interfaces that comprise an
IPMP group can set it to LIFCUNDERIPMP
to request that those interfaces be
included in the count.
SIOCSLIFMTU Set the maximum transmission unit (MTU)
size for interface. Place the request in
the lifrumtu field. The MTU can not
exceed the physical MTU limitation
(which is reported in the DLPI
DLINFOACK message).
SunOS 5.11 Last change: 5 Feb 2009 3
Protocols iftcp(7P)
SIOCGLIFMTU Get the maximum transmission unit size
for interface.
SIOCSLIFMETRIC Set the metric associated with the inter-
face. The metric is used by routing dae-
mons such as in.routed(1M).
SIOCGLIFMETRIC Get the metric associated with the inter-
face.
SIOCGLIFMUXID Get the ip and arp muxid associated with
the interface.
SIOCSLIFMUXID Set the ip and arp muxid associated with
the interface.
SIOCGLIFINDEX Get the interface index associated with
the interface.
SIOCSLIFINDEX Set the interface index associated with
the interface.
SIOCGLIFZONE Get the zone associated with the inter-
face.
SIOCSLIFZONE Set the zone associated with the inter-
face. Only applies for zones that use the
shared-IP instance.
SIOCLIFADIF Add a new logical interface on a physical
interface using an unused logical inter-
face number.
SIOCLIFREMOVEIF Remove a logical interface by specifying
its IP address or logical interface name.
SIOCSLIFTOKEN Set the address token used to form IPv6
link-local addresses and for stateless
address autoconfiguration.
SunOS 5.11 Last change: 5 Feb 2009 4
Protocols iftcp(7P)
SIOCGLIFTOKEN Get the address token used to form IPv6
link-local addresses and for stateless
address autoconfiguration.
SIOCSLIFSUBNET Set the subnet prefix associated with the
interface.
SIOCGLIFSUBNET Get the subnet prefix associated with the
interface.
SIOCSLIFLNKINFO Set link specific parameters for the
interface.
SIOCGLIFLNKINFO Get link specific parameters for the
interface.
SIOCLIFDELND Delete a neighbor cache entry for IPv6.
SIOCLIFGETND Get a neighbor cache entry for IPv6.
SIOCLIFSETND Set a neighbor cache entry for IPv6.
SIOCSLIFUSESRC Set the interface from which to choose a
source address. The lifrindex field has
the interface index corresponding to the
interface whose address is to be used as
the source address for packets going out
on the interface whose name is provided
by lifrname. If the lifrindex field is
set to zero, the previous setting is
cleared. See ifconfig(1M) for examples
of the usesrc option.
SIOCGLIFUSESRC Get the interface index of the interface
whose address is used as the source
address for packets going out on the
interface provided by lifrname field.
The value is retrieved in the lifrindex
field. See ifconfig(1M) for examples of
the usesrc option.
SunOS 5.11 Last change: 5 Feb 2009 5
Protocols iftcp(7P)
SIOCGLIFSRCOF Get the interface configuration list for
interfaces that use an address hosted on
the interface provided by the
lifsifindex field in the lifsrcof struct
(see below), as a source address. The
application sets lifsmaxlen to the size
(in bytes) of the buffer it has allocated
for the data. On return, the kernel sets
lifslen to the actual size required.
Note, the application could set
lifsmaxlen to zero to query the kernel
of the required buffer size instead of
estimating a buffer size. The application
tests lifslen <= lifsmaxlen -- if
that's true, the buffer was big enough
and the application has an accurate list.
If it is false, it needs to allocate a
bigger buffer and try again, and lifslen
provides a hint of how big to make the
next trial. See ifconfig(1M) for examples
of the usesrc option.
SIOCTONLINK Test if the address is directly reach-
able, for example, that it can be reached
without going through a router. This
request takes an siocaddrreq structure
(see below) as a value-result parameter.
The saaddr field should be set to the
address to test. The sares field will
contain a non-zero value if the address
is onlink.
SIOCTMYADR Test if the address is assigned to this
node. This request takes an siocaddrreq
structure (see below) as a value-result
parameter. The saaddr field should be
set to the address to test. The sares
field will contain a non-zero value if
the address is assigned to this node.
SIOCTMYSITE Test if the address is part of the same
site as this node. This request takes an
siocaddrreq structure (see below) as a
value-result parameter. The saaddr field
should be set to the address to test. The
sares field will contain a non-zero
value if the address is in the same site.
SunOS 5.11 Last change: 5 Feb 2009 6
Protocols iftcp(7P)
The structure used by SIOCGLIFCONF has the form:
struct lifconf {
safamilyt lifcfamily;
int lifcflags; /* request specific
/* interfaces */
int lifclen; /* size of assoc. buffer */
union {
caddrt lifcubuf;
struct lifreq *lifcureq;
} lifclifcu;
#define lifcbuf lifclifcu.lifcubuf /* buffer address */
#define lifcreq lifclifcu.lifcureq /* array of structs returned */
};
The structure used by SIOCGLIFNUM has the form:
struct lifnum {
safamilyt lifnfamily;
int lifnflags; /* req. specf. interfaces */
int lifncount; /* Result */
};
The structure used by SIOCTONLINK, SIOCTMYADR and
SIOCTMYSITE has the form:
struct siocaddrreq {
struct sockaddrstorage saaddr; /* Address to test */
int sares; /* Result - 0/1 */
};
The structure used by SIOCGLIFSRCOF has the form:
struct lifsrcof {
uintt lifsifindex; /* addr on this interface */
/* used as the src addr */
sizet lifsmaxlen; /* size of buffer: input */
sizet lifslen; /* size of buffer: output */
union {
caddrt lifsubuf;
struct lifreq *lifsureq;
} lifslifsu;
#define lifsbuf lifslifsu.lifsubuf /* buffer addr. */
#define lifsreq lifslifsu.lifsureq /* array returned */
};
SunOS 5.11 Last change: 5 Feb 2009 7
Protocols iftcp(7P)
The following ioctl() calls are maintained for compatibility
but only apply to IPv4 network interfaces, since the data
structures are too small to hold an IPv6 address. Unless
specified otherwise, the request takes an ifreq structure as
its parameter. This structure has the form:
struct ifreq {
#define IFNAMSIZ 16
char ifrname[IFNAMSIZ]; /* interface name - e.g. "hme0" */
union {
struct sockaddr ifruaddr;
struct sockaddr ifrudstaddr;
struct sockaddr ifrubroadaddr;
short ifruflags;
int ifrumetric;
int ifmuxid[2]; /* mux id's for arp and ip */
int ifruindex; /* interface index */
} ifrifru;
#define ifraddr ifrifru.ifruaddr /* address */
#define ifrdstaddr ifrifru.ifrudstaddr /* other end of p-to-p link */
#define ifrbroadaddr ifrifru.ifrubroadaddr /* broadcast address */
#define ifrflags ifrifru.ifruflags /* flags */
#define ifrindex ifrifru.ifruindex /* interface index */
#define ifrmetric ifrifru.ifrumetric /* metric */
};
SIOCSIFADR Set interface address.
SIOCGIFADR Get interface address.
SIOCSIFDSTADR Set point to point address for interface.
SIOCGIFDSTADR Get point to point address for interface.
SIOCSIFLAGS Set interface flags field. If the inter-
face is marked down, any processes
currently routing packets through the
interface are notified.
SIOCGIFLAGS Get interface flags.
SIOCGIFCONF Get interface configuration list. This
request takes an ifconf structure (see
below) as a value-result parameter. The
SunOS 5.11 Last change: 5 Feb 2009 8
Protocols iftcp(7P)
ifclen field should be set to the size of
the buffer pointed to by ifcbuf. Upon
success, ifclen will contain the length,
in bytes, of the array of ifreq structures
pointed to by ifcreq. For each ifreq
structure, the ifrname and ifraddr
fields are valid. Though IPMP IP inter-
faces are included in the array, underly-
ing IP interfaces that comprise those IPMP
groups are not.
SIOCGIFNUM Get number of interfaces. This request
returns an integer which is the number of
interface descriptions (struct ifreq)
returned by the SIOCGIFCONF ioctl (in
other words, indicates how large ifclen
must be). Though IPMP IP interfaces are
included in the array, underlying IP
interfaces that comprise those IPMP groups
are not.
SIOCSIFMTU Set the maximum transmission unit (MTU)
size for interface. Place the request in
the ifrmetric field. The MTU has to be
smaller than physical MTU limitation
(which is reported in the DLPI DLINFOACK
message).
SIOCGIFMTU Get the maximum transmission unit size for
interface. Upon success, the request is
placed in the ifrmetric field.
SIOCSIFMETRIC Set the metric associated with the inter-
face. The metric is used by routine dae-
mons such as in.routed(1M).
SIOCGIFMETRIC Get the metric associated with the inter-
face.
SIOCGIFMUXID Get the ip and arp muxid associated with
the interface.
SIOCSIFMUXID Set the ip and arp muxid associated with
the interface.
SunOS 5.11 Last change: 5 Feb 2009 9
Protocols iftcp(7P)
SIOCGIFINDEX Get the interface index associated with
the interface.
SIOCSIFINDEX Set the interface index associated with
the interface.
The ifconf structure has the form:
struct ifconf {
int ifclen; /* size of assoc. buffer */
union {
caddrt ifcubuf;
struct ifreq *ifcureq;
} ifcifcu;
#define ifcbuf ifcifcu.ifcubuf /* buffer address */
#define ifcreq ifcifcu.ifcureq /* array of structs returned */
};
IF Flags
You can use the ifconfig(1M) command to display the IF
flags listed below (with the leading IF prefix removed).
See the ifconfig(1M) manpage for a definition of each flag.
#define IFUP 0x0000000001 /* Address is up */
#define IFBROADCAST 0x0000000002 /* Broadcast address valid */
#define IFDEBUG 0x0000000004 /* Turn on debugging */
#define IFLOPBACK 0x0000000008 /* Loopback net */
#define IFPOINTOPOINT 0x0000000010 /* Interface is p-to-p */
#define IFNOTRAILERS 0x0000000020 /* Avoid use of trailers */
#define IFRUNING 0x0000000040 /* Resources allocated */
#define IFNOARP 0x0000000080 /* No address res. protocol */
#define IFPROMISC 0x0000000100 /* Receive all packets */
#define IFALMULTI 0x0000000200 /* Receive all multicast pkts */
#define IFINTELIGENT 0x0000000400 /* Protocol code on board */
#define IFMULTICAST 0x0000000800 /* Supports multicast */
#define IFMULTIBCAST 0x0000001000 /* Multicast using broadcst. add. */
#define IFUNUMBERED 0x0000002000 /* Non-unique address */
#define IFDHCPRUNING 0x0000004000 /* DHCP controls interface */
#define IFPRIVATE 0x0000008000 /* Do not advertise */
#define IFNOXMIT 0x0000010000 /* Do not transmit pkts */
#define IFNOLOCAL 0x0000020000 /* No address - just on-link subnet */
#define IFDEPRECATED 0x0000040000 /* Address is deprecated */
#define IFADRCONF 0x0000080000 /* Addr. from stateless addrconf */
SunOS 5.11 Last change: 5 Feb 2009 10
Protocols iftcp(7P)
#define IFROUTER 0x0000100000 /* Router on interface */
#define IFNONUD 0x0000200000 /* No NUD on interface */
#define IFANYCAST 0x0000400000 /* Anycast address */
#define IFNORTEXCH 0x0000800000 /* Don't xchange rout. info */
#define IFIPV4 0x0001000000 /* IPv4 interface */
#define IFIPV6 0x0002000000 /* IPv6 interface */
#define IFNOFAILOVER 0x0008000000 /* in.mpathd test address */
#define IFAILED 0x0010000000 /* Interface has failed */
#define IFSTANDBY 0x0020000000 /* Interface is a hot-spare */
#define IFINACTIVE 0x0040000000 /* Functioning but not used */
#define IFOFLINE 0x0080000000 /* Interface is offline */
#define IFXRESOLV 0x0100000000 /* IPv6 external resolver */
#define IFCOSENABLED 0x0200000000 /* If CoS marking is supported */
#define IFPREFERED 0x0400000000 /* Prefer as source address */
#define IFTEMPORARY 0x0800000000 /* RFC3041 */
#define IFIXEDMTU 0x1000000000 /* MTU set with SIOCSLIFMTU */
#define IFVIRTUAL 0x2000000000 /* Cannot send/receive pkts */
#define IFDUPLICATE 0x4000000000 /* Local address in use */
#define IFIPMP 0x8000000000 /* IPMP IP interface */
ERORS
EPERM Calling process has insufficient privileges.
ENXIO The lifrname member of the lifreq structure
contains an invalid value.
For SIOCGLIFSRCOF, the lifsifindex member of
the lifsrcof structure contains an invalid
value.
For SIOCSLIFUSESRC, this error is returned if
the lifrindex is set to an invalid value.
EBADADR Wrong address family or malformed address.
EBUSY For SIOCSLIFLAGS, this error is returned when
the order of bringing the physical interface
(for example, eri0) and a logical interface
associated with the same physical interface (for
example, eri0:1) up or down is violated. The
physical interface must be configured up first
and cannot be configured down until all the
corresponding logical interfaces have been con-
figured down.
SunOS 5.11 Last change: 5 Feb 2009 11
Protocols iftcp(7P)
EINVAL For SIOCSLIFMTU, this error is returned when the
requested MTU size is invalid. This error indi-
cates the MTU size is greater than the MTU size
supported by the DLPI provider or less than 68
(for IPv4) or less than 1280 (for IPv6).
For SIOCSLIFUSESRC, this error is returned if
either the lifrindex or lifrname identify
interfaces that are already part of an existing
IPMP group.
EXIST For SIOCLIFADIF, this error is returned if the
lifrname member in the lifreq structure
corresponds to an interface that already has the
PA specified by lifrppa plumbed.
SEE ALSO
ifconfig(1M), in.routed(1M), ioctl(2), streamio(7I),
arp(7P), dlpi(7P), ip(7P), ip6(7P)
SunOS 5.11 Last change: 5 Feb 2009 12
|
