A network packet. More...

Inheritance diagram for Packet:

Data
enum	{ default_headroom = 28 , min_buffer_length = 64 }

typedef void(*	buffer_destructor_type) (unsigned char buf, size_t sz, void argument)

static WritablePacket *	make (uint32_t headroom, const void *data, uint32_t length, uint32_t tailroom, bool clear=true)
	Create and return a new packet.

static WritablePacket *	make (const void *data, uint32_t length)
	Create and return a new packet.

static WritablePacket *	make (uint32_t length)
	Create and return a new packet.

static WritablePacket *	make_similar (Packet *original, uint32_t length)

static Packet *	make (struct sk_buff *skb)
	Change an sk_buff into a Packet (linuxmodule).

static void	empty_destructor (unsigned char , size_t, void )

static WritablePacket *	make (unsigned char data, uint32_t length, buffer_destructor_type buffer_destructor, void argument=(void *) 0, int headroom=0, int tailroom=0, bool clear=true)
	Create and return a new packet (userlevel).

static int	max_data_pool_size ()

static void	static_cleanup ()

void	kill ()
	Delete this packet.

void	kill_nonatomic ()
	Delete this packet in a thread-safe context.

bool	shared () const
	Test whether this packet's data is shared.

bool	shared_nonatomic () const
	Test whether this packet's data is shared.

Packet *	clone (bool fast=false)
	Create a clone of this packet.

WritablePacket *	duplicate (int32_t extra_headroom=0, int32_t extra_tailroom=0, const bool data_only=true)

WritablePacket *	uniqueify ()
	Return an unshared packet containing this packet's data.

void	get ()

const unsigned char *	data () const
	Return the packet's data pointer.

const unsigned char *	end_data () const
	Return the packet's end data pointer.

uint32_t	length () const
	Return the packet's length.

uint32_t	headroom () const
	Return the packet's headroom.

uint32_t	tailroom () const
	Return the packet's tailroom.

const unsigned char *	buffer () const
	Return a pointer to the packet's data buffer.

const unsigned char *	end_buffer () const
	Return the packet's end data buffer pointer.

uint32_t	buffer_length () const
	Return the packet's buffer length.

struct sk_buff *	skb ()

const struct sk_buff *	skb () const

WritablePacket *	push (uint32_t len)
	Add space for a header before the packet.

WritablePacket *	push_mac_header (uint32_t len)
	Add space for a MAC header before the packet.

Packet *	nonunique_push (uint32_t len)
	Add space for a header before the packet.

void	pull (uint32_t len)
	Remove a header from the front of the packet.

WritablePacket *	put (uint32_t len)
	Add space for data after the packet.

Packet *	nonunique_put (uint32_t len)
	Add space for data after the packet.

void	take (uint32_t len)
	Remove space from the end of the packet.

Packet *	shift_data (int offset, bool free_on_failure=true)
	Shift packet data within the data buffer.

void	shrink_data (const unsigned char *data, uint32_t length)
	Shrink the packet's data.

void	change_headroom_and_length (uint32_t headroom, uint32_t length)
	Shift the packet's data view to a different part of its buffer.

void	change_buffer_length (uint32_t length)

bool	copy (Packet *p, int headroom=0)
	Copy the content and annotations of another packet (userlevel) into this packet.

Annotations
never
enum	{ anno_size = 48 }

enum	PacketType { HOST = 0 , BROADCAST = 1 , MULTICAST = 2 , OTHERHOST = 3 , OUTGOING = 4 , LOOPBACK = 5 , FASTROUTE = 6 }
	Values for packet_type_anno(). Must agree with Linux's PACKET_ constants in <linux/if_packet.h>. More...

enum	{ dst_ip_anno_offset = 0 , dst_ip_anno_size = 4 , dst_ip6_anno_offset = 0 , dst_ip6_anno_size = 16 }

const Timestamp &	timestamp_anno () const
	Return the timestamp annotation.

Timestamp &	timestamp_anno ()

void	set_timestamp_anno (const Timestamp &t)
	Set the timestamp annotation.

net_device *	device_anno () const
	Return the device annotation.

void	set_device_anno (net_device *dev)
	Set the device annotation.

PacketType	packet_type_anno () const
	Return the packet type annotation.

void	set_packet_type_anno (PacketType t)
	Set the packet type annotation.

Packet *	next () const
	Return the next packet annotation.

Packet *&	next ()

void	set_next (Packet *p)
	Set the next packet annotation.

Packet *	prev () const
	Return the previous packet annotation.

Packet *&	prev ()

void	set_prev (Packet *p)
	Set the previous packet annotation.

Packet *	find_tail ()

unsigned int	find_count ()

IPAddress	dst_ip_anno () const
	Return the destination IPv4 address annotation.

void	set_dst_ip_anno (IPAddress addr)
	Set the destination IPv4 address annotation.

void *	anno ()
	Return a pointer to the annotation area.

const void *	anno () const

uint8_t *	anno_u8 ()
	Return a pointer to the annotation area as uint8_ts.

const uint8_t *	anno_u8 () const
	overload

uint32_t *	anno_u32 ()
	Return a pointer to the annotation area as uint32_ts.

const uint32_t *	anno_u32 () const
	overload

uint8_t	anno_u8 (int i) const
	Return annotation byte at offset i.

void	set_anno_u8 (int i, uint8_t x)
	Set annotation byte at offset i.

uint16_t	anno_u16 (int i) const
	Return 16-bit annotation at offset i.

void	set_anno_u16 (int i, uint16_t x)
	Set 16-bit annotation at offset i.

int16_t	anno_s16 (int i) const
	Return 16-bit annotation at offset i.

void	set_anno_s16 (int i, int16_t x)
	Set 16-bit annotation at offset i.

uint32_t	anno_u32 (int i) const
	Return 32-bit annotation at offset i.

void	set_anno_u32 (int i, uint32_t x)
	Set 32-bit annotation at offset i.

