VxWorks API Reference : OS Libraries
ifLib - network interface library
ifUnnumberedSet( ) - configure an interface to be unnumbered
ifAddrAdd( ) - add an interface address for a network interface
ifAddrSet( ) - set an interface address for a network interface
ifAddrDelete( ) - delete an interface address for a network interface
ifAddrGet( ) - get the Internet address of a network interface
ifBroadcastSet( ) - set the broadcast address for a network interface
ifBroadcastGet( ) - get the broadcast address for a network interface
ifDstAddrSet( ) - define an address for the other end of a point-to-point link
ifDstAddrGet( ) - get the Internet address of a point-to-point peer
ifMaskSet( ) - define a subnet for a network interface
ifMaskGet( ) - get the subnet mask for a network interface
ifFlagChange( ) - change the network interface flags
ifFlagSet( ) - specify the flags for a network interface
ifFlagGet( ) - get the network interface flags
ifMetricSet( ) - specify a network interface hop count
ifMetricGet( ) - get the metric for a network interface
ifRouteDelete( ) - delete routes associated with a network interface
ifAllRoutesDelete( ) - delete all routes associated with a network interface
ifunit( ) - map an interface name to an interface structure pointer
ifNameToIfIndex( ) - returns the interface index given the interface name
ifIndexToIfName( ) - returns the interface name given the interface index
This library contains routines to configure the network interface parameters. Generally, each routine corresponds to one of the functions of the UNIX command ifconfig.
To use this feature, include the following component: INCLUDE_NETWRS_IFLIB
ifLib.h
ifUnnumberedSet( ) - configure an interface to be unnumbered
#ifdef ROUTER_STACK STATUS ifUnnumberedSet ( char * pIfName, /* Name of interface to configure */ char * pDstIp, /* Destination address of the point to */ /* point link */ char * pBorrowedIp, /* The borrowed IP address/router ID */ char * pDstMac /* Destination MAC address */ )
This API sets an interface unnumbered. It sets the IFF_POINTOPOINT flags and creates a routing entry through the interface using a user-specified destination IP address. The unnumbered link can then be uniquely referred to by the destination IP address, pDstIp, when adding routes. The interface is assigned a "borrowed" IP address--borrowed from another interface on the machine. In RFC 1812 it is also called the router ID. This address will be used to generate any needed ICMP messages or the like. Note that ARP is not able to run on an unnumbered link.
The initialization of the unnumbered device is similar to other network devices, but it does have a few additional steps and concerns. ifUnnumberedSet( ) must come next after ipAttach( ). Please note that the interface using the IP address that the unnumbered interface will borrow must be brought up first and configured with ifAddrSet or equivalent. This is required to ensure normal network operation for that IP address/interface. After ifUnnumberedSet( ), one must create additional routing entries (using mRouteAdd( ), routeNetAdd( ), etc) in order to reach other networks, including the network to which the destination IP address belongs.
The pDstMac field in ifUnnumberedSet( ) is used to specify the destination's MAC address. It should be left NULL if the destination is not an Ethernet device. If the MAC address is not known, then supply an artificial address. We recommend using "00:00:00:00:00:01" The destination interface can then be set promiscuous to accept this artificial address. This is accomplished using the ifpromisc command.
Example:
ipAttach (1, "fei") ifUnnumberedSet ("fei1", "120.12.12.12", "140.34.78.94", "00:a0:d0:d8:c8:14") routeNetAdd ("120.12.0.0","120.12.12.12")routeNetAdd ("178.45.0.0","120.12.12.12")
OK, or ERROR if the interface cannot be set.
ifAddrAdd( ) - add an interface address for a network interface
STATUS ifAddrAdd ( char * interfaceName, /* name of interface to configure */ char * interfaceAddress, /* Internet address to assign to interface */ char * broadcastAddress, /* broadcast address to assign to interface */ int subnetMask /* subnetMask */ )
This routine assigns an Internet address to a specified network interface. The Internet address can be a host name or a standard Internet address format (e.g., 90.0.0.4). If a host name is specified, it should already have been added to the host table with hostAdd( ).
You must specify both an interfaceName and an interfaceAddress. A broadcastAddress is optional. If broadcastAddress is NULL, in_ifinit( ) generates a broadcastAddress value based on the interfaceAddress value and the netmask. A subnetMask value is optional. If subnetMask is 0, in_ifinit( ) uses a subnetMask the same as the netmask that is generated by the interfaceAddress. The broadcastAddress is also destAddress in case of IFF_POINTOPOINT.
OK, or ERROR if the interface cannot be set.
ifLib, ifAddrGet( ), ifDstAddrSet( ), ifDstAddrGet( )
ifAddrSet( ) - set an interface address for a network interface
STATUS ifAddrSet ( char * interfaceName, /* name of interface to configure, i.e. ei0 */ char * interfaceAddress /* Internet address to assign to interface */ )
This routine assigns an Internet address to a specified network interface. The Internet address can be a host name or a standard Internet address format (e.g., 90.0.0.4). If a host name is specified, it should already have been added to the host table with hostAdd( ).
A successful call to ifAddrSet( ) results in the addition of a new route.
The subnet mask used in determining the network portion of the address will be that set by ifMaskSet( ), or the default class mask if ifMaskSet( ) has not been called. It is standard practice to call ifMaskSet( ) prior to calling ifAddrSet( ).
OK, or ERROR if the interface cannot be set.
ifLib, ifAddrGet( ), ifDstAddrSet( ), ifDstAddrGet( )
ifAddrDelete( ) - delete an interface address for a network interface
STATUS ifAddrDelete ( char * interfaceName, /* name of interface to delete addr from */ char * interfaceAddress /* Internet address to delete from interface */ )
This routine deletes an Internet address from a specified network interface. The Internet address can be a host name or a standard Internet address format (e.g., 90.0.0.4). If a host name is specified, it should already have been added to the host table with hostAdd( ).
OK, or ERROR if the interface cannot be deleted.
ifLib, ifAddrGet( ), ifDstAddrSet( ), ifDstAddrGet( )
ifAddrGet( ) - get the Internet address of a network interface
STATUS ifAddrGet ( char * interfaceName, /* name of interface, i.e. ei0 */ char * interfaceAddress /* buffer for Internet address */ )
This routine gets the Internet address of a specified network interface and copies it to interfaceAddress. This pointer should point to a buffer large enough to contain INET_ADDR_LEN bytes.
OK or ERROR.
ifLib, ifAddrSet( ), ifDstAddrSet( ), ifDstAddrGet( )
ifBroadcastSet( ) - set the broadcast address for a network interface
STATUS ifBroadcastSet ( char * interfaceName, /* name of interface to assign, i.e. ei0 */ char * broadcastAddress /* broadcast address to assign to interface */ )
This routine assigns a broadcast address for the specified network interface. The broadcast address must be a string in standard Internet address format (e.g., 90.0.0.0).
An interface's default broadcast address is its Internet address with a host part of all ones (e.g., 90.255.255.255). This conforms to current ARPA specifications. However, some older systems use an Internet address with a host part of all zeros as the broadcast address.
VxWorks automatically accepts a host part of all zeros as a broadcast address, in addition to the default or specified broadcast address. But if VxWorks is to broadcast to older systems using a host part of all zeros as the broadcast address, this routine should be used to change the broadcast address of the interface.
OK or ERROR.
ifBroadcastGet( ) - get the broadcast address for a network interface
STATUS ifBroadcastGet ( char * interfaceName, /* name of interface, i.e. ei0 */ char * broadcastAddress /* buffer for broadcast address */ )
This routine gets the broadcast address for a specified network interface. The broadcast address is copied to the buffer broadcastAddress.
OK or ERROR.
ifLib, ifBroadcastSet( )
ifDstAddrSet( ) - define an address for the other end of a point-to-point link
STATUS ifDstAddrSet ( char * interfaceName, /* name of interface to configure, i.e. ei0 */ char * dstAddress /* Internet address to assign to destination */ )
This routine assigns the Internet address of a machine connected to the opposite end of a point-to-point network connection, such as a SLIP connection. Inherently, point-to-point connection-oriented protocols such as SLIP require that addresses for both ends of a connection be specified.
OK or ERROR.
ifLib, ifAddrSet( ), ifDstAddrGet( )
ifDstAddrGet( ) - get the Internet address of a point-to-point peer
STATUS ifDstAddrGet ( char * interfaceName, /* name of interface, i.e. ei0 */ char * dstAddress /* buffer for destination address */ )
This routine gets the Internet address of a machine connected to the opposite end of a point-to-point network connection. The Internet address is copied to the buffer dstAddress.
OK or ERROR.
ifLib, ifDstAddrSet( ), ifAddrGet( )
ifMaskSet( ) - define a subnet for a network interface
STATUS ifMaskSet ( char * interfaceName, /* name of interface to set mask for, i.e. ei0 */ int netMask /* subnet mask (e.g. 0xff000000) */ )
This routine allocates additional bits to the network portion of an Internet address. The network portion is specified with a mask that must contain ones in all positions that are to be interpreted as the network portion. This includes all the bits that are normally interpreted as the network portion for the given class of address, plus the bits to be added. Note that all bits must be contiguous. The mask is specified in host byte order.
In order to correctly interpret the address, a subnet mask should be set for an interface prior to setting the Internet address of the interface with the routine ifAddrSet( ).
OK or ERROR.
ifMaskGet( ) - get the subnet mask for a network interface
STATUS ifMaskGet ( char * interfaceName, /* name of interface, i.e. ei0 */ int * netMask /* buffer for subnet mask */ )
This routine gets the subnet mask for a specified network interface. The subnet mask is copied to the buffer netMask. The subnet mask is returned in host byte order.
OK or ERROR.
ifLib, ifAddrGet( ), ifFlagGet( )
ifFlagChange( ) - change the network interface flags
STATUS ifFlagChange ( char * interfaceName, /* name of the network interface, i.e. ei0 */ int flags, /* the flag to be changed */ BOOL on /* TRUE=turn on, FALSE=turn off */ )
This routine changes the flags for the specified network interfaces. If the parameter on is TRUE, the specified flags are turned on; otherwise, they are turned off. The routines ifFlagGet( ) and ifFlagSet( ) are called to do the actual work.
OK or ERROR.
ifLib, ifAddrSet( ), ifMaskSet( ), ifFlagSet( ), ifFlagGet( )
ifFlagSet( ) - specify the flags for a network interface
STATUS ifFlagSet ( char * interfaceName, /* name of the network interface, i.e. ei0 */ int flags /* network flags */ )
This routine changes the flags for a specified network interface. Any combination of the following flags can be specified:
- IFF_UP (0x1)
- Brings the network up or down.
- IFF_DEBUG (0x4)
- Turns on debugging for the driver interface if supported.
- IFF_LOOPBACK (0x8)
- Set for a loopback network.
- IFF_NOTRAILERS (0x20)
- Always set (VxWorks does not use the trailer protocol).
- IFF_PROMISC (0x100)
- Tells the driver to accept all packets, not just broadcast packets and packets addressed to itself.
- IFF_ALLMULTI (0x200)
- Tells the driver to accept all multicast packets.
- IFF_NOARP (0x80)
- Disables ARP for the interface.
The following flags can only be set at interface initialization time. Specifying these flags does not change any settings in the interface data structure.
- IFF_POINTOPOINT (0x10)
- Identifies a point-to-point interface such as PPP or SLIP.
- IFF_RUNNING (0x40)
- Set when the device turns on.
- IFF_BROADCAST (0x2)
- Identifies a broadcast interface.
OK or ERROR.
ifLib, ifFlagChange( ), ifFlagGet( )
ifFlagGet( ) - get the network interface flags
STATUS ifFlagGet ( char * interfaceName, /* name of the network interface, i.e. ei0 */ int * flags /* network flags returned here */ )
This routine gets the flags for a specified network interface. The flags are copied to the buffer flags.
OK or ERROR.
ifMetricSet( ) - specify a network interface hop count
STATUS ifMetricSet ( char * interfaceName, /* name of the network interface, i.e. ei0 */ int metric /* metric for this interface */ )
This routine configures metric for a network interface from the host machine to the destination network. This information is used primarily by the IP routing algorithm to compute the relative distance for a collection of hosts connected to each interface. For example, a higher metric for SLIP interfaces can be specified to discourage routing a packet to slower serial line connections. Note that when metric is zero, the IP routing algorithm allows for the direct sending of a packet having an IP network address that is not necessarily the same as the local network address.
OK or ERROR.
ifLib, ifMetricGet( )
ifMetricGet( ) - get the metric for a network interface
STATUS ifMetricGet ( char * interfaceName, /* name of the network interface, i.e. ei0 */ int * pMetric /* returned interface's metric */ )
This routine retrieves the metric for a specified network interface. The metric is copied to the buffer pMetric.
OK or ERROR.
ifLib, ifMetricSet( )
ifRouteDelete( ) - delete routes associated with a network interface
int ifRouteDelete ( char * ifName, /* name of the interface */ int unit /* unit number for this interface */ )
This routine deletes all routes that have been associated with the specified interface. A route is associated with an interface if its destination equals to the assigned address, or network number. This routine does not remove routes to arbitrary destinations that through the given interface.
The number of routes deleted, or ERROR if an interface is not specified.
ifAllRoutesDelete( ) - delete all routes associated with a network interface
int ifAllRoutesDelete ( char * ifName, /* name of the interface */ int unit /* unit number for this interface */ )
This routine deletes all routes that have been associated with the specified interface. The routes deleted are:
Routes added by routing protocols are not deleted.
- the network route added when the interface address is initialized - the static routes added by the administrator - ARP routes passing through the interface
The number of routes deleted, or ERROR if an interface is not specified.
ifunit( ) - map an interface name to an interface structure pointer
struct ifnet *ifunit ( char * ifname /* name of the interface */ )
This routine returns a pointer to a network interface structure for name or NULL if no such interface exists. For example:
struct ifnet *pIf; ... pIf = ifunit ("ln0");pIf points to the data structure that describes the first network interface device if ln0 is mapped successfully.
A pointer to the interface structure, or NULL if an interface is not found.
ifNameToIfIndex( ) - returns the interface index given the interface name
unsigned short ifNameToIfIndex ( char * ifName /* a string describing the full interface */ /* name. e.g., "fei0" */ )
This routine returns the interface index for the interface named by the ifName parameter, which proviedes a string describing the full interface name. For example, "fei0".
The interface index, if the interface could be located, 0, otherwise. 0 is not a valid value for interface index.
ifIndexToIfName( ) - returns the interface name given the interface index
STATUS ifIndexToIfName ( unsigned short ifIndex, /* Interface index */ char * ifName /* Where the name is to be stored */ )
This routine returns the interface name for the interface referenced by the ifIndex parameter.
- ifIndex
- The index for the interface.
- ifName
- The location where the interface name is copied
OK on success, ERROR otherwise.