On Sep 2, 2021, at 12:05 AM, Ariel Burbaickij <ariel.burbaickij@xxxxxxxxx> wrote:
> this type of issue is IMHO better solved through having a link to a more in-depth explanation if somebody cares/wants/has to read it rather than deciding for them beforehand what they need to know and what they don't.
*ANY* documentation is going to "decide beforehand what the reader needs to know and what they don't". For example, our documentation probably will not include:
an explanation of Mendelian inheritance;
an explanation of the quantum double-slit experiment;
an explanation of question time in the British parliament;
and so on. It probably won't even, in a section about registering to dissect a given link-layer type, give an explanation of what P and NP problems are.
I.e., we're not going to, for example, dump out the entire Wikipedia and insert it at that point. We're probably not even going to give a link to the Wikipedia, or to its pages about the topics I listed above.
> In my example as dissector writer I do not care too much obviously why it happened once I hooked up properly to wtap_encap but in retrospect it was interesting to understand why I spent some half a day in vain trying to utilize "user_dlt" ;-).
The only explanation needed there, and the only explanation that would in any way improve the answer, would be something such as:
Wireshark has its own set of values for link-layer encapsulation types, the WTAP_ENCAP values, independent of the various values used in the different types of packet capture files that Wireshark can read.
To dissect a particular link-layer type in capture files, a dissector must register itself in a dissector table named "wtap_encap". For dissectors written in C, these values have names of the form WTAP_ENCAP_XXX; for Lua dissectors, the names are of the form wtap.XXX, where the XXX is the same for both names.
For example, to register a dissector for the USER0 link-layer type, which corresponds to the pcap and pcapng LINKTYPE_USER0 type, use WTAP_ENCAP_USER0 in a C dissector and wtap.USER0 in a Lua dissector. Note that values used by a particular file format, such as LINKTYPE values, will *not* work when used with the "wtap_encap" dissector table, and must *not* be used with that dissector table.
> in retrospect it was interesting to understand why I spent some half a day in vain trying to utilize "user_dlt" ;-).
The reason why it was in vain is that there *is* no "user_dlt" dissector table; there is no dissector table just for USERn values, there's just the "wtap_encap" table, used for *all* encapsulation types, including Ethernet, Wi-Fi, etc..
It would also have failed if you used a LINKTYPE value with "wtap_encap", because that's not what Wireshark uses, because no file format supports *all* the link-layer types that Wireshark can handle, so there is, for example, no LINKTYPE value for some of those link-layer types.
The goal is to tell people what they need to do, not to bore them with a tale about various BSDs choosing numerical DLT values differently that isn't even relevant, given that you don't use those values to register to dissect a link-layer type - the difference between LINKTYPE and DLT values is the difference between two set of values, *neither* of which will ever work in this context.