int32_t	anno_s32 (int i) const
	Return 32-bit annotation at offset i.

void	set_anno_s32 (int i, int32_t x)
	Set 32-bit annotation at offset i.

uint64_t	anno_u64 (int i) const
	Return 64-bit annotation at offset i.

void	set_anno_u64 (int i, uint64_t x)
	Set 64-bit annotation at offset i.

void *	anno_ptr (int i) const
	Return void * sized annotation at offset i.

void	set_anno_ptr (int i, const void *x)
	Set void * sized annotation at offset i.

Packet *	data_packet ()

void	clear_annotations (bool all=true)
	Clear all packet annotations.

void	copy_annotations (const Packet *, bool all=true)
	Copy most packet annotations from p.

void	copy_headers (const Packet *)

Header Pointers
bool	has_mac_header () const
	Return true iff the packet's MAC header pointer is set.

const unsigned char *	mac_header () const
	Return the packet's MAC header pointer.

int	mac_header_offset () const
	Return the offset from the packet data to the MAC header.

uint32_t	mac_header_length () const
	Return the MAC header length.

int	mac_length () const
	Return the packet's length starting from its MAC header pointer.

void	set_mac_header (const unsigned char *p)
	Set the MAC header pointer.

void	set_mac_header (const unsigned char *p, uint32_t len)
	Set the MAC and network header pointers.

void	clear_mac_header ()
	Unset the MAC header pointer.

bool	has_network_header () const
	Return true iff the packet's network header pointer is set.

const unsigned char *	network_header () const
	Return the packet's network header pointer.

int	network_header_offset () const
	Return the offset from the packet data to the network header.

uint32_t	network_header_length () const
	Return the network header length.

int	network_length () const
	Return the packet's length starting from its network header pointer.

void	set_network_header (const unsigned char *p)
	Set the network header.

void	set_network_header (const unsigned char *p, uint32_t len)
	Set the network and transport header pointers.

void	set_network_header_length (uint32_t len)
	Set the network header length.

void	clear_network_header ()
	Unset the network header pointer.

void	set_transport_header (const unsigned char *p)
	Set the transport header.

bool	has_transport_header () const
	Return true iff the packet's transport header pointer is set.

const unsigned char *	transport_header () const
	Return the packet's transport header pointer.

int	transport_header_offset () const
	Return the offset from the packet data to the transport header.

int	transport_length () const
	Return the packet's length starting from its transport header pointer.

void	clear_transport_header ()
	Unset the transport header pointer.

const click_ether *	ether_header () const
	Return the packet's MAC header pointer as Ethernet.

void	set_ether_header (const click_ether *ethh)
	Set the MAC header pointer to an Ethernet header.

const click_ip *	ip_header () const
	Return the packet's network header pointer as IPv4.

int	ip_header_offset () const
	Return the offset from the packet data to the IP header.

uint32_t	ip_header_length () const
	Return the IP header length.

void	set_ip_header (const click_ip *iph, uint32_t len)
	Set the network header pointer to an IPv4 header.

const click_ip6 *	ip6_header () const
	Return the packet's network header pointer as IPv6.

int	ip6_header_offset () const
	Return the offset from the packet data to the IPv6 header.

uint32_t	ip6_header_length () const
	Return the IPv6 header length.

void	set_ip6_header (const click_ip6 *ip6h)
	Set the network header pointer to an IPv6 header.

void	set_ip6_header (const click_ip6 *ip6h, uint32_t len)
	Set the network header pointer to an IPv6 header.

const click_icmp *	icmp_header () const
	Return the packet's transport header pointer as ICMP.

const click_tcp *	tcp_header () const
	Return the packet's transport header pointer as TCP.

const click_udp *	udp_header () const
	Return the packet's transport header pointer as UDP.

uint16_t	getContentOffset () const

void	setContentOffset (uint16_t offset)

const unsigned char *	getPacketContent ()

bool	isPacketContentEmpty () const

uint16_t	getPacketContentSize () const

typedef	typeof (((struct sk_buff *) 0) ->mac_header) mac_header_type

typedef	typeof (((struct sk_buff *) 0) ->network_header) network_header_type

typedef	typeof (((struct sk_buff *) 0) ->transport_header) transport_header_type

Detailed Description

A network packet.

Click's Packet class represents network packets within a router. Packet objects are passed from Element to Element via the Element::push() and Element::pull() functions. The vast majority of elements handle packets.

A packet consists of a data buffer, which stores the actual packet wire data, and a set of annotations, which store extra information calculated about the packet, such as the destination address to be used for routing. Every Packet object has different annotations, but a data buffer may be shared among multiple Packet objects, saving memory and speeding up packet copies. (See Packet::clone.) As a result a Packet's data buffer is not writable. To write into a packet, turn it into a nonshared WritablePacket first, using uniqueify(), push(), or put().

Data Buffer

A packet's data buffer is a single flat array of bytes. The buffer may be larger than the actual packet data, leaving unused spaces called headroom and tailroom before and after the data proper. Prepending headers or appending data to a packet can be quite efficient if there is enough headroom or tailroom.

The relationships among a Packet object's data buffer variables is shown here:

                    data()               end_data()
                       |                      |
      |<- headroom() ->|<----- length() ----->|<- tailroom() ->|
      |                v                      v                |
      +================+======================+================+
      |XXXXXXXXXXXXXXXX|   PACKET CONTENTS    |XXXXXXXXXXXXXXXX|
      +================+======================+================+
      ^                                                        ^
      |<------------------ buffer_length() ------------------->|
      |                                                        |
   buffer()                                               end_buffer()

Most code that manipulates packets is interested only in data() and length().

