Content-type: text/html Manpage of LIBPNET6

LIBPNET6

Section: LIBPNET6 API Reference (3)
Updated: March 30, 2003
Index Return to Main Contents

 

NAME


 - libpnet6's functionality regarding auxiliary information for RAW and UDP sockets. See pnet6(3) for an introduction to libpnet6 itself.

This document describes the mechanims through which additional information pertaining to the last datagram received on a RAW or UDP socket can be obtained by an application using libpnet6. Auxiliary information is not maintained for TCP sockets.

 

OVERVIEW

You only need to include the <pnet6.h> generic header file to be able to use this functionality.

 

DESCRIPTION

In general, a lot more information is recorded by the kernel when a datagram is received than the information made immediately available to the application. Not all of the information is relevant to an application, but there are a few useful attributes that some applications need to know. These are among others, the interface on which the datagram arrived (provided the host machine has more than one interface); the actual destination address of the original datagram (this is not the same as the address of the interface on which the datagram arrived: a datagram might have been sent to a broadcast or a multicast address, or even to a different interface address); the hop-limit of the original datagram (useful for applications that rely on exact values for the hop-limit, such as IPv6 neighbor discovery); and the receive flags for the datagram: these include flags that indicate whether the datagram was a broadcast or multicast datagram, whether it was truncated upon reception (for instance due to limited buffer space on the receiving end), and/or whether the datagram contained out-of-band data. In addition, for RAW sockets, the full IPv4 or IPv6 header (depending on the address family of the socket) is recorder as well.

Auxiliary information is not stored automatically for each UDP socket by libpnet6 (it is for RAW sockets). Rather, a request to record auxiliary information is made on a per-socket basis during the creation of each particular socket. In order to create a socket for which auxiliary information is stored, you need to use pnetUDPSocketX(). NOTE: auxiliary information cannot be disabled for RAW sockets in the current version of libpnet6.

NOTE: auxiliary information is updated each time a new datagram arrives on a socket. This is therefore transient information. It is the responsibility of the programmer to take this into account.

 

API

Auxiliary information is represented by the opaque PNETSOCK_AUXINFO object in libpnet6.

PNETSOCK_AUXINFO pnetSockAuxInfo( PNETSOCK ps );

Returns a pointer to the auxiliary info buffer associated with this socket. If no auxiliary info exists for this socket, NULL is returned.

int pnetAuxType( PNETSOCK_AUXINFO paux );

Returns the type of the auxiliary info object. Legal types are PNET_IPv4, indicating that paux contains a valid IPv4 header, PNET_IPv6, indicating that paux contains a valid IPv6 header, and PNET_IPPROTO_UDP, indicating that the paux contains valid UDP auxiliary info. The first two types are only used by raw sockets, the last one is only used by UDP sockets (in the latter case, you don't really need to inspect the type to know it's UDP, since it's currently the only possibility anyway).

pnet_ip * pnetAuxIP( PNETSOCK_AUXINFO paux );

Return the IPv4 header stored with this paux object. The type of paux must be PNET_IPv4 or else the header will be corrupt.

pnet_ip6 * pnetAuxIP6( PNETSOCK_AUXINFO paux )

Return the IPv6 header stored with this paux object. The type of paux must be PNET_IPv6 or else the header will be corrupt.

int pnetAuxFlagOOB( PNETSOCK_AUXINFO paux );

Return true (i.e. a value other than 0) if the out-of-band flag is set for this paux object (i.e. the datagram contains out-of-band data).

int pnetAuxFlagBCST( PNETSOCK_AUXINFO paux );

Return true (i.e. a value other than 0) if the broadcast flag is set for this paux object (i.e. the datagram was a broadcast).

int pnetAuxFlagMCST( PNETSOCK_AUXINFO paux );

Return true (i.e. a value other than 0) if the multicast flag is set for this paux object (i.e. the datagram was a multicast).

int pnetAuxFlagTRUNC( PNETSOCK_AUXINFO paux );

Return true (i.e. a value other than 0) if the truncated flag is set for this paux object (i.e. the datagram was truncated on reception).

PNETADDR pnetAuxDstAddr( PNETSOCK_AUXINFO paux );

Returns the actual destination address of the datagram to which paux belongs.
  PNETIF pnetAuxRecvIf( PNETSOCK_AUXINFO paux );

Returns the interface on which the datagram to which paux belongs was received. See pnet6-if (3), on details about the PNETIF object.
  int pnetAuxHoplimit( PNETSOCK_AUXINFO paux );

Returns the hop limit of the datagram to which paux belongs. Returns -1 if the hop limit could not be obtained.

 

REMARKS

 

SEE ALSO

pnet6(3), pnet6-addr(3), pnet6-api(3), pnet6-aux(3), pnet6-if(3), pnet6-ip(3), pnet6-log(3), pnet6-pkt(3), pnet6-raw(3), pnet6-socket(3), pnet6-tcp(3), pnet6-threads(3), pnet6-udp(3).

 

VERSION

The current version of libpnet6 is highly experimental.

You can always get the most recent version from http://pnet6.sourceforge.net.

 

BUGS

??  

AUTHOR

Peter Bozarov. Send mail to kingofgib (at) users.sourceforge.net


 

Index

NAME
OVERVIEW
DESCRIPTION
API
REMARKS
SEE ALSO
VERSION
BUGS
AUTHOR

This document was created by man2html, using the manual pages.
Time: 06:22:19 GMT, May 26, 2003