pnet6-if: libpnet6's network interface access fuctionality
This document describes libpnet6's network interface access functions. See pnet6(3) for a general introduction to libpnet6 itself.
- Obtain miscellaneous network interface information.
Many network applications need to know something about the underlying network hardware (normally referred to as an interface). This includes things such as the interface's name, netmask, broadcast addresses; whether it's up, or is multicast capable. Fortunately, libpnet6 provides a clear set of functions to access all of this information.
In libpnet6, an interface is represented by the PNETIF datatype. Most interfaces have different addresses, for example an IPv6 and an IP address. Interface addresses are represented in libpnet6 as PNETIFADDR objects. For each interface, all of its addresses are stored as a linked list of PNETIFADDR objects.
To be able to use the following functions, you need to include the file pnet6.h.
This section explains the functions available for accessing information about a network interface. The following section talks in more detail about the addresses of a network interface.
PNETIF pnetGetIfInfo(int pfam);
Reads the system's network interfaces configuration and stores it in a linked list of PNETIF objects. The argument pfam can be either PNET_IPv4, PNET_IPv6, or PNET_UNSPEC, telling libpnet6 to fetch information regarding IPv4, IPv6, or all interfaces. Returns NULL on failure.
const char *pnetIfName(PNETIF pif);
Returns a null-terminated string containing the interface's name.
int pnetIfIndex(PNETIF pif);
Returns an integer containing the interface's current index.
const char * pnetIfTypeString(PNETIF pif);
Returns a null-terminated string containing a short description of the interface's type, e.g. ``Loopback''.
int pnetIfIsUp(PNETIF pif);
Returns true if interface is up.
int pnetIfIsRunning(PNETIF pif);
Returns true if interface is running.
int pnetIfIsBroadcast(PNETIF pif);
Returns true if interface is capable of receiving broadcast messages.
int pnetIfIsMulticast(PNETIF pif);
Returns true if interface is capable of receiving multicast messages.
int pnetIfIsLoopback(PNETIF pif);
Returns true if interface is a loopback interface.
int pnetIfIsPointopoint(PNETIF pif);
Returns true if interface is a point-to-point interface.
int pnetIfIsSimplex(PNETIF pif);
Returns true if interface is a simplex interface (that is, it cannot receive its own transmissions).
int pnetIfGetMTU(PNETIF pif);
Returns the Maximum Transfer Unit (in bytes) for this interface.
int pnetIfNameToIndex(const char * ifname);
Returns the interface index for the interface given by ifname.
const char * pnetIfIndexToName(int index);
Returns a null-terminated string representing the name of the interface that has the specified index, NULL if no such interface is found.
PNETIF pnetIfNext(PNETIF pif);
Returns the next interface in the linked list, NULL if there are no more interfaces left.
const pnet_byte * pnetIfGetLinkAddress(PNETIF pif, int * plen);
Returns a non-null terminated string containing the link layer (hardware) address of this interface. If plen is not NULL, the length of the string is returned in it. For example, for Ethernet, this length will be 6 since Ethernet addresses consist of six bytes.
PNETIFADDR pnetIfGetNextAddr( PNETIF pif, PNETIFADDR pia);
Returns the next address for this interface. Pass NULL as value for pia in order to get the first address available. If no (more) addresses are present for this interface, NULL is returned.
As already mentioned, most interfaces have more than one interface address. A network interface's address is represented in libpnet6 as a PNETIFADDR object. An interface's addresses are represented by a linked list of PNETIFADDR addresses.
PNETIFADDR pnetIfAddrGetNext( PNETIFADDR pia);
Returns the next address in the list, NULL if this is the last one.
int pnetIfAddrGetFamily( PNETIFADDR pia);
Returns the address family of this address object. The family is either PNET_IPv6 or PNET_IPv6.
const char * pnetIfAddrToString( PNETIFADDR pia, char * buf, int buflen );
Converts the given address to human-readable format and stores it in the provided buffer, which has a maximum length of len. A pointer to the same buffer is returned as well. If a conversion cannot be made, NULL is returned.
const pnet_byte * pnetIfAddrGetNetmask( PNETIFADDR pia);
Returns the netmask of this address, as a string of bytes. If the address has no netmask, NULL is returned.
const pnet_byte * pnetIfAddrGetBroadcast( PNETIFADDR pia);
Return the broadcast address of this address as a string of bytes. NULL is returned if the given address does not have a broadcast address.
int pnetIfAddrGetScopeId( PNETIFADDR pia);
For PNET_IPv6 addresses, returns the scope id. -1 is returned on error (mostly, when invoked on a non-IPv4 address).
int pnetIfAddrGetPrefixLength( PNETIFADDR pia);
For PNET_IPv6 addresses, returns the prefix length. -1 is returned on error (mostly, when invoked on a non-IPv4 address).
const pnet_byte* pnetIfAddrGetBinary( PNETIFADDR pia, int * len);
Returns a byte string containing the address in network format (non-readable string). If len is non-NULL, the length of the address is returned in it (normally, 4 for IPv4 address, and 16 for an IPv6 address).
The inteface information is contained in global, static variables. These are destroyed and recreated each time pnetGetIfInfo() is invoked. You will need to make own copies of any inteface variables if you need to keep them and are invoking pnetGetIfInfo() again.
As such, this particular interface API is not thread safe. However, interface configuration information is not likely to change a lot, and all of the functions only read the information. It is still left to the programmer to ensure proper protection of shared data in multithreaded applications.
The current version of libpnet6 is highly experimental.
You can always get the most recent version from http://pnet6.sourceforge.net.
??
Peter Bozarov. Send mail to kingofgib (at) users.sourceforge.net