pcap_ng(3)

Opening a pcap-ng file

To open a handle for a pcap-ng capture file from which to read pcap-ng blocks use either pcap_ng_fopen_offline() or pcap_ng_open_offline(). As these functions return a NULL value if the file is not in the pcap-ng format, one should then try opening the file using pcap_fopen_offline(3PCAP) or pcap_open_offline(3PCAP).

To open a new pcap-ng capture file to save pcap-ng blocks use either pcap_ng_dump_open() or pcap_ng_dump_fopen().

The above functions return a pcap_t that may be used with most of the pcap(3PCAP) functions that accept a capture handle.

When used with a pcap_t handle of file in the pcap-ng format, pcap_datalink(3PCAP) return the pseudo data link type DLT_PCAPNG as a pcap-ng file may contain packets with different data link type.

Call pcap_ng_dump_close() to close the handle of a pcap-ng file.

Reading pcap-ng blocks

To read blocks from a pcap-ng file opened by pcap_ng_fopen_offline() or pcap_ng_open_offline() simply call the traditional functions pcap_dispatch() or pcap_loop() or pcap_next() or pcap_next_ex(). The difference is that instead of getting a pointer to a packet, the function or the callback gets a buffer to a raw pcap-ng block.

The raw pcap-ng may be parsed manually or it may be passed to the function pcap_ng_create_with_raw_block() to create an internalized representation of the block and used with other pcap_ng accessor functions.

Writing pcap-ng blocks

The function pcap_ng_dump_block() takes a pcapng_block_t object, and writes it to the capture file in the pcap-ng file format.

Creating a pcap-ng block internalized object

Internalized pcap-ng block objects are represented by the opaque data type pcapng_block_t and accessor functions may be used to read and write the content of a pcapng_block_t object (header and options). A pcapng_block_t object may be re-used to mimimize memory allocations.

The function pcap_ng_block_alloc() allocates a pcapng_block_t object to hold an pcap-ng block data structure. This allocate a work buffer to hold the raw data block content so the given size should be large enough to hold the largest expected raw block size.

If the size given to pcap_ng_block_alloc() is greater than the value returned by pcap_ng_block_size_max() then the allocation fails and pcap_ng_block_alloc() returns NULL.

To reuse an existing internalized pcapng_block_t object, use the function pcap_ng_block_reset() as it is more efficient to reuse than to allocate a new data structure of each pcap-ng block being read or written.

The function pcap_ng_free_block() deletes the memory used by the pcapng_block_t object.

The function pcap_ng_block_init_with_raw_block() parses a raw pcap-ng block buffer into an internalized form using an existing pcapng_block_t object. This is typically used when reading from a pcap-ng capture file.

The function pcap_ng_block_alloc_with_raw_block() creates a pcapng_block_t object from a raw pcap-ng buffer buffer.

Getting information about a pcap-ng block

The function pcap_ng_block_get_type() returns the type of a pcapng_block_t object.

The function pcap_ng_block_is_swapped() returns the byte order of a pcapng_block_t object. This is useful when reading pcap-ng blocks and options from a pcap-ng capture file. This actually reflects the byte order magic of the section header block.

The function pcap_ng_block_get_len() returns the length of the externalized form of a pcapng_block_t object.

The following functions return the fixed header size corresponding to the supported block types:

• pcapng_section_header_fields()

• pcapng_interface_description_fields()

• pcapng_enhanced_packet_fields()

• pcapng_simple_packet_fields()

• pcapng_packet_fields()

• pcapng_process_information_fields()

Accessing the data of packet blocks

The same functions may be used to access the data portion of the three types of packet blocks:

enhanced packet block

simple packet block

packet block

The function pcap_ng_block_packet_copy_data() copies the content of the passed data buffer into the pcapng_block_t packet object. This may involve memory allocation to hold the data.

