This manpage is an overview of the libpnet6 API. See
for an introduction to libpnet6 itself.
cc <c files> -o <executable> -lpnet6 -lpthread
Roughly speaking, libpnet6's API is divided into 4 sections.
This section documents a few data types used by the library, and discusses some issues and conventions regarding the functions in the API.
The sections on IP sockets and TCP/UDP ( pnet6-socket(3), pnet6-tcp(3) and pnet6-udp(3)) discuss most of the ``standard'' client server functionality offered by libpnet6, or indeed any self-respecting network library. Casual users should find this section more than sufficient for building robust network applications with great ease.
The remaining sections are addressed to the more experienced network programmers, who, although perfectly capable of implementing most of the functionality here themselves, are looking for a platform independent and intuitive way to deal with most of the advanced network stuff. These sections include interface access, pnet6-if(3) ; raw datagram manipulation, pnet6-ip(3) and pnet6-raw(3) ; and datalink packet access, pnet6-pkt(3).
For the sake of good programming practice, almost all data types used by libpnet6 are opaque, that is, there fields are hidden from the user of the API. This keeps the details about them hidden in the library, where they belong. Some people might not prefer that, but trust me, it keeps the end-user sane. Besides, it makes internal changes easy.
Functions and Return Values
Unless otherwise stated, each function that returns an integer, will return -1 on failure, and 0 on success. Functions that return pointers to structures will return NULL on failure, an a valid structure on success. libpnet6 functions do not return other types of values.
Whenever a function fails, libpnet6 sets an error code. This error code can later be obtained through pnetErrno(). A human-readable string explaining the error that belongs to the given error code can be obtained via a call to void pnetGetErrorString( int errno, char * buf, int buflen). The message is trunctated to fit into the given buffer if necessary.
At the heart of the libpnet6 API lies the PNETSOCK data type. This is an encapsulation of a socket. Like a regular socket, a PNETSOCK can be a connection based, stream-oriented socket, a connectionless datagram oriented socket, or it can be of the raw type, providing raw network protocol access. In addition, with each socket, an address family must be specified which specifies the protocol for communication (i.e. does this socket communicates through IP or IPv6?). How to create and use libpnet6 sockets is further discussed in pnet6-socket(3).
In addition to the PNETSOCK data type, there's also the PNETADDR data type. This is an encapsulation of an IP/IPv6/Unix socket address. It is mostly used internally, although occasionally, you might need to manipulate one: for example, you might want to resolve an address without actually using it in a socket call.
The next two data type, PNETIF and PNETIFADDR are used with network interfaces. Information about a network interface on the local machine, such as its name, index, netmask, and different types of addresses (hardware, IP, broadcast, etc...) is contained in the PNETIF data type. The interface's IP addresses are contained in a linked list of PNETIFADDR structures. These are not quite regular IP addresses, because they contain additional information, which is particular to the interface itself (i.e. its netmask, prefix, etc...). Interface access and interface addresses are further described in pnet6-if(3).
The next few data types are more advanced, and might be skipped in 95% of the cases where one is building a network application with pnet6.
The next data type is the PNETSOCK_AUXINFO: this only exists for a UDP or a RAW PNETSOCK, and is updated each time that socket receives data from the network. A PNETSOCK_AUXINFO contains additional information about the datagram which was just received: this differs for a UDP and a RAW socket. The exact details are described in pnet6-udp(3) and pnet6-raw(3).
If you need to acces packets at the datalink layer (see pnet6-pkt(3)), then the following data type might be of interest. All relevant details about a particular interface on which packets are being access are contained in the PNET_PKTACCESS data type. This includes details about the datalink frame header length, hardware addresses, payload type and the exact method used for reading and writing packets from and to the network.
libpnet6 is a fairly self-contained library. It has been designed like this in order to promote portability and minimize dependencies on third-party software that might not be available on systems where libpnet6 itself is supported. The only other library that applications that use libpnet6 need to link against besides the libpnet6 library is libpthread, if linking on UNIX systems that provide the POXIS threads API. On Windows platforms thread support is not linked in through a separate library. Systems that don't offer the pthreads API (I believe NetBSD 1.6 is one of them) can still use libpnet6, but cannot, obviously, make use of multithreading.
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