Re: New libpcap API

[Guy Harris <guy () alum mit edu>]

On Jan 15, 2010, at 8:17 AM, Mark Bednarczyk wrote:

>  I'm the developer of a java libpcap wrapper jNetPcap. jNetPcap API
> currently provides comparible libpcap functions for almost everything prior
> to libpcap 0.9.8 version. I am planning out additional functions that I
> think need to be added to the API.
>
> Does anyone know which functions were introduced in 1.0.0 from the list
> below? I checked in changelogs but couldn't find references to most of these
> functions. Lastly, if anyone could fill in the few ??? marks for function
> description I couldn't find manpages for.
>
> pcap_create           - allocates memory for the pcap handle (must be
> followed by a corresponding pcap_activate)
> pcap_set_snaplen      - set the snapshot length for a not-yet-activated
> capture handle
> pcap_set_promisc      - set promiscuous mode for a not-yet-activated capture
> handle
> pcap_can_set_rfmon    - check whether monitor mode can be set for a
> not-yet-activated capture handle
> pcap_set_rfmon        - set monitor mode for a not-yet-activated capture
> handle
> pcap_set_timeout      - set the read timeout for a not-yet-activated capture
> handle
> pcap_set_buffer_size  - set the buffer size for a not-yet-activated capture
> handle

All introduced in 1.0.0.

> pcap_setdirection     - set the direction for which packets will be captured

Introduced in one of the 0.9.x releases.

> pcap_activate         - actives the pcap handle and most of the above
> functions may no longer be called on an active handle
> pcap_statustostr      - convert a PCAP_ERROR_ or PCAP_WARNING_ value to a
> string

Introduced in 1.0.0.

> pcap_strerror         - convert an errno value to a string (how is this
> different from pcap_geterr?)

Has been there for a *long* time.  It provides a wrapper around strerror() for the benefit of OSes that don't have 
strerror().  (libpcap is an *old* library, and dates back to an era when many UN*Xes people were using didn't have 
strerror().)

pcap_geterr() returns an error string in the error buffer in a pcap_t, rather than an error string corresponding to a 
UN*X errno; to quote the man page:

       pcap_geterr()  returns  the  error  text  pertaining  to  the last pcap
       library error.  NOTE: the pointer it returns will no longer point to  a
       valid error message string after the pcap_t passed to it is closed; you
       must use or copy the string before closing the pcap_t.

       pcap_perror() prints the text of the last pcap library error on stderr,
       prefixed by prefix.

> pcap_offline_filter   - check whether a filter matches a packet. BPF VM
> engine in user land

Introduced in 1.0.0 as a wrapper around bpf_filter().

> pcap_datalink_ext     - not sure ???

Introduced in 1.0.0; the theory was that some linktype values in a savefile could give additional information, such as 
the number of bits of FCS.  Currently, that's only used by the code to support DAG cards.

> pcap_set_datalink     - set the link-layer header type to be used by a
> capture device.
> pcap_list_datalinks   - get a list of link-layer header types supported by a
> capture device
> pcap_free_datalinks   - frees allocated memory in pcap_list_datalinks
> pcap_snapshot         - get the snapshot length set with pcap_set_snaplen or
> pcap_open_live

All introduced before 1.0.0.

> bpf_filter            - ???
> bpf_validate          - ???
> bpf_image             - ???
> bpf_dump              - ???

All introduced before 1.0.0; they're part of the userland BPF-filter code.

bpf_filter() is the filter engine, around which the somewhat-inaccurately-named pcap_offline_filter() is a wrapper 
(it's inaccurately named because it can be used in a live capture as well - you might, for example, have an application 
that uses a BPF filter expression as a "start capturing" or "stop capturing" trigger, in which case your app would have 
to evaluate that in userland).

bpf_validate() checks whether a BPF program is "safe".  It's mainly of interest in the OS kernel, so that applications 
can't hand to the kernel a program that could loop or cause a zero-divide fault or reference arbitrary memory locations 
or....

bpf_image() is an routine that takes a BPF instruction and generates a "assembly-language" string for it.

bpf_dump() is a routine that takes a BPF program and dumps out the instructions, perhaps as raw instruction fields or 
perhaps as "assembly-language" strings as generated by bpf_image(), depending on the second argument value.  It's 
mainly used by tcpdump's "-d" option.

None other than bpf_filter() are guaranteed to remain as they are in the future.-
This is the tcpdump-workers list.
Visit https://cod.sandelman.ca/ to unsubscribe.