To create a Packet, call one of the make() functions. To destroy a Packet, call kill(). To clone a Packet, which creates a new Packet object that shares this packet's data, call clone(). To uniqueify a Packet, which unshares the packet data if necessary, call uniqueify(). To allocate extra space for headers or trailers, call push() and put(). To remove headers or trailers, call pull() and take().

               data()                          end_data()
                  |                                |
          push()  |  pull()                take()  |  put()
         <======= | =======>              <======= | =======>
                  v                                v
      +===========+================================+===========+
      |XXXXXXXXXXX|        PACKET CONTENTS         |XXXXXXXXXXX|
      +===========+================================+===========+

Packet objects are implemented in different ways in different drivers. The userlevel driver has its own C++ implementation. In the linuxmodule driver, however, Packet is an overlay on Linux's native sk_buff object: the Packet methods access underlying sk_buff data directly, with no overhead. (For example, Packet::data() returns the sk_buff's data field.)

Annotations

Annotations are extra information about a packet above and beyond the packet data. Packet supports several specific annotations, plus a user annotation area available for arbitrary use by elements.

Header pointers: Each packet has three header pointers, designed to point to the packet's MAC header, network header, and transport header, respectively. Convenience functions like ip_header() access these pointers cast to common header types. The header pointers are kept up to date when operations like push() or uniqueify() change the packet's data buffer. Header pointers can be null, and they can even point to memory outside the current packet data bounds. For example, a MAC header pointer will remain set even after pull() is used to shift the packet data past the MAC header. As a result, functions like mac_header_offset() can return negative numbers.
Timestamp: A timestamp associated with the packet. Most packet sources timestamp packets when they enter the router; other elements examine or modify the timestamp.
Device: A pointer to the device on which the packet arrived. Only meaningful in the linuxmodule driver, but provided in every driver.
Packet type: A small integer indicating whether the packet is meant for this host, broadcast, multicast, or some other purpose. Several elements manipulate this annotation; in linuxmodule, setting the annotation is required for the host network stack to process incoming packets correctly.
Performance counter (linuxmodule only): A 64-bit integer intended to hold a performance counter value. Used by SetCycleCount and others.
Next and previous packet: Pointers provided to allow elements to chain packets into a doubly linked list.
Annotations: Each packet has anno_size bytes available for annotations. Elements agree to use portions of the annotation area to communicate per-packet information. Macros in the <click/packet_anno.hh> header file define the annotations used by Click's current elements. One common annotation is the network address annotation – see Packet::dst_ip_anno(). Routing elements, such as RadixIPLookup, set the address annotation to indicate the desired next hop; ARPQuerier uses this annotation to query the next hop's MAC.

New packets start wth all annotations set to zero or null. Cloning a packet copies its annotations.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
default_headroom	Default packet headroom() for Packet::make(). 4-byte aligned.
min_buffer_length	Minimum buffer_length() for Packet::make()

◆ anonymous enum

anonymous enum

Enumerator
anno_size	Size of annotation area.

◆ PacketType

enum Packet::PacketType

Values for packet_type_anno(). Must agree with Linux's PACKET_ constants in <linux/if_packet.h>.

Enumerator
HOST	Packet was sent to this host.
BROADCAST	Packet was sent to a link-level multicast address.
MULTICAST	Packet was sent to a link-level multicast address.
OTHERHOST	Packet was sent to a different host, but received anyway. The receiving device is probably in promiscuous mode.
OUTGOING	Packet was generated by this host and is being sent elsewhere.

Member Function Documentation

◆ make() [1/5]

WritablePacket * Packet::make	(	uint32_t	headroom,
		const void *	data,
		uint32_t	length,
		uint32_t	tailroom,
		bool	clear = `true`
	)

static

Create and return a new packet.

Parameters

headroom	headroom in new packet
data	data to be copied into the new packet
length	length of packet
tailroom	tailroom in new packet (ignored when DPDK is used)

Returns: new packet, or null if no packet could be created

The data is copied into the new packet. If data is null, the packet's data is left uninitialized. The resulting packet's buffer_length() will be at least min_buffer_length ; if headroom + length + tailroom would be less, then tailroom is increased to make the total min_buffer_length .

The new packet's annotations are cleared and its header pointers are null.

◆ make() [2/5]

WritablePacket * Packet::make	(	const void *	data,
		uint32_t	length
	)

inlinestatic

Create and return a new packet.

Parameters

data	data to be copied into the new packet
length	length of packet

Returns: new packet, or null if no packet could be created

The data is copied into the new packet. If data is null, the packet's data is left uninitialized. The new packet's headroom equals default_headroom , its tailroom is 0.

The returned packet's annotations are cleared and its header pointers are null.

◆ make() [3/5]

WritablePacket * Packet::make ( uint32_t length )

inlinestatic

Create and return a new packet.

Parameters

length length of packet

Returns: new packet, or null if no packet could be created

The packet's data is left uninitialized. The new packet's headroom equals default_headroom , its tailroom is 0.

The returned packet's annotations are cleared and its header pointers are null.

◆ make() [4/5]

Packet * Packet::make ( struct sk_buff * skb )

inlinestatic

Change an sk_buff into a Packet (linuxmodule).

Parameters

skb	input sk_buff

Returns: the packet

In the Linux kernel module, Packet objects are sk_buff objects. This function simply changes an sk_buff into a Packet by claiming its skb argument. If skb->users is 1, then skb is orphaned by skb_orphan(skb) and returned. If it is larger than 1, then skb is cloned and the clone is returned. (sk_buffs used for Click Packet objects must have skb->users == 1.) Null might be returned if there's no memory for the clone.

The returned packet's annotations and header pointers are not cleared: they have the same values they did in the sk_buff. If the packet came from Linux, then the header pointers and shared annotations (timestamp, packet type, next/prev packet) might have valid values, but the Click annotations (address, user) likely do not. Use clear_annotations() to clear them.

◆ empty_destructor()

void Packet::empty_destructor	(	unsigned char *	,
		size_t	,
		void *
	)

static

Empty destructor which does nothing. Use this whenever possible instead of your own empty destructor as this special case will be detected and it won't be called.