The function pcap_ng_block_packet_set_data uses the passed data buffer as a pointer reference to an external buffer. Using pcap_ng_block_packet_set_data() is more efficient than pcap_ng_block_packet_copy_data() as this does not involve data movement or memory allocation, but the caller must make sure the passed data buffer is kept intact for the lifetime of the pcapng_block_t packet object.

The function pcap_ng_block_delete_data() empties the pcapng_block_t packet object from any data so its length becomes zero.

The function pcap_ng_block_packet_get_data_ptr() returns a pointer on the beginning of the data portion of the pcapng_block_t packet object.

The function pcap_ng_block_packet_get_data_len() returns the length of the data referred to by the pcapng_block_t packet object.

The function pcap_ng_block_does_support_data() returns a non-zero value when the passed pcapng_block_t in a pcap-ng block with data of variable length.

Accessing pcap-ng options

To add an option to a pcapng_block_t packet object use the function pcap_ng_block_add_option_with_value().

When the option value is a null terminated string, one may use the function pcap_ng_block_add_option_with_string() that includes the terminating null byte in the option value.

To get a single option value one may use the function pcap_ng_block_get_option() when an option may appear at most once in a pcap-ng block.

The function walks the list of options pcapng_block_t and calls the given callback function of each option.

Keeping track of interface information

pcap_ng provides utility functions to help keep track of interface information associated with a pcap_t handle using the data structure struct pcap_if_info. The interface IDs being specific to a given section, the list of interface information should be cleared whenever a new section is being processed.

The function pcap_add_if_info() add an interface information. The interface ID is assigned sequentially so the corresponding interface block needs to be written to the save file to avoid reference to missing interfaces caused by filtering.

The function pcap_find_if_info_by_name() returns the struct pcap_if_info that matches the given name.

The function pcap_find_if_info_by_id() returns the struct pcap_if_info that matches the given interface id.

The function pcap_free_if_info() frees struct pcap_if_info and removes it from the pcap_t handle. Removing a single struct pcap_if_info is not a common usage.

The function pcap_clear_if_infos() removes all the struct pcap_if_info structures from a pcap_t * handle. This is useful when processing a new section header block as the interface IDs are valid with a section.

Use the function pcap_ng_init_section_info() to reinitialize the section specific data like interface information and process information. This should be used when adding a new section header. This is also useful when saving to a new packet capture files, for example when "rotating" files.

Keeping track of process information

pcap_ng provide utility functions to help keep track of process information associated with a pcap_t handle using the data structure struct pcap_proc_info. The process information indexes being specific to a given section, the list of process information should be cleared whenever a new section is being processed.

The function pcap_add_proc_info() adds a process information.

The function pcap_find_proc_info() returns the struct pcap_proc_info that matches the given process name and ID.

The function pcap_find_proc_info_by_index() returns the struct pcap_proc_info that matches the given process information index.

The function pcap_free_proc_info() frees struct pcap_proc_info and removes it from the pcap_t handle. Removing a single struct pcap_proc_info is not a common usage.

The function pcap_clear_proc_infos() removes all the struct pcap_proc_info structures from a pcap_t * handle. This is useful when processing a new section header block as the process information indexes are valid within a section.

Handling special pktap and iptap interfaces

The function pcap_setup_pktap_interface() creates a cloned pktap or iptap interface to be used as a capture device.

The function pcap_cleanup_pktap_interface() destroys a cloned pktap or iptap interface that was used as a capture device.

Dumping packet with ptkap header

The function pcap_ng_dump_pktap() saves a packet with a struct pcap_pkthdr header as a pcap-ng enhanced data block. It handles the packet metadata information from the struct pcap_pkthdr and creates process information blocks and interface information blocks as needed. It returns 1 if the packet passes the filter, 0 otherwise. The function pcap_ng_dump_pktap_comment() saves a packet like pcap_ng_dump_pktap() with the addition of a comment string parameter that is added to the pcap-ng enhanced data block.