--- name: "pcap_ng" section: "3" platform: "macos" package: "libpcap" version: "146" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/pcap_ng" --- # pcap\_ng(3) pcap library extensions for the new pcap-ng file format ## NAME **pcap\_ng** – pcap library extensions for the new pcap-ng file format ## SYNOPSIS **#include \** *pcap\_t* *\**\ **pcap\_ng\_fopen\_offline**(*FILE \*fp*, *char \*errbuf*); *pcap\_t* *\**\ **pcap\_ng\_open\_offline**(*const char \*fname*, *char \*errbuf*); *pcap\_dumper\_t* *\**\ **pcap\_ng\_dump\_open**(*pcap\_t \*p*, *const char \*file*); *pcap\_dumper\_t* *\**\ **pcap\_ng\_dump\_fopen**(*pcap\_t \*p*, *FILE \*fp*); *void*\ **pcap\_ng\_dump**(*u\_char \*user*, *struct pcap\_pkthdr \*h*, *u\_char \*sp*); *void*\ **pcap\_ng\_dump\_close**(*pcap\_dumper\_t \*p*); *pcapng\_block\_t*\ **pcap\_ng\_block\_alloc**(*size\_t len*); *size\_t*\ **pcap\_ng\_block\_size\_max**(*void*); *int*\ **pcap\_ng\_block\_reset**(*pcapng\_block\_t block*); *int*\ **pcap\_ng\_free\_block**(*pcapng\_block\_t block*); *bpf\_u\_int32*\ **pcap\_ng\_dump\_block**(*FILE \*stream*, *pcapng\_block\_t block*); *bpf\_u\_int32*\ **pcap\_ng\_externalize\_block**(*int fd*, *pcapng\_block\_t block*); *pcapng\_block\_t*\ **pcap\_ng\_block\_alloc\_with\_raw\_block**(*pcap\_t \*p*, *u\_char \*rawblock*); *int*\ **pcap\_ng\_block\_init\_with\_raw\_block**(*pcapng\_block\_t block*, *pcap\_t \*p*, *u\_char \*rawblock*); *bpf\_u\_int32*\ **pcap\_ng\_block\_get\_type**(*pcapng\_block\_t block*); *bpf\_u\_int32*\ **pcap\_ng\_block\_get\_len**(*pcapng\_block\_t block*); *int*\ **pcap\_ng\_block\_is\_swapped**(*pcapng\_block\_t block*); *struct* *pcapng\_section\_header\_fields* *\**\ **pcap\_ng\_get\_section\_header\_fields**(*pcapng\_block\_t block*); *struct* *pcapng\_interface\_description\_fields* *\**\ **pcap\_ng\_get\_interface\_description\_fields**(*pcapng\_block\_t block*); *struct* *pcapng\_enhanced\_packet\_fields* *\**\ **pcap\_ng\_get\_enhanced\_packet\_fields**(*pcapng\_block\_t block*); *struct* *pcapng\_simple\_packet\_fields* *\**\ **pcap\_ng\_get\_simple\_packet\_fields**(*pcapng\_block\_t block*); *struct* *pcapng\_packet\_fields* *\**\ **pcap\_ng\_get\_packet\_fields**(*pcapng\_block\_t block*); *struct* *pcapng\_process\_information\_fields* *\**\ **pcap\_ng\_get\_process\_information\_fields**(*pcapng\_block\_t block*); *bpf\_u\_int32*\ **pcap\_ng\_block\_packet\_copy\_data**(*pcapng\_block\_t block*, *const void \* data*, *bpf\_u\_int32 caplen*); *bpf\_u\_int32*\ **pcap\_ng\_block\_packet\_set\_data**(*pcapng\_block\_t block*, *const void \* data*, *bpf\_u\_int32 caplen*); *void* *\**\ **pcap\_ng\_block\_packet\_get\_data\_ptr**(*pcapng\_block\_t block*); *bpf\_u\_int32*\ **pcap\_ng\_block\_packet\_get\_data\_len**(*pcapng\_block\_t block*); *int*\ **pcap\_ng\_block\_does\_support\_data**(*pcapng\_block\_t block*); *int*\ **pcap\_ng\_block\_add\_option\_with\_value**(*pcapng\_block\_t block*, *u\_short code*, *const void \*buffer*, *u\_short length*); *int*\ **pcap\_ng\_block\_add\_option\_with\_value\_string**(*pcapng\_block\_t block*, *u\_short code*, *const char \*string*); *pcapng\_option\_t*\ **pcap\_ng\_block\_get\_option**(*pcapng\_option\_t option*, *u\_short code*); *void*\ **pcapng\_block\_iterate\_options**(*pcapng\_block\_t block*, *void \* context*, *pcap\_ng\_block\_option\_iterator\_func opt\_iterator\_func*); *pcapng\_name\_record\_t*\ **pcap\_ng\_block\_add\_name\_record\_with\_ip4**(*pcapng\_block\_t block*, *struct in\_addr \* in4*, *const void \*\* names*); *pcapng\_name\_record\_t*\ **pcap\_ng\_block\_add\_name\_record\_with\_ip6**(*pcapng\_block\_t block*, *struct in6\_addr \* in6*, *const void \*\* names*); *void*\ **pcapng\_block\_iterate\_name\_records**(*pcapng\_name\_record\_t record*, *pcapng\_name\_record\_iterator\_func fn*); *int*\ **dlt\_to\_linktype**(*int dlt*); *int*\ **linktype\_to\_dlt**(*int linktype*); ## DESCRIPTION The **pcap\_ng** collection of functions and data structure is an extension to the pcap(3PCAP) library to read and write capture files in the Pcap-ng file format. While the traditional pcap(3PCAP) API is packet oriented, the **pcap\_ng** API uses pcap-ng blocks as the fundamental type of object. The following standard pcap-ng block types are supported: - section header - interface description - the three types of packet blocks - interface statistic - name resolution as well a custom block type for process information. While it's possible to access the raw content of a block, the bulk of the API provides accessor functions to facilitate the parsing and the creation of blocks and options. The purpose of this API is to provide sequential access to capture files using the Pcap-ng file format and it does not offer any facility for random access or direct edition of pcan-ng file (no addition, removal or modification of pcap-ng blocks that are present in a capture file). ### 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. ## SEE ALSO pcap\_dump\_open(3PCAP), pcap\_dump\_fopen(3PCAP), pcap\_dump(3PCAP), pcap\_dump\_close(3PCAP), [tcpdump(1)](/tcpdump/1.md) *http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html* *http://wiki.wireshark.org/Development/PcapNg*