◆ make() [5/5]

WritablePacket * Packet::make	(	unsigned char *	data,
		uint32_t	length,
		buffer_destructor_type	destructor,
		void *	argument = `(void*) 0`,
		int	headroom = `0`,
		int	tailroom = `0`,
		bool	clear = `true`
	)

static

Create and return a new packet (userlevel).

Parameters

data	data used in the new packet
length	length of packet
destructor	destructor function
argument	argument to destructor function
headroom	headroom available before the data pointer
tailroom	tailroom available after data + length

Returns: new packet, or null if no packet could be created

The packet's data pointer becomes the data: the data is not copied into the new packet, rather the packet owns the data pointer. When the packet's data is eventually destroyed, either because the packet is deleted or because of something like a push() or full(), the destructor will be called as destructor(data, length, argument). (If destructor is null, the packet data will be freed by delete[] data.) The packet has zero headroom and tailroom.

The returned packet's annotations are cleared and its header pointers are null.

◆ kill()

void Packet::kill ( )

inline

Delete this packet.

The packet header (including annotations) is destroyed and its memory returned to the system. The packet's data is also freed if this is the last clone.

◆ kill_nonatomic()

void Packet::kill_nonatomic ( )

inline

Delete this packet in a thread-safe context.

The packet header (including annotations) is destroyed and its memory returned to the system. The packet's data is also freed if this is the last clone.

@precond Packet are only handled by this thread

◆ shared()

bool Packet::shared ( ) const

inline

Test whether this packet's data is shared.

Returns true iff the packet's data is shared. If shared() is false, then the result of uniqueify() will equal this.

◆ shared_nonatomic()

bool Packet::shared_nonatomic ( ) const

inline

Test whether this packet's data is shared.

Returns true iff the packet's data is shared. If shared() is false, then the result of uniqueify() will equal this.

◆ clone()

Packet * Packet::clone ( bool fast = false )

Create a clone of this packet.

fast The new clone won't be a shared packet and we won't update the reference count of this packet. The buffer won't be freed in any way and an empty destructor will be set. It is usefull if you won't release this packet before you're sure that the clone will be killed and plan on managing the buffer yourself. This is usefull for pktgen applications where it would be hard to achieve good performances with (useless) reference counting. If the packet is a DPDK packet, it will be referenced as a DPDK packet and the DPDK buffer counter will be updated.

Returns: the cloned packet

The returned clone has independent annotations, initially copied from this packet, but shares this packet's data. shared() returns true for both the packet and its clone. Returns null if there's no memory for the clone.

◆ uniqueify()

WritablePacket * Packet::uniqueify ( )

inline

Return an unshared packet containing this packet's data.

Returns: the unshared packet, which is writable

The returned packet's data is unshared with any other packet, so it's safe to write the data. If shared() is false, this operation simply returns the input packet. If shared() is true, uniqueify() makes a copy of the data. The input packet is freed if the copy fails.

The returned WritablePacket pointer may not equal the input Packet pointer, so do not use the input pointer after the uniqueify() call.

The input packet's headroom and tailroom areas are copied in addition to its true contents. The header annotations are shifted to point into the new packet data if necessary.

uniqueify() is usually used like this:

WritablePacket *q = p->uniqueify();
if (!q)
    return 0;
// p must not be used here.

◆ data()

const unsigned char * Packet::data ( ) const

inline

Return the packet's data pointer.

This is the pointer to the first byte of packet data.

◆ end_data()

const unsigned char * Packet::end_data ( ) const

inline

Return the packet's end data pointer.

The result points at the byte following the packet data.

Invariant: end_data() == data() + length()

◆ length()

uint32_t Packet::length ( ) const

inline

Return the packet's length.

◆ headroom()

uint32_t Packet::headroom ( ) const

inline

Return the packet's headroom.

The headroom is the amount of space available in the current packet buffer before data(). A push() operation is cheap if the packet's unshared and the length pushed is less than headroom().

◆ tailroom()

uint32_t Packet::tailroom ( ) const

inline

Return the packet's tailroom.

The tailroom is the amount of space available in the current packet buffer following end_data(). A put() operation is cheap if the packet's unshared and the length put is less than tailroom().

◆ buffer()

const unsigned char * Packet::buffer ( ) const

inline

Return a pointer to the packet's data buffer.

The result points at the packet's headroom, not its data.

Invariant: buffer() == data() - headroom()

◆ end_buffer()

const unsigned char * Packet::end_buffer ( ) const

inline

Return the packet's end data buffer pointer.

The result points past the packet's tailroom.

Invariant: end_buffer() == end_data() + tailroom()

◆ buffer_length()

uint32_t Packet::buffer_length ( ) const

inline

Return the packet's buffer length.

Invariant: buffer_length() == headroom() + length() + tailroom(); buffer() + buffer_length() == end_buffer()

◆ push()

WritablePacket * Packet::push ( uint32_t len )

inline

Add space for a header before the packet.

Parameters

len	amount of space to add

Returns: packet with added header space, or null on failure

Returns a packet with an additional len bytes of uninitialized space before the current packet's data(). A copy of the packet data is made if there isn't enough headroom() in the current packet, or if the current packet is shared(). If no copy is made, this operation is quite efficient.

If a data copy would be required, but the copy fails because of lack of memory, then the current packet is freed.

push() is usually used like this:

WritablePacket *q = p->push(14);
if (!q)
    return 0;
// p must not be used here.

Postcondition: new length() == old length() + len (if no failure)

See also: nonunique_push, push_mac_header, pull

◆ push_mac_header()

WritablePacket * Packet::push_mac_header ( uint32_t len )

inline

Add space for a MAC header before the packet.

Parameters

len	amount of space to add and length of MAC header

Returns: packet with added header space, or null on failure

Combines the action of push() and set_mac_header(). len bytes are pushed for a MAC header, and on success, the packet's returned MAC and network header pointers are set as by set_mac_header(data(), len).

See also: push

◆ nonunique_push()

Packet * Packet::nonunique_push ( uint32_t len )

inline

Add space for a header before the packet.

Parameters

len	amount of space to add

Returns: packet with added header space, or null on failure

This is a variant of push(). Returns a packet with an additional len bytes of uninitialized space before the current packet's data(). A copy of the packet data is made if there isn't enough headroom() in the current packet. However, no copy is made if the current packet is shared; and if no copy is made, this operation is quite efficient.

If a data copy would be required, but the copy fails because of lack of memory, then the current packet is freed.

Note: Unlike push(), nonunique_push() returns a Packet object, which has non-writable data.

See also: push

◆ pull()

void Packet::pull ( uint32_t len )

inline

Remove a header from the front of the packet.

Parameters

len	amount of space to remove

Removes len bytes from the initial part of the packet, usually corresponding to some network header (for example, pull(14) removes an Ethernet header). This operation is efficient: it just bumps a pointer.

It is an error to attempt to pull more than length() bytes.

Postcondition: new data() == old data() + len; new length() == old length() - len

See also: push

◆ put()

WritablePacket * Packet::put ( uint32_t len )

inline

Add space for data after the packet.

Parameters

len	amount of space to add

Returns: packet with added trailer space, or null on failure

Returns a packet with an additional len bytes of uninitialized space after the current packet's data (starting at end_data()). A copy of the packet data is made if there isn't enough tailroom() in the current packet, or if the current packet is shared(). If no copy is made, this operation is quite efficient.

If a data copy would be required, but the copy fails because of lack of memory, then the current packet is freed.

put() is usually used like this:

WritablePacket *q = p->put(100);
if (!q)
    return 0;
// p must not be used here.

Postcondition: new length() == old length() + len (if no failure)

See also: nonunique_put, take

◆ nonunique_put()

Packet * Packet::nonunique_put ( uint32_t len )

inline

Add space for data after the packet.

Parameters

len	amount of space to add

Returns: packet with added trailer space, or null on failure

This is a variant of put(). Returns a packet with an additional len bytes of uninitialized space after the current packet's data (starting at end_data()). A copy of the packet data is made if there isn't enough tailroom() in the current packet. However, no copy is made if the current packet is shared; and if no copy is made, this operation is quite efficient.

If a data copy would be required, but the copy fails because of lack of memory, then the current packet is freed.

See also: put

◆ take()

void Packet::take ( uint32_t len )

inline

Remove space from the end of the packet.

Parameters

len	amount of space to remove

Removes len bytes from the end of the packet. This operation is efficient: it just bumps a pointer.

It is an error to attempt to pull more than length() bytes.

Postcondition: new data() == old data(); new end_data() == old end_data() - len; new length() == old length() - len

See also: push

◆ shift_data()

Packet * Packet::shift_data	(	int	offset,
		bool	free_on_failure = `true`
	)

Shift packet data within the data buffer.

Parameters

offset	amount to shift packet data
free_on_failure	if true, then delete the input packet on failure

Returns: a packet with shifted data, or null on failure

Useful to align packet data. For example, if the packet's embedded IP header is located at pointer value 0x8CCA03, then shift_data(1) or shift_data(-3) will both align the header on a 4-byte boundary.

Due to the alignement, the data may be shifted by an error of 4 bytes. Eg calling shift(-5) might shift only for -3.

If the packet is shared() or there isn't enough headroom or tailroom for the operation, the packet is passed to uniqueify() first. This can fail if there isn't enough memory. If it fails, shift_data returns null, and if free_on_failure is true (the default), the input packet is freed.

The packet's mac_header, network_header, and transport_header areas are preserved, even if they lie within the headroom. Any headroom outside these regions may be overwritten, as may any tailroom.

Postcondition: new data() == old data() + offset (if no copy is made); new buffer() == old buffer() (if no copy is made)

◆ shrink_data()

void Packet::shrink_data	(	const unsigned char *	data,
		uint32_t	length
	)

inline

Shrink the packet's data.

Parameters

data	new data pointer
length	new length

Warning: This function is useful only in special contexts.

Note: Only available at user level

User-level programs that read packet logs commonly read a large chunk of data (32 kB or more) into a base Packet object. The log reader then works over the data buffer and, for each packet contained therein, outputs a clone that shares memory with the base packet. This is space- and time-efficient, but the generated packets have gigantic headroom and tailroom. Uniqueifying a generated packet will wastefully copy this headroom and tailroom as well. The shrink_data function addresses this problem.

shrink_data() removes all of a packet's headroom and tailroom. The resulting packet has data() equal to data, length() equal to length, and headroom() and tailroom() equal to zero.

Precondition: The packet must be a clone() of another existing packet.; data >= data(), data <= end_data(), data + length >= data(), and data + length <= end_data()

See also: change_headroom_and_length

◆ change_headroom_and_length()

void Packet::change_headroom_and_length	(	uint32_t	headroom,
		uint32_t	length
	)

inline

Shift the packet's data view to a different part of its buffer.

Parameters

headroom	new headroom
length	new length

Warning: This function is useful only in special contexts.

Note: Only available at user level

Shifts the packet's data() pointer to a different part of the packet's data buffer. The buffer pointer itself is not changed, and the packet's contents are not affected (except by the new view).

Precondition: headroom + length <= buffer_length()

Postcondition: new buffer() == old buffer(); new end_buffer() == old end_buffer(); new headroom() == headroom; new length() == length

See also: shrink_data

◆ copy()

bool Packet::copy	(	Packet *	p,
		int	headroom = `0`
	)

Copy the content and annotations of another packet (userlevel) into this packet.

Parameters

source	packet
headroom	for the new packet

Returns: True of the copy was successfull

◆ has_mac_header()

bool Packet::has_mac_header ( ) const

inline

Return true iff the packet's MAC header pointer is set.

See also: set_mac_header, clear_mac_header

◆ mac_header()

const unsigned char * Packet::mac_header ( ) const

inline

Return the packet's MAC header pointer.

Warning: Not useful if !has_mac_header().

See also: ether_header, set_mac_header, clear_mac_header, mac_header_length, mac_length

◆ mac_header_offset()

int Packet::mac_header_offset ( ) const

inline

Return the offset from the packet data to the MAC header.

Returns: mac_header() - data()

Warning: Not useful if !has_mac_header().

◆ mac_header_length()

uint32_t Packet::mac_header_length ( ) const

inline

Return the MAC header length.

Returns: network_header() - mac_header()

This equals the offset from the MAC header pointer to the network header pointer.

Warning: Not useful if !has_mac_header() or !has_network_header().

◆ mac_length()

int Packet::mac_length ( ) const

inline

Return the packet's length starting from its MAC header pointer.

Invariant: mac_length() == end_data() - mac_header()

Warning: Not useful if !has_mac_header().

◆ set_mac_header() [1/2]

void Packet::set_mac_header ( const unsigned char * p )

inline

Set the MAC header pointer.

Parameters

p	new header pointer

◆ set_mac_header() [2/2]

void Packet::set_mac_header	(	const unsigned char *	p,
		uint32_t	len
	)

inline

Set the MAC and network header pointers.

Parameters

p	new MAC header pointer
len	new MAC header length

Postcondition: mac_header() == p and network_header() == p + len

◆ clear_mac_header()

void Packet::clear_mac_header ( )

inline

Unset the MAC header pointer.

Postcondition: has_mac_header() == false Does not affect the network or transport header pointers.

◆ has_network_header()

bool Packet::has_network_header ( ) const

inline

Return true iff the packet's network header pointer is set.

See also: set_network_header, clear_network_header

◆ network_header()

const unsigned char * Packet::network_header ( ) const

inline

Return the packet's network header pointer.

Warning: Not useful if !has_network_header().

See also: ip_header, ip6_header, set_network_header, clear_network_header, network_header_length, network_length

◆ network_header_offset()

int Packet::network_header_offset ( ) const

inline

Return the offset from the packet data to the network header.

Returns: network_header() - data()

Warning: Not useful if !has_network_header().

◆ network_header_length()

uint32_t Packet::network_header_length ( ) const

inline

Return the network header length.

Returns: transport_header() - network_header()

This equals the offset from the network header pointer to the transport header pointer.

Warning: Not useful if !has_network_header() or !has_transport_header().

◆ network_length()

int Packet::network_length ( ) const

inline

Return the packet's length starting from its network header pointer.

Invariant: network_length() == end_data() - network_header()

Warning: Not useful if !has_network_header().

◆ set_network_header() [1/2]

void Packet::set_network_header ( const unsigned char * p )

inline

Set the network header.

Parameters

p	new network header pointer

◆ set_network_header() [2/2]

void Packet::set_network_header	(	const unsigned char *	p,
		uint32_t	len
	)

inline

Set the network and transport header pointers.

Parameters

p	new network header pointer
len	new network header length

Postcondition: network_header() == p and transport_header() == p + len

◆ set_network_header_length()

void Packet::set_network_header_length ( uint32_t len )

inline

Set the network header length.

Parameters

len	new network header length

Setting the network header length really just sets the transport header pointer.

Postcondition: transport_header() == network_header() + len

◆ clear_network_header()

void Packet::clear_network_header ( )

inline

Unset the network header pointer.

Postcondition: has_network_header() == false Does not affect the MAC or transport header pointers.

◆ set_transport_header()

void Packet::set_transport_header ( const unsigned char * p )

inline

Set the transport header.

Parameters

p	new transport header pointer

◆ has_transport_header()

bool Packet::has_transport_header ( ) const

inline

Return true iff the packet's transport header pointer is set.

See also: set_network_header, clear_transport_header

◆ transport_header()

const unsigned char * Packet::transport_header ( ) const

inline

Return the packet's transport header pointer.

Warning: Not useful if !has_transport_header().

See also: tcp_header, udp_header, icmp_header, set_transport_header, clear_transport_header, transport_length

◆ transport_header_offset()

int Packet::transport_header_offset ( ) const

inline

Return the offset from the packet data to the transport header.

Returns: transport_header() - data()

Warning: Not useful if !has_transport_header().

◆ transport_length()

int Packet::transport_length ( ) const

inline

Return the packet's length starting from its transport header pointer.

Invariant: transport_length() == end_data() - transport_header()

Warning: Not useful if !has_transport_header().

◆ clear_transport_header()

void Packet::clear_transport_header ( )

inline

Unset the transport header pointer.

Postcondition: has_transport_header() == false Does not affect the MAC or network header pointers.

◆ ether_header()

const click_ether * Packet::ether_header ( ) const

inline

Return the packet's MAC header pointer as Ethernet.

Invariant: (void *) ether_header() == (void *) mac_header()

Warning: Not useful if !has_mac_header().

See also: mac_header

◆ set_ether_header()

void Packet::set_ether_header ( const click_ether * ethh )

inline

Set the MAC header pointer to an Ethernet header.

Parameters

ethh	new Ethernet header pointer

Postcondition: (void *) mac_header() == (void *) ethh; mac_header_length() == 14; (void *) network_header() == (void *) (ethh + 1)

◆ ip_header()

const click_ip * Packet::ip_header ( ) const

inline

Return the packet's network header pointer as IPv4.

Invariant: (void *) ip_header() == (void *) network_header()

Warning: Not useful if !has_network_header().

See also: network_header

◆ ip_header_offset()

int Packet::ip_header_offset ( ) const

inline

Return the offset from the packet data to the IP header.

Returns: network_header() - mac_header()

Warning: Not useful if !has_network_header().

See also: network_header_offset

◆ ip_header_length()

uint32_t Packet::ip_header_length ( ) const

inline

Return the IP header length.

Returns: transport_header() - network_header()

This equals the offset from the network header pointer to the transport header pointer.

Warning: Not useful if !has_network_header() or !has_transport_header().

See also: network_header_length

◆ set_ip_header()

void Packet::set_ip_header	(	const click_ip *	iph,
		uint32_t	len
	)

inline

Set the network header pointer to an IPv4 header.

Parameters

iph	new IP header pointer
len	new IP header length in bytes

Postcondition: (char *) network_header() == (char *) iph; network_header_length() == len; (char *) transport_header() == (char *) iph + len

◆ ip6_header()

const click_ip6 * Packet::ip6_header ( ) const

inline

Return the packet's network header pointer as IPv6.

Invariant: (void *) ip6_header() == (void *) network_header()

Warning: Not useful if !has_network_header().

See also: network_header

◆ ip6_header_offset()

int Packet::ip6_header_offset ( ) const

inline

Return the offset from the packet data to the IPv6 header.

Returns: network_header() - data()

Warning: Not useful if !has_network_header().

See also: network_header_offset

◆ ip6_header_length()

uint32_t Packet::ip6_header_length ( ) const

inline

Return the IPv6 header length.

Returns: transport_header() - network_header()

This equals the offset from the network header pointer to the transport header pointer.

Warning: Not useful if !has_network_header() or !has_transport_header().

See also: network_header_length

◆ set_ip6_header() [1/2]

void Packet::set_ip6_header ( const click_ip6 * ip6h )

inline

Set the network header pointer to an IPv6 header.

Parameters

ip6h	new IP header pointer

Postcondition: (char *) network_header() == (char *) ip6h; network_header_length() == 40; (char *) transport_header() == (char *) (ip6h + 1)

◆ set_ip6_header() [2/2]

void Packet::set_ip6_header	(	const click_ip6 *	ip6h,
		uint32_t	len
	)

inline

Set the network header pointer to an IPv6 header.

Parameters

ip6h	new IP header pointer
len	new IP header length in bytes

Postcondition: (char *) network_header() == (char *) ip6h; network_header_length() == len; (char *) transport_header() == (char *) ip6h + len

◆ icmp_header()

const click_icmp * Packet::icmp_header ( ) const

inline

Return the packet's transport header pointer as ICMP.

Invariant: (void *) icmp_header() == (void *) transport_header()

Warning: Not useful if !has_transport_header().

See also: transport_header

◆ tcp_header()

const click_tcp * Packet::tcp_header ( ) const

inline

Return the packet's transport header pointer as TCP.

Invariant: (void *) tcp_header() == (void *) transport_header()

Warning: Not useful if !has_transport_header().

See also: transport_header

◆ udp_header()

const click_udp * Packet::udp_header ( ) const

inline

Return the packet's transport header pointer as UDP.

Invariant: (void *) udp_header() == (void *) transport_header()

Warning: Not useful if !has_transport_header().

See also: transport_header

◆ timestamp_anno() [1/2]

const Timestamp & Packet::timestamp_anno ( ) const

inline

Return the timestamp annotation.

◆ timestamp_anno() [2/2]

Timestamp & Packet::timestamp_anno ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ set_timestamp_anno()

void Packet::set_timestamp_anno ( const Timestamp & t )

inline

Set the timestamp annotation.

Parameters

t	new timestamp

◆ device_anno()

net_device * Packet::device_anno ( ) const

inline

Return the device annotation.

◆ set_device_anno()

void Packet::set_device_anno ( net_device * dev )

inline

Set the device annotation.

◆ packet_type_anno()

Packet::PacketType Packet::packet_type_anno ( ) const

inline

Return the packet type annotation.

◆ set_packet_type_anno()

void Packet::set_packet_type_anno ( PacketType t )

inline

Set the packet type annotation.

◆ next() [1/2]

Packet * Packet::next ( ) const

inline

Return the next packet annotation.

◆ next() [2/2]

Packet *& Packet::next ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ set_next()

void Packet::set_next ( Packet * p )

inline

Set the next packet annotation.

◆ prev() [1/2]

Packet * Packet::prev ( ) const

inline

Return the previous packet annotation.

◆ prev() [2/2]

Packet *& Packet::prev ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ set_prev()

void Packet::set_prev ( Packet * p )

inline

Set the previous packet annotation.

◆ dst_ip_anno()

IPAddress Packet::dst_ip_anno ( ) const

inline

Return the destination IPv4 address annotation.

The value is taken from the address annotation area.

◆ set_dst_ip_anno()

void Packet::set_dst_ip_anno ( IPAddress addr )

inline

Set the destination IPv4 address annotation.

The value is stored in the address annotation area.

◆ anno() [1/2]

void * Packet::anno ( )

inline

Return a pointer to the annotation area.

The area is anno_size bytes long.

◆ anno() [2/2]

const void * Packet::anno ( ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ anno_u8() [1/3]

uint8_t * Packet::anno_u8 ( )

inline

Return a pointer to the annotation area as uint8_ts.

◆ anno_u8() [2/3]

const uint8_t * Packet::anno_u8 ( ) const

inline

overload

◆ anno_u32() [1/3]

uint32_t * Packet::anno_u32 ( )

inline

Return a pointer to the annotation area as uint32_ts.

◆ anno_u32() [2/3]

const uint32_t * Packet::anno_u32 ( ) const

inline

overload

◆ anno_u8() [3/3]

uint8_t Packet::anno_u8 ( int i ) const

inline

Return annotation byte at offset i.

Precondition: 0 <= i < anno_size

◆ set_anno_u8()

void Packet::set_anno_u8	(	int	i,
		uint8_t	x
	)

inline

Set annotation byte at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size

◆ anno_u16()

uint16_t Packet::anno_u16 ( int i ) const

inline

Return 16-bit annotation at offset i.

Precondition: 0 <= i < anno_size - 1; On aligned targets, i must be evenly divisible by 2.

Affects annotation bytes [i, i+1].

◆ set_anno_u16()

void Packet::set_anno_u16	(	int	i,
		uint16_t	x
	)

inline

Set 16-bit annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - 1; On aligned targets, i must be evenly divisible by 2.

Affects annotation bytes [i, i+1].

◆ anno_s16()

int16_t Packet::anno_s16 ( int i ) const

inline

Return 16-bit annotation at offset i.

Precondition: 0 <= i < anno_size - 1; On aligned targets, i must be evenly divisible by 2.

Affects annotation bytes [i, i+1].

◆ set_anno_s16()

void Packet::set_anno_s16	(	int	i,
		int16_t	x
	)

inline

Set 16-bit annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - 1; On aligned targets, i must be evenly divisible by 2.

Affects annotation bytes [i, i+1].

◆ anno_u32() [3/3]

uint32_t Packet::anno_u32 ( int i ) const

inline

Return 32-bit annotation at offset i.

Precondition: 0 <= i < anno_size - 3; On aligned targets, i must be evenly divisible by 4.

Affects user annotation bytes [i, i+3].

◆ set_anno_u32()

void Packet::set_anno_u32	(	int	i,
		uint32_t	x
	)

inline

Set 32-bit annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - 3; On aligned targets, i must be evenly divisible by 4.

Affects user annotation bytes [i, i+3].

◆ anno_s32()

int32_t Packet::anno_s32 ( int i ) const

inline

Return 32-bit annotation at offset i.

Precondition: 0 <= i < anno_size - 3

Affects user annotation bytes [4*i, 4*i+3].

◆ set_anno_s32()

void Packet::set_anno_s32	(	int	i,
		int32_t	x
	)

inline

Set 32-bit annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - 3; On aligned targets, i must be evenly divisible by 4.

Affects user annotation bytes [i, i+3].

◆ anno_u64()

uint64_t Packet::anno_u64 ( int i ) const

inline

Return 64-bit annotation at offset i.

Precondition: 0 <= i < anno_size - 7; On aligned targets, i must be aligned properly for uint64_t.

Affects user annotation bytes [i, i+7].

◆ set_anno_u64()

void Packet::set_anno_u64	(	int	i,
		uint64_t	x
	)

inline

Set 64-bit annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - 7; On aligned targets, i must be aligned properly for uint64_t.

Affects user annotation bytes [i, i+7].

◆ anno_ptr()

void * Packet::anno_ptr ( int i ) const

inline

Return void * sized annotation at offset i.

Precondition: 0 <= i < anno_size - sizeof(void *); On aligned targets, i must be aligned properly.

Affects user annotation bytes [i, i+sizeof(void *)].

◆ set_anno_ptr()

void Packet::set_anno_ptr	(	int	i,
		const void *	x
	)

inline

Set void * sized annotation at offset i.

Parameters

i	annotation offset in bytes
x	value

Precondition: 0 <= i < anno_size - sizeof(void *); On aligned targets, i must be aligned properly.

Affects user annotation bytes [i, i+sizeof(void *)].

◆ clear_annotations()

void Packet::clear_annotations ( bool all = true )

inline

Clear all packet annotations.

Parameters

all	If true, clear all annotations. If false, clear only Click's internal annotations.

All user annotations and the address annotation are set to zero, the packet type annotation is set to HOST, the device annotation and all header pointers are set to null, the timestamp annotation is cleared, and the next/prev-packet annotations are set to null.

If all is false, then the packet type, device, timestamp, header, and next/prev-packet annotations are left alone.

◆ copy_annotations()

void Packet::copy_annotations	(	const Packet *	p,
		bool	all = `true`
	)

inline

Copy most packet annotations from p.

Parameters

p	source of annotations

This packet's user annotations, address annotation, packet type annotation, device annotation, and timestamp annotation are set to the corresponding annotations from p.

Note: The next/prev-packet and header annotations are not copied.

The documentation for this class was generated from the following files:

include/click/packet.hh
lib/packet.cc

Data

Annotations

Header Pointers

Detailed Description

Data Buffer

Annotations

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ PacketType

Member Function Documentation

◆ make() [1/5]

◆ make() [2/5]

◆ make() [3/5]

◆ make() [4/5]

◆ empty_destructor()

◆ make() [5/5]

◆ kill()

◆ kill_nonatomic()

◆ shared()

◆ shared_nonatomic()

◆ clone()

◆ uniqueify()

◆ data()

◆ end_data()

◆ length()

◆ headroom()

◆ tailroom()

◆ buffer()

◆ end_buffer()

◆ buffer_length()

◆ push()

◆ push_mac_header()

◆ nonunique_push()

◆ pull()

◆ put()

◆ nonunique_put()

◆ take()

◆ shift_data()

◆ shrink_data()

◆ change_headroom_and_length()

◆ copy()

◆ has_mac_header()

◆ mac_header()

◆ mac_header_offset()

◆ mac_header_length()

◆ mac_length()

◆ set_mac_header() [1/2]

◆ set_mac_header() [2/2]

◆ clear_mac_header()

◆ has_network_header()

◆ network_header()

◆ network_header_offset()

◆ network_header_length()

◆ network_length()

◆ set_network_header() [1/2]

◆ set_network_header() [2/2]

◆ set_network_header_length()

◆ clear_network_header()

◆ set_transport_header()

◆ has_transport_header()

◆ transport_header()

◆ transport_header_offset()

◆ transport_length()

◆ clear_transport_header()

◆ ether_header()

◆ set_ether_header()

◆ ip_header()

◆ ip_header_offset()

◆ ip_header_length()

◆ set_ip_header()

◆ ip6_header()

◆ ip6_header_offset()

◆ ip6_header_length()

◆ set_ip6_header() [1/2]

◆ set_ip6_header() [2/2]

◆ icmp_header()

◆ tcp_header()

◆ udp_header()

◆ timestamp_anno() [1/2]