NAME

pcap - Packet Capture library

SYNOPSIS


##iinncclluuddee <>


cchhaarr eerrrrbbuuff[[PPCCAAPP__EERRRRBBUUFF__SSIIZZEE]];;

ppccaapp__tt **ppccaapp__ooppeenn__lliivvee((ccoonnsstt cchhaarr **ddeevviiccee,, iinntt ssnnaapplleenn,, iinntt pprroommiisscc,, iinntt ttoo__mmss,, cchhaarr **eerrrrbbuuff)) ppccaapp__tt **ppccaapp__ooppeenn__ddeeaadd((iinntt lliinnkkttyyppee,, iinntt ssnnaapplleenn)) ppccaapp__tt **ppccaapp__ooppeenn__oofffflliinnee((ccoonnsstt cchhaarr **ffnnaammee,, cchhaarr **eerrrrbbuuff)) ppccaapp__tt **ppccaapp__ffooppeenn__oofffflliinnee((FFIILLEE **ffpp,, cchhaarr **eerrrrbbuuff)) ppccaapp__dduummppeerr__tt **ppccaapp__dduummpp__ooppeenn((ppccaapp__tt **pp,, ccoonnsstt cchhaarr **ffnnaammee)) ppccaapp__dduummppeerr__tt **ppccaapp__dduummpp__ffooppeenn((ppccaapp__tt **pp,, FFIILLEE **ffpp))

iinntt ppccaapp__sseettnnoonnbblloocckk((ppccaapp__tt **pp,, iinntt nnoonnbblloocckk,, cchhaarr **eerrrrbbuuff));; iinntt ppccaapp__ggeettnnoonnbblloocckk((ppccaapp__tt **pp,, cchhaarr **eerrrrbbuuff));;

iinntt ppccaapp__ffiinnddaallllddeevvss((ppccaapp__iiff__tt ****aallllddeevvsspp,, cchhaarr **eerrrrbbuuff)) vvooiidd ppccaapp__ffrreeeeaallllddeevvss((ppccaapp__iiff__tt **aallllddeevvss)) cchhaarr **ppccaapp__llooookkuuppddeevv((cchhaarr **eerrrrbbuuff)) iinntt ppccaapp__llooookkuuppnneett((ccoonnsstt cchhaarr **ddeevviiccee,, bbppff__uu__iinntt3322 **nneettpp,, bbppff__uu__iinntt3322 **mmaasskkpp,, cchhaarr **eerrrrbbuuff))

ttyyppeeddeeff vvooiidd ((**ppccaapp__hhaannddlleerr))((uu__cchhaarr **uusseerr,, ccoonnsstt ssttrruucctt ppccaapp__ppkktthhddrr **hh,, ccoonnsstt uu__cchhaarr **bbyytteess));; iinntt ppccaapp__ddiissppaattcchh((ppccaapp__tt **pp,, iinntt ccnntt,, ppccaapp__hhaannddlleerr ccaallllbbaacckk,, uu__cchhaarr **uusseerr)) iinntt ppccaapp__lloooopp((ppccaapp__tt **pp,, iinntt ccnntt,, ppccaapp__hhaannddlleerr ccaallllbbaacckk,, uu__cchhaarr **uusseerr)) vvooiidd ppccaapp__dduummpp((uu__cchhaarr **uusseerr,, ssttrruucctt ppccaapp__ppkktthhddrr **hh,, uu__cchhaarr **sspp)) <> iinntt ppccaapp__ccoommppiillee((ppccaapp__tt **pp,, ssttrruucctt bbppff__pprrooggrraamm **ffpp,, ccoonnsstt cchhaarr **ssttrr,, iinntt ooppttiimmiizzee,, bbppff__uu__iinntt3322 nneettmmaasskk)) iinntt ppccaapp__sseettffiilltteerr((ppccaapp__tt **pp,, ssttrruucctt bbppff__pprrooggrraamm **ffpp)) vvooiidd ppccaapp__ffrreeeeccooddee((ssttrruucctt bbppff__pprrooggrraamm **)) iinntt ppccaapp__sseettddiirreeccttiioonn((ppccaapp__tt **pp,, ppccaapp__ddiirreeccttiioonn__tt dd)) <> ccoonnsstt uu__cchhaarr **ppccaapp__nneexxtt((ppccaapp__tt **pp,, ssttrruucctt ppccaapp__ppkktthhddrr **hh)) iinntt ppccaapp__nneexxtt__eexx((ppccaapp__tt **pp,, ssttrruucctt ppccaapp__ppkktthhddrr ****ppkktt__hheeaaddeerr,, ccoonnsstt uu__cchhaarr ****ppkktt__ddaattaa)) <> vvooiidd ppccaapp__bbrreeaakklloooopp((ppccaapp__tt **)) <> iinntt ppccaapp__iinnjjeecctt((ppccaapp__tt **pp,, ccoonnsstt vvooiidd **bbuuff,, ssiizzee__tt ssiizzee)) iinntt ppccaapp__sseennddppaacckkeett((ppccaapp__tt **pp,, ccoonnsstt uu__cchhaarr **bbuuff,, iinntt ssiizzee)) <> iinntt ppccaapp__ddaattaalliinnkk((ppccaapp__tt **pp)) iinntt ppccaapp__lliisstt__ddaattaalliinnkkss((ppccaapp__tt **pp,, iinntt ****ddlltt__bbuuff));; iinntt ppccaapp__sseett__ddaattaalliinnkk((ppccaapp__tt **pp,, iinntt ddlltt));; iinntt ppccaapp__ddaattaalliinnkk__nnaammee__ttoo__vvaall((ccoonnsstt cchhaarr **nnaammee));; ccoonnsstt cchhaarr **ppccaapp__ddaattaalliinnkk__vvaall__ttoo__nnaammee((iinntt ddlltt));; ccoonnsstt cchhaarr **ppccaapp__ddaattaalliinnkk__vvaall__ttoo__ddeessccrriippttiioonn((iinntt ddlltt));; iinntt ppccaapp__ssnnaappsshhoott((ppccaapp__tt **pp)) iinntt ppccaapp__iiss__sswwaappppeedd((ppccaapp__tt **pp)) iinntt ppccaapp__mmaajjoorr__vveerrssiioonn((ppccaapp__tt **pp)) iinntt ppccaapp__mmiinnoorr__vveerrssiioonn((ppccaapp__tt **pp)) iinntt ppccaapp__ssttaattss((ppccaapp__tt **pp,, ssttrruucctt ppccaapp__ssttaatt **ppss)) FFIILLEE **ppccaapp__ffiillee((ppccaapp__tt **pp)) iinntt ppccaapp__ffiilleennoo((ppccaapp__tt **pp)) iinntt ppccaapp__ggeett__sseelleeccttaabbllee__ffdd((ppccaapp__tt **pp));; vvooiidd ppccaapp__ppeerrrroorr((ppccaapp__tt **pp,, cchhaarr **pprreeffiixx)) cchhaarr **ppccaapp__ggeetteerrrr((ppccaapp__tt **pp)) ccoonnsstt cchhaarr **ppccaapp__ssttrreerrrroorr((iinntt eerrrroorr)) ccoonnsstt cchhaarr **ppccaapp__lliibb__vveerrssiioonn((vvooiidd)) <> vvooiidd ppccaapp__cclloossee((ppccaapp__tt **pp)) iinntt ppccaapp__dduummpp__fflluusshh((ppccaapp__dduummppeerr__tt **pp)) lloonngg ppccaapp__dduummpp__fftteellll((ppccaapp__dduummppeerr__tt **pp)) FFIILLEE **ppccaapp__dduummpp__ffiillee((ppccaapp__dduummppeerr__tt **pp)) vvooiidd ppccaapp__dduummpp__cclloossee((ppccaapp__dduummppeerr__tt **pp)) <> DDEESSCCRRIIPPTTIIOONN <> TThhee PPaacckkeett CCaappttuurree lliibbrraarryy pprroovviiddeess aa hhiigghh lleevveell iinntteerrffaaccee ttoo ppaacckkeett ccaappttuurree ssyysstteemmss.. AAllll ppaacckkeettss oonn tthhee nneettwwoorrkk,, eevveenn tthhoossee ddeessttiinneedd ffoorr ootthheerr hhoossttss,, aarree aacccceessssiibbllee tthhrroouugghh tthhiiss mmeecchhaanniissmm.. <> <> RROOUUTTIINNEESS <> NNOOTTEE:: <>eerrrrbbuuff<> iinn <>ppccaapp__ooppeenn__lliivvee(())<>,, <>ppccaapp__ooppeenn__ddeeaadd(())<>,, <>ppccaapp__ooppeenn__oofffflliinnee(())<>,, <>ppccaapp__ffooppeenn__oofffflliinnee(())<>,, <>ppccaapp__sseettnnoonnbblloocckk(())<>,, <>ppccaapp__ggeettnnoonnbblloocckk(())<>,, <>ppccaapp__ffiinnddaallllddeevvss(())<>,, <>ppccaapp__llooookkuuppddeevv(())<>,, aanndd <>ppccaapp__llooookkuuppnneett(())<> iiss aassssuummeedd ttoo bbee aabbllee ttoo hhoolldd aatt lleeaasstt <>PPCCAAPP__EERRRRBBUUFF__SSIIZZEE<> cchhaarrss.. <> <>ppccaapp__ooppeenn__lliivvee(())<> iiss uusseedd ttoo oobbttaaiinn aa ppaacckkeett ccaappttuurree ddeessccrriippttoorr ttoo llooookk aatt ppaacckkeettss oonn tthhee nneettwwoorrkk.. <>ddeevviiccee<> iiss aa ssttrriinngg tthhaatt ssppeecciiffiieess tthhee nneettwwoorrkk ddeevviiccee ttoo ooppeenn;; oonn LLiinnuuxx ssyysstteemmss wwiitthh 22..22 oorr llaatteerr kkeerrnneellss,, aa <>ddeevviiccee<> aarrgguummeenntt ooff ""aannyy"" oorr <>NNUULLLL<> ccaann bbee uusseedd ttoo ccaappttuurree ppaacckkeettss ffrroomm aallll iinntteerrffaacceess.. <>ssnnaapplleenn<> ssppeecciiffiieess tthhee mmaaxxiimmuumm nnuummbbeerr ooff bbyytteess ttoo ccaappttuurree.. IIff tthhiiss vvaalluuee iiss lleessss tthhaann tthhee ssiizzee ooff aa ppaacckkeett tthhaatt iiss ccaappttuurreedd,, oonnllyy tthhee ffiirrsstt <>ssnnaapplleenn<> bbyytteess ooff tthhaatt ppaacckkeett wwiillll bbee ccaappttuurreedd aanndd pprroovviiddeedd aass ppaacckkeett ddaattaa.. AA vvaalluuee ooff 6655553355 sshhoouulldd bbee ssuuffffiicciieenntt,, oonn mmoosstt iiff nnoott aallll nneettwwoorrkkss,, ttoo ccaappttuurree aallll tthhee ddaattaa aavvaaiillaabbllee ffrroomm tthhee ppaacckkeett.. <>pprroommiisscc<> ssppeecciiffiieess iiff tthhee iinntteerrffaaccee iiss ttoo bbee ppuutt iinnttoo pprroommiissccuuoouuss mmooddee.. ((NNoottee tthhaatt eevveenn iiff tthhiiss ppaarraammeetteerr iiss ffaallssee,, tthhee iinntteerrffaaccee ccoouulldd wweellll bbee iinn pprroommiissccuuoouuss mmooddee ffoorr ssoommee ootthheerr rreeaassoonn..)) FFoorr nnooww,, tthhiiss ddooeessnn''tt wwoorrkk oonn tthhee ""aannyy"" ddeevviiccee;; iiff aann aarrgguummeenntt ooff ""aannyy"" oorr NNUULLLL iiss ssuupppplliieedd,, tthhee <>pprroommiisscc<> ffllaagg iiss iiggnnoorreedd.. <>ttoo__mmss<> ssppeecciiffiieess tthhee rreeaadd ttiimmeeoouutt iinn mmiilllliisseeccoonnddss.. TThhee rreeaadd ttiimmeeoouutt iiss uusseedd ttoo aarrrraannggee tthhaatt tthhee rreeaadd nnoott nneecceessssaarriillyy rreettuurrnn iimmmmeeddiiaatteellyy wwhheenn aa ppaacckkeett iiss sseeeenn,, bbuutt tthhaatt iitt wwaaiitt ffoorr ssoommee aammoouunntt ooff ttiimmee ttoo aallllooww mmoorree ppaacckkeettss ttoo aarrrriivvee aanndd ttoo rreeaadd mmuullttiippllee ppaacckkeettss ffrroomm tthhee OOSS kkeerrnneell iinn oonnee ooppeerraattiioonn.. NNoott aallll ppllaattffoorrmmss ssuuppppoorrtt aa rreeaadd ttiimmeeoouutt;; oonn ppllaattffoorrmmss tthhaatt ddoonn''tt,, tthhee rreeaadd ttiimmeeoouutt iiss iiggnnoorreedd.. AA zzeerroo vvaalluuee ffoorr <>ttoo__mmss<>,, oonn ppllaattffoorrmmss tthhaatt ssuuppppoorrtt aa rreeaadd ttiimmeeoouutt,, wwiillll ccaauussee aa rreeaadd ttoo wwaaiitt ffoorreevveerr ttoo aallllooww eennoouugghh ppaacckkeettss ttoo aarrrriivvee,, wwiitthh nnoo ttiimmeeoouutt.. <>eerrrrbbuuff<> iiss uusseedd ttoo rreettuurrnn eerrrroorr oorr wwaarrnniinngg tteexxtt.. IItt wwiillll bbee sseett ttoo eerrrroorr tteexxtt wwhheenn <>ppccaapp__ooppeenn__lliivvee(())<> ffaaiillss aanndd rreettuurrnnss <>NNUULLLL<>.. <>eerrrrbbuuff<> mmaayy aallssoo bbee sseett ttoo wwaarrnniinngg tteexxtt wwhheenn <>ppccaapp__ooppeenn__lliivvee(())<> ssuucccceeddss;; ttoo ddeetteecctt tthhiiss ccaassee tthhee ccaalllleerr sshhoouulldd ssttoorree aa zzeerroo--lleennggtthh ssttrriinngg iinn <>eerrrrbbuuff<> bbeeffoorree ccaalllliinngg <>ppccaapp__ooppeenn__lliivvee(())<> aanndd ddiissppllaayy tthhee wwaarrnniinngg ttoo tthhee uusseerr iiff <>eerrrrbbuuff<> iiss nnoo lloonnggeerr aa zzeerroo--lleennggtthh ssttrriinngg.. <> <>ppccaapp__ooppeenn__ddeeaadd(())<> iiss uusseedd ffoorr ccrreeaattiinngg aa <>ppccaapp__tt<> ssttrruuccttuurree ttoo uussee wwhheenn ccaalllliinngg tthhee ootthheerr ffuunnccttiioonnss iinn lliibbppccaapp.. IItt iiss ttyyppiiccaallllyy uusseedd wwhheenn jjuusstt uussiinngg lliibbppccaapp ffoorr ccoommppiilliinngg BBPPFF ccooddee.. <> <>ppccaapp__ooppeenn__oofffflliinnee(())<> iiss ccaalllleedd ttoo ooppeenn aa ````ssaavveeffiillee'''' ffoorr rreeaaddiinngg.. <>ffnnaammee<> ssppeecciiffiieess tthhee nnaammee ooff tthhee ffiillee ttoo ooppeenn.. TThhee ffiillee hhaass tthhee ssaammee ffoorrmmaatt aass tthhoossee uusseedd bbyy <>ttccppdduummpp((11))<> aanndd <>ttccppsslliiccee((11))<>.. TThhee nnaammee ""--"" iinn aa ssyynnoonnyymm ffoorr <>ssttddiinn<>.. AAlltteerrnnaattiivveellyy,, yyoouu mmaayy ccaallll <>ppccaapp__ffooppeenn__oofffflliinnee(())<> ttoo rreeaadd dduummppeedd ddaattaa ffrroomm aann eexxiissttiinngg ooppeenn ssttrreeaamm <>ffpp<>.. NNoottee tthhaatt oonn WWiinnddoowwss,, tthhaatt ssttrreeaamm sshhoouulldd bbee ooppeenneedd iinn bbiinnaarryy mmooddee.. <>eerrrrbbuuff<> iiss uusseedd ttoo rreettuurrnn eerrrroorr tteexxtt aanndd iiss oonnllyy sseett wwhheenn <>ppccaapp__ooppeenn__oofffflliinnee(())<> oorr <>ppccaapp__ffooppeenn__oofffflliinnee(())<> ffaaiillss aanndd rreettuurrnnss <>NNUULLLL<>.. <> <>ppccaapp__dduummpp__ooppeenn(())<> iiss ccaalllleedd ttoo ooppeenn aa ````ssaavveeffiillee'''' ffoorr wwrriittiinngg.. TThhee nnaammee ""--"" iinn aa ssyynnoonnyymm ffoorr <>ssttddoouutt<>.. <>NNUULLLL<> iiss rreettuurrnneedd oonn ffaaiilluurree.. <>pp<> iiss aa <>ppccaapp<> ssttrruucctt aass rreettuurrnneedd bbyy <>ppccaapp__ooppeenn__oofffflliinnee(())<> oorr <>ppccaapp__ooppeenn__lliivvee(())<>.. <>ffnnaammee<> ssppeecciiffiieess tthhee nnaammee ooff tthhee ffiillee ttoo ooppeenn.. AAlltteerrnnaattiivveellyy,, yyoouu mmaayy ccaallll <>ppccaapp__dduummpp__ffooppeenn(())<> ttoo wwrriittee ddaattaa ttoo aann eexxiissttiinngg ooppeenn ssttrreeaamm <>ffpp<>.. NNoottee tthhaatt oonn WWiinnddoowwss,, tthhaatt ssttrreeaamm sshhoouulldd bbee ooppeenneedd iinn bbiinnaarryy mmooddee.. IIff <>NNUULLLL<> iiss rreettuurrnneedd,, <>ppccaapp__ggeetteerrrr(())<> ccaann bbee uusseedd ttoo ggeett tthhee eerrrroorr tteexxtt.. <> <> <>ppccaapp__sseettnnoonnbblloocckk(())<> ppuuttss aa ccaappttuurree ddeessccrriippttoorr,, ooppeenneedd wwiitthh <>ppccaapp__ooppeenn__lliivvee(())<>,, iinnttoo ````nnoonn--bblloocckkiinngg'''' mmooddee,, oorr ttaakkeess iitt oouutt ooff ````nnoonn--bblloocckkiinngg'''' mmooddee,, ddeeppeennddiinngg oonn wwhheetthheerr tthhee <>nnoonnbblloocckk<> aarrgguummeenntt iiss nnoonn--zzeerroo oorr zzeerroo.. IItt hhaass nnoo eeffffeecctt oonn ````ssaavveeffiilleess''''.. IIff tthheerree iiss aann eerrrroorr,, --11 iiss rreettuurrnneedd aanndd <>eerrrrbbuuff<> iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee;; ootthheerrwwiissee,, 00 iiss rreettuurrnneedd.. IInn ````nnoonn--bblloocckkiinngg'''' mmooddee,, aann aatttteemmpptt ttoo rreeaadd ffrroomm tthhee ccaappttuurree ddeessccrriippttoorr wwiitthh <>ppccaapp__ddiissppaattcchh(())<> wwiillll,, iiff nnoo ppaacckkeettss aarree ccuurrrreennttllyy aavvaaiillaabbllee ttoo bbee rreeaadd,, rreettuurrnn 00 iimmmmeeddiiaatteellyy rraatthheerr tthhaann bblloocckkiinngg wwaaiittiinngg ffoorr ppaacckkeettss ttoo aarrrriivvee.. <>ppccaapp__lloooopp(())<> aanndd <>ppccaapp__nneexxtt(())<> wwiillll nnoott wwoorrkk iinn ````nnoonn--bblloocckkiinngg'''' mmooddee.. <> <>ppccaapp__ggeettnnoonnbblloocckk(())<> rreettuurrnnss tthhee ccuurrrreenntt ````nnoonn--bblloocckkiinngg'''' ssttaattee ooff tthhee ccaappttuurree ddeessccrriippttoorr;; iitt aallwwaayyss rreettuurrnnss 00 oonn ````ssaavveeffiilleess''''.. IIff tthheerree iiss aann eerrrroorr,, --11 iiss rreettuurrnneedd aanndd <>eerrrrbbuuff<> iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee.. <> <>ppccaapp__ffiinnddaallllddeevvss(())<> ccoonnssttrruuccttss aa lliisstt ooff nneettwwoorrkk ddeevviicceess tthhaatt ccaann bbee ooppeenneedd wwiitthh <>ppccaapp__ooppeenn__lliivvee(())<>.. ((NNoottee tthhaatt tthheerree mmaayy bbee nneettwwoorrkk ddeevviicceess tthhaatt ccaannnnoott bbee ooppeenneedd wwiitthh ppccaapp__ooppeenn__lliivvee(()) bbyy tthhee pprroocceessss ccaalllliinngg <>ppccaapp__ffiinnddaallllddeevvss(())<>,, bbeeccaauussee,, ffoorr eexxaammppllee,, tthhaatt pprroocceessss mmiigghhtt nnoott hhaavvee ssuuffffiicciieenntt pprriivviilleeggeess ttoo ooppeenn tthheemm ffoorr ccaappttuurriinngg;; iiff ssoo,, tthhoossee ddeevviicceess wwiillll nnoott aappppeeaarr oonn tthhee lliisstt..)) <>aallllddeevvsspp<> iiss sseett ttoo ppooiinntt ttoo tthhee ffiirrsstt eelleemmeenntt ooff tthhee lliisstt;; eeaacchh eelleemmeenntt ooff tthhee lliisstt iiss ooff ttyyppee <>ppccaapp__iiff__tt<>,, aanndd hhaass tthhee ffoolllloowwiinngg mmeemmbbeerrss:: <> <> <>nneexxtt<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo tthhee nneexxtt eelleemmeenntt iinn tthhee lliisstt;; <>NNUULLLL<> ffoorr tthhee llaasstt eelleemmeenntt ooff tthhee lliisstt <> <>nnaammee<> <> aa ppooiinntteerr ttoo aa ssttrriinngg ggiivviinngg aa nnaammee ffoorr tthhee ddeevviiccee ttoo ppaassss ttoo <>ppccaapp__ooppeenn__lliivvee(())<> <> <>ddeessccrriippttiioonn<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo aa ssttrriinngg ggiivviinngg aa hhuummaann--rreeaaddaabbllee ddeessccrriippttiioonn ooff tthhee ddeevviiccee <> <>aaddddrreesssseess<> <> aa ppooiinntteerr ttoo tthhee ffiirrsstt eelleemmeenntt ooff aa lliisstt ooff aaddddrreesssseess ffoorr tthhee iinntteerrffaaccee <> <>ffllaaggss<> <> iinntteerrffaaccee ffllaaggss:: <> <>PPCCAAPP__IIFF__LLOOOOPPBBAACCKK<> <> sseett iiff tthhee iinntteerrffaaccee iiss aa llooooppbbaacckk iinntteerrffaaccee <> <> EEaacchh eelleemmeenntt ooff tthhee lliisstt ooff aaddddrreesssseess iiss ooff ttyyppee <>ppccaapp__aaddddrr__tt<>,, aanndd hhaass tthhee ffoolllloowwiinngg mmeemmbbeerrss:: <> <> <>nneexxtt<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo tthhee nneexxtt eelleemmeenntt iinn tthhee lliisstt;; <>NNUULLLL<> ffoorr tthhee llaasstt eelleemmeenntt ooff tthhee lliisstt <> <>aaddddrr<> <> aa ppooiinntteerr ttoo aa <>ssttrruucctt ssoocckkaaddddrr<> ccoonnttaaiinniinngg aann aaddddrreessss <> <>nneettmmaasskk<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo aa <>ssttrruucctt ssoocckkaaddddrr<> tthhaatt ccoonnttaaiinnss tthhee nneettmmaasskk ccoorrrreessppoonnddiinngg ttoo tthhee aaddddrreessss ppooiinntteedd ttoo bbyy <>aaddddrr<> <> <>bbrrooaaddaaddddrr<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo aa <>ssttrruucctt ssoocckkaaddddrr<> tthhaatt ccoonnttaaiinnss tthhee bbrrooaaddccaasstt aaddddrreessss ccoorrrreessppoonnddiinngg ttoo tthhee aaddddrreessss ppooiinntteedd ttoo bbyy <>aaddddrr<>;; mmaayy bbee nnuullll iiff tthhee iinntteerrffaaccee ddooeessnn''tt ssuuppppoorrtt bbrrooaaddccaassttss <> <>ddssttaaddddrr<> <> iiff nnoott <>NNUULLLL<>,, aa ppooiinntteerr ttoo aa <>ssttrruucctt ssoocckkaaddddrr<> tthhaatt ccoonnttaaiinnss tthhee ddeessttiinnaattiioonn aaddddrreessss ccoorrrreessppoonnddiinngg ttoo tthhee aaddddrreessss ppooiinntteedd ttoo bbyy <>aaddddrr<>;; mmaayy bbee nnuullll iiff tthhee iinntteerrffaaccee iissnn''tt aa ppooiinntt--ttoo--ppooiinntt iinntteerrffaaccee <> <> NNoottee tthhaatt nnoott aallll tthhee aaddddrreesssseess iinn tthhee lliisstt ooff aaddddrreesssseess aarree nneecceessssaarriillyy IIPPvv44 oorr IIPPvv66 aaddddrreesssseess -- yyoouu mmuusstt cchheecckk tthhee <>ssaa__ffaammiillyy<> mmeemmbbeerr ooff tthhee <>ssttrruucctt ssoocckkaaddddrr<> bbeeffoorree iinntteerrpprreettiinngg tthhee ccoonntteennttss ooff tthhee aaddddrreessss.. <> <>--11<> iiss rreettuurrnneedd oonn ffaaiilluurree,, iinn wwhhiicchh ccaassee <>eerrrrbbuuff<> iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee;; <>00<> iiss rreettuurrnneedd oonn ssuucccceessss.. <> <>ppccaapp__ffrreeeeaallllddeevvss(())<> iiss uusseedd ttoo ffrreeee aa lliisstt aallllooccaatteedd bbyy <>ppccaapp__ffiinnddaallllddeevvss(())<>.. <> <>ppccaapp__llooookkuuppddeevv(())<> rreettuurrnnss aa ppooiinntteerr ttoo aa nneettwwoorrkk ddeevviiccee ssuuiittaabbllee ffoorr uussee wwiitthh <>ppccaapp__ooppeenn__lliivvee(())<> aanndd <>ppccaapp__llooookkuuppnneett(())<>.. IIff tthheerree iiss aann eerrrroorr,, <>NNUULLLL<> iiss rreettuurrnneedd aanndd <>eerrrrbbuuff<> iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee.. <> <>ppccaapp__llooookkuuppnneett(())<> iiss uusseedd ttoo ddeetteerrmmiinnee tthhee nneettwwoorrkk nnuummbbeerr aanndd mmaasskk aassssoocciiaatteedd wwiitthh tthhee nneettwwoorrkk ddeevviiccee <>ddeevviiccee<>.. BBootthh <>nneettpp<> aanndd <>mmaasskkpp<> aarree <>bbppff__uu__iinntt3322<> ppooiinntteerrss.. AA rreettuurrnn ooff --11 iinnddiiccaatteess aann eerrrroorr iinn wwhhiicchh ccaassee <>eerrrrbbuuff<> iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee.. <> <>ppccaapp__ddiissppaattcchh(())<> iiss uusseedd ttoo ccoolllleecctt aanndd pprroocceessss ppaacckkeettss.. <>ccnntt<> ssppeecciiffiieess tthhee mmaaxxiimmuumm nnuummbbeerr ooff ppaacckkeettss ttoo pprroocceessss bbeeffoorree rreettuurrnniinngg.. TThhiiss iiss nnoott aa mmiinniimmuumm nnuummbbeerr;; wwhheenn rreeaaddiinngg aa lliivvee ccaappttuurree,, oonnllyy oonnee bbuuffffeerrffuull ooff ppaacckkeettss iiss rreeaadd aatt aa ttiimmee,, ssoo ffeewweerr tthhaann <>ccnntt<> ppaacckkeettss mmaayy bbee pprroocceesssseedd.. AA <>ccnntt<> ooff --11 pprroocceesssseess aallll tthhee ppaacckkeettss rreecceeiivveedd iinn oonnee bbuuffffeerr wwhheenn rreeaaddiinngg aa lliivvee ccaappttuurree,, oorr aallll tthhee ppaacckkeettss iinn tthhee ffiillee wwhheenn rreeaaddiinngg aa ````ssaavveeffiillee''''.. <>ccaallllbbaacckk<> ssppeecciiffiieess aa rroouuttiinnee ttoo bbee ccaalllleedd wwiitthh tthhrreeee aarrgguummeennttss:: aa <>uu__cchhaarr<> ppooiinntteerr wwhhiicchh iiss ppaasssseedd iinn ffrroomm <>ppccaapp__ddiissppaattcchh(())<>,, aa <>ccoonnsstt ssttrruucctt ppccaapp__ppkktthhddrr<> ppooiinntteerr ttoo aa ssttrruuccttuurree wwiitthh tthhee ffoolllloowwiinngg mmeemmbbeerrss:: <> <> <>ttss<> <> aa <>ssttrruucctt ttiimmeevvaall<> ccoonnttaaiinniinngg tthhee ttiimmee wwhheenn tthhee ppaacckkeett wwaass ccaappttuurreedd <> <>ccaapplleenn<> <> aa <>bbppff__uu__iinntt3322<> ggiivviinngg tthhee nnuummbbeerr ooff bbyytteess ooff tthhee ppaacckkeett tthhaatt aarree aavvaaiillaabbllee ffrroomm tthhee ccaappttuurree <> <>lleenn<> <> aa <>bbppff__uu__iinntt3322<> ggiivviinngg tthhee lleennggtthh ooff tthhee ppaacckkeett,, iinn bbyytteess ((wwhhiicchh mmiigghhtt bbee mmoorree tthhaann tthhee nnuummbbeerr ooff bbyytteess aavvaaiillaabbllee ffrroomm tthhee ccaappttuurree,, iiff tthhee lleennggtthh ooff tthhee ppaacckkeett iiss llaarrggeerr tthhaann tthhee mmaaxxiimmuumm nnuummbbeerr ooff bbyytteess ttoo ccaappttuurree)) <> <> aanndd aa <>ccoonnsstt uu__cchhaarr<> ppooiinntteerr ttoo tthhee ffiirrsstt <>ccaapplleenn<> ((aass ggiivveenn iinn tthhee <>ssttrruucctt ppccaapp__ppkktthhddrr<> aa ppooiinntteerr ttoo wwhhiicchh iiss ppaasssseedd ttoo tthhee ccaallllbbaacckk rroouuttiinnee)) bbyytteess ooff ddaattaa ffrroomm tthhee ppaacckkeett ((wwhhiicchh wwoonn''tt nneecceessssaarriillyy bbee tthhee eennttiirree ppaacckkeett;; ttoo ccaappttuurree tthhee eennttiirree ppaacckkeett,, yyoouu wwiillll hhaavvee ttoo pprroovviiddee aa vvaalluuee ffoorr <>ssnnaapplleenn<> iinn yyoouurr ccaallll ttoo <>ppccaapp__ooppeenn__lliivvee(())<> tthhaatt iiss ssuuffffiicciieennttllyy llaarrggee ttoo ggeett aallll ooff tthhee ppaacckkeett''ss ddaattaa -- aa vvaalluuee ooff 6655553355 sshhoouulldd bbee ssuuffffiicciieenntt oonn mmoosstt iiff nnoott aallll nneettwwoorrkkss)).. <> TThhee nnuummbbeerr ooff ppaacckkeettss rreeaadd iiss rreettuurrnneedd.. 00 iiss rreettuurrnneedd iiff nnoo ppaacckkeettss wweerree rreeaadd ffrroomm aa lliivvee ccaappttuurree ((iiff,, ffoorr eexxaammppllee,, tthheeyy wweerree ddiissccaarrddeedd bbeeccaauussee tthheeyy ddiiddnn''tt ppaassss tthhee ppaacckkeett ffiilltteerr,, oorr iiff,, oonn ppllaattffoorrmmss tthhaatt ssuuppppoorrtt aa rreeaadd ttiimmeeoouutt tthhaatt ssttaarrttss bbeeffoorree aannyy ppaacckkeettss aarrrriivvee,, tthhee ttiimmeeoouutt eexxppiirreess bbeeffoorree aannyy ppaacckkeettss aarrrriivvee,, oorr iiff tthhee ffiillee ddeessccrriippttoorr ffoorr tthhee ccaappttuurree ddeevviiccee iiss iinn nnoonn--bblloocckkiinngg mmooddee aanndd nnoo ppaacckkeettss wweerree aavvaaiillaabbllee ttoo bbee rreeaadd)) oorr iiff nnoo mmoorree ppaacckkeettss aarree aavvaaiillaabbllee iinn aa ````ssaavveeffiillee..'''' AA rreettuurrnn ooff --11 iinnddiiccaatteess aann eerrrroorr iinn wwhhiicchh ccaassee <>ppccaapp__ppeerrrroorr(())<> oorr <>ppccaapp__ggeetteerrrr(())<> mmaayy bbee uusseedd ttoo ddiissppllaayy tthhee eerrrroorr tteexxtt.. AA rreettuurrnn ooff --22 iinnddiiccaatteess tthhaatt tthhee lloooopp tteerrmmiinnaatteedd dduuee ttoo aa ccaallll ttoo <>ppccaapp__bbrreeaakklloooopp(())<> bbeeffoorree aannyy ppaacckkeettss wweerree pprroocceesssseedd.. IIff yyoouurr aapppplliiccaattiioonn uusseess ppccaapp__bbrreeaakklloooopp(()),, mmaakkee ssuurree tthhaatt yyoouu eexxpplliicciittllyy cchheecckk ffoorr --11 aanndd --22,, rraatthheerr tthhaann jjuusstt cchheecckkiinngg ffoorr aa rreettuurrnn vvaalluuee << 00..

NOTE: when reading a live capture, pcap_dispatch() will not necessarily return when the read times out; on some platforms, the read timeout isn't supported, and, on other platforms, the timer doesn't start until at least one packet arrives. This means that the read timeout should NOT be used in, for example, an interactive application, to allow the packet capture loop to ``poll'' for user input periodically, as there's no guarantee that pcap_dispatch() will return after the timeout expires.

pcap_loop() is similar to pcap_dispatch() except it keeps reading packets until cnt packets are processed or an error occurs. It does not return when live read timeouts occur. Rather, specifying a non-zero read timeout to pcap_open_live() and then calling pcap_dispatch() allows the reception and processing of any packets that arrive when the timeout occurs. A negative cnt causes pcap_loop() to loop forever (or at least until an error occurs). -1 is returned on an error; 0 is returned if cnt is exhausted; -2 is returned if the loop terminated due to a call to pcap_breakloop() before any packets were processed. IIff yyoouurr aapppplliiccaattiioonn uusseess ppccaapp__bbrreeaakklloooopp(()),, mmaakkee ssuurree tthhaatt yyoouu eexxpplliicciittllyy cchheecckk ffoorr --11 aanndd --22,, rraatthheerr tthhaann jjuusstt cchheecckkiinngg ffoorr aa rreettuurrnn vvaalluuee << 00..

pcap_next() reads the next packet (by calling pcap_dispatch() with a cnt of 1) and returns a u_char pointer to the data in that packet. (The pcap_pkthdr struct for that packet is not supplied.) NULL is returned if an error occured, or if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a read timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read), or if no more packets are available in a ``savefile.'' Unfortunately, there is no way to determine whether an error occured or not.

pcap_next_ex() reads the next packet and returns a success/failure indication:

1
the packet was read without problems
0
packets are being read from a live capture, and the timeout expired
-1
an error occurred while reading the packet
-2
packets are being read from a ``savefile'', and there are no more packets to read from the savefile.

If the packet was read without problems, the pointer pointed to by the pkt_header argument is set to point to the pcap_pkthdr struct for the packet, and the pointer pointed to by the pkt_data argument is set to point to the data in the packet.

pcap_breakloop() sets a flag that will force pcap_dispatch() or pcap_loop() to return rather than looping; they will return the number of packets that have been processed so far, or -2 if no packets have been processed so far.

This routine is safe to use inside a signal handler on UNIX or a console control handler on Windows, as it merely sets a flag that is checked within the loop.

The flag is checked in loops reading packets from the OS - a signal by itself will not necessarily terminate those loops - as well as in loops processing a set of packets returned by the OS. NNoottee tthhaatt iiff yyoouu aarree ccaattcchhiinngg ssiiggnnaallss oonn UUNNIIXX ssyysstteemmss tthhaatt ssuuppppoorrtt rreessttaarrttiinngg ssyysstteemm ccaallllss aafftteerr aa ssiiggnnaall,, aanndd ccaalllliinngg ppccaapp__bbrreeaakklloooopp(()) iinn tthhee ssiiggnnaall hhaannddlleerr,, yyoouu mmuusstt ssppeecciiffyy,, wwhheenn ccaattcchhiinngg tthhoossee ssiiggnnaallss,, tthhaatt ssyysstteemm ccaallllss sshhoouulldd NNOOTT bbee rreessttaarrtteedd bbyy tthhaatt ssiiggnnaall.. OOtthheerrwwiissee,, iiff tthhee ssiiggnnaall iinntteerrrruupptteedd aa ccaallll rreeaaddiinngg ppaacckkeettss iinn aa lliivvee ccaappttuurree,, wwhheenn yyoouurr ssiiggnnaall hhaannddlleerr rreettuurrnnss aafftteerr ccaalllliinngg ppccaapp__bbrreeaakklloooopp(()),, tthhee ccaallll wwiillll bbee rreessttaarrtteedd,, aanndd tthhee lloooopp wwiillll nnoott tteerrmmiinnaattee uunnttiill mmoorree ppaacckkeettss aarrrriivvee aanndd tthhee ccaallll ccoommpplleetteess.. <> NNoottee aallssoo tthhaatt,, iinn aa mmuullttii--tthhrreeaaddeedd aapppplliiccaattiioonn,, iiff oonnee tthhrreeaadd iiss bblloocckkeedd iinn <>ppccaapp__ddiissppaattcchh(())<>,, <>ppccaapp__lloooopp(())<>,, <>ppccaapp__nneexxtt(())<>,, oorr <>ppccaapp__nneexxtt__eexx(())<>,, aa ccaallll ttoo <>ppccaapp__bbrreeaakklloooopp(())<> iinn aa ddiiffffeerreenntt tthhrreeaadd wwiillll nnoott uunnbblloocckk tthhaatt tthhrreeaadd;; yyoouu wwiillll nneeeedd ttoo uussee wwhhaatteevveerr mmeecchhaanniissmm tthhee OOSS pprroovviiddeess ffoorr bbrreeaakkiinngg aa tthhrreeaadd oouutt ooff bblloocckkiinngg ccaallllss iinn oorrddeerr ttoo uunnbblloocckk tthhee tthhrreeaadd,, ssuucchh aass tthhrreeaadd ccaanncceellllaattiioonn iinn ssyysstteemmss tthhaatt ssuuppppoorrtt PPOOSSIIXX tthhrreeaaddss..

Note that pcap_next() will, on some platforms, loop reading packets from the OS; that loop will not necessarily be terminated by a signal, so pcap_breakloop() should be used to terminate packet processing even if pcap_next() is being used.

pcap_breakloop() does not guarantee that no further packets will be processed by pcap_dispatch() or pcap_loop() after it is called; at most one more packet might be processed.

If -2 is returned from pcap_dispatch() or pcap_loop(), the flag is cleared, so a subsequent call will resume reading packets. If a positive number is returned, the flag is not cleared, so a subsequent call will return -2 and clear the flag.

pcap_inject() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. It returns the number of bytes written on success. A return of -1 indicates an error in which case pcap_perror() or pcap_geterr() may be used to display the error text. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live() doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_inject(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

pcap_sendpacket() is like pcap_inject(), but it returns 0 on success and -1 on failure. comes from OpenBSD; pcap_sendpacket() comes from WinPcap. Both are provided for compatibility.)

pcap_dump() outputs a packet to the ``savefile'' opened with pcap_dump_open(). Note that its calling arguments are suitable for use with pcap_dispatch() or pcap_loop(). If called directly, the user parameter is of type pcap_dumper_t as returned by pcap_dump_open().

pcap_compile() is used to compile the string str into a filter program. program is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting code is performed. netmask specifies the IPv4 netmask of the network on which packets are being captured; it is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of 0 can be supplied; tests for IPv4 broadcast addreses won't be done correctly, but all other tests in the filter program will be OK. A return of -1 indicates an error in which case pcap_geterr() may be used to display the error text.

pcap_compile_nopcap() is similar to pcap_compile() except that instead of passing a pcap structure, one passes the snaplen and linktype explicitly. It is intended to be used for compiling filters for direct BPF usage, without necessarily having called pcap_open(). A return of -1 indicates an error; the error text is unavailable. is a wrapper around pcap_open_dead(), pcap_compile(), and pcap_close(); the latter three routines can be used directly in order to get the error text for a compilation error.)

pcap_setfilter() is used to specify a filter program. fp is a pointer to a bpf_program struct, usually the result of a call to pcap_compile(). -1 is returned on failure, in which case pcap_geterr() may be used to display the error text; 0 is returned on success.

pcap_freecode() is used to free up allocated memory pointed to by a bpf_program struct generated by pcap_compile() when that BPF program is no longer needed, for example after it has been made the filter program for a pcap structure by a call to pcap_setfilter().

pcap_setdirection() is used to specify a direction that packets will be captured. pcap_direction_t is one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT. PCAP_D_IN will only capture packets received by the device, PCAP_D_OUT will only capture packets sent by the device and PCAP_D_INOUT will capture packets received by or sent by the device. PCAP_D_INOUT is the default setting if this function is not called. This isn't necessarily supported on all platforms; some platforms might return an error, and some other platforms might not support PCAP_D_OUT. This operation is not supported if a ``savefile'' is being read. -1 is returned on failure, 0 is returned on success.

pcap_datalink() returns the link layer type; link layer types it can return include:

DLT_NULL
BSD loopback encapsulation; the link layer header is a 4-byte field, in host byte order, containing a PF_ value from socket.h for the network-layer protocol of the packet.
Note that ``host byte order'' is the byte order of the machine on which
the packets are captured, and the PF_ values are for the OS of the machine on which the packets are captured; if a live capture is being done, ``host byte order'' is the byte order of the machine capturing the packets, and the PF_ values are those of the OS of the machine capturing the packets, but if a ``savefile'' is being read, the byte order and PF_ values are not necessarily those of the machine reading the capture file.
DLT_EN10MB
Ethernet (10Mb, 100Mb, 1000Mb, and up)
DLT_IEEE802
IEEE 802.5 Token Ring
DLT_ARCNET
ARCNET
DLT_SLIP
SLIP; the link layer header contains, in order:

a 1-byte flag, which is 0 for packets received by the machine and 1 for packets sent by the machine;

a 1-byte field, the upper 4 bits of which indicate the type of packet, as per RFC 1144:

0x40
an unmodified IP datagram (TYPE_IP);
0x70
an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being the first byte of the raw IP header on the wire, containing the connection number in the protocol field;
0x80
a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the first byte of the compressed TCP/IP datagram header;

for UNCOMPRESSED_TCP, the rest of the modified IP header, and for COMPRESSED_TCP, the compressed TCP/IP datagram header;

for a total of 16 bytes; the uncompressed IP datagram follows the header.

DLT_PPP
PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like framing, with the PPP header following those two bytes, otherwise it's PPP without framing, and the packet begins with the PPP header.
DLT_FDDI
FDDI
DLT_ATM_RFC1483
RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2 LLC header.
DLT_RAW
raw IP; the packet begins with an IP header.
DLT_PPP_SERIAL
PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP with HDLC framing.
DLT_PPP_ETHER
PPPoE; the packet begins with a PPPoE header, as per RFC 2516.
DLT_C_HDLC
Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547.
DLT_IEEE802_11
IEEE 802.11 wireless LAN
DLT_FRELAY
Frame Relay
DLT_LOOP
OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in network byte order, containing a PF_ value from OpenBSD's socket.h for the network-layer protocol of the packet.
Note that, if a ``savefile'' is being read, those PF_ values are
not necessarily those of the machine reading the capture file.
DLT_LINUX_SLL
Linux "cooked" capture encapsulation; the link layer header contains, in order:

a 2-byte "packet type", in network byte order, which is one of:

0
packet was sent to us by somebody else
1
packet was broadcast by somebody else
2
packet was multicast, but not broadcast, by somebody else
3
packet was sent by somebody else to somebody else
4
packet was sent by us

a 2-byte field, in network byte order, containing a Linux ARPHRD_ value for the link layer device type;

a 2-byte field, in network byte order, containing the length of the link layer address of the sender of the packet (which could be 0);

an 8-byte field containing that number of bytes of the link layer header (if there are more than 8 bytes, only the first 8 are present);

a 2-byte field containing an Ethernet protocol type, in network byte order, or containing 1 for Novell 802.3 frames without an 802.2 LLC header or 4 for frames beginning with an 802.2 LLC header.

DLT_LTALK
Apple LocalTalk; the packet begins with an AppleTalk LLAP header.
DLT_PFLOG
OpenBSD pflog; the link layer header contains, in order:

a 1-byte header length, in host byte order;

a 4-byte PF_ value, in host byte order;

a 2-byte action code, in network byte order, which is one of:

0
passed
1
dropped
2
scrubbed

a 2-byte reason code, in network byte order, which is one of:

0
match
1
bad offset
2
fragment
3
short
4
normalize
5
memory

a 16-character interface name;

a 16-character ruleset name (only meaningful if subrule is set);

a 4-byte rule number, in network byte order;

a 4-byte subrule number, in network byte order;

a 1-byte direction, in network byte order, which is one of:

0
incoming or outgoing
1
incoming
2
outgoing
DLT_PRISM_HEADER
Prism monitor mode information followed by an 802.11 header.
DLT_IP_OVER_FC
RFC 2625 IP-over-Fibre Channel, with the link-layer header being the Network_Header as described in that RFC.
DLT_SUNATM
SunATM devices; the link layer header contains, in order:

a 1-byte flag field, containing a direction flag in the uppermost bit, which is set for packets transmitted by the machine and clear for packets received by the machine, and a 4-byte traffic type in the low-order 4 bits, which is one of:

0
raw traffic
1
LANE traffic
2
LLC-encapsulated traffic
3
MARS traffic
4
IFMP traffic
5
ILMI traffic
6
Q.2931 traffic

a 1-byte VPI value;

a 2-byte VCI field, in network byte order.

DLT_IEEE802_11_RADIO
link-layer information followed by an 802.11 header - see http://www.shaftnet.org/~pizza/software/capturefrm.txt for a description of the link-layer information.
DLT_ARCNET_LINUX
ARCNET, with no exception frames, reassembled packets rather than raw frames, and an extra 16-bit offset field between the destination host and type bytes.
DLT_LINUX_IRDA
Linux-IrDA packets, with a DLT_LINUX_SLL header followed by the IrLAP header.

pcap_list_datalinks() is used to get a list of the supported data link types of the interface associated with the pcap descriptor. pcap_list_datalinks() allocates an array to hold the list and sets *dlt_buf. The caller is responsible for freeing the array. -1 is returned on failure; otherwise, the number of data link types in the array is returned.

pcap_set_datalink() is used to set the current data link type of the pcap descriptor to the type specified by dlt. -1 is returned on failure.

pcap_datalink_name_to_val() translates a data link type name, which is a DLT_ name with the DLT_ removed, to the corresponding data link type value. The translation is case-insensitive. -1 is returned on failure.

pcap_datalink_val_to_name() translates a data link type value to the corresponding data link type name. NULL is returned on failure.

pcap_datalink_val_to_description() translates a data link type value to a short description of that data link type. NULL is returned on failure.

pcap_snapshot() returns the snapshot length specified when pcap_open_live() was called.

pcap_is_swapped() returns true if the current ``savefile'' uses a different byte order than the current system.

pcap_major_version() returns the major number of the file format of the savefile; pcap_minor_version() returns the minor number of the file format of the savefile. The version number is stored in the header of the savefile.

pcap_file() returns the standard I/O stream of the ``savefile,'' if a ``savefile'' was opened with pcap_open_offline(), or NULL, if a network device was opened with pcap_open_live().

pcap_stats() returns 0 and fills in a pcap_stat struct. The values represent packet statistics from the start of the run to the time of the call. If there is an error or the underlying packet capture doesn't support packet statistics, -1 is returned and the error text can be obtained with pcap_perror() or pcap_geterr(). pcap_stats() is supported only on live captures, not on ``savefiles''; no statistics are stored in ``savefiles'', so no statistics are available when reading from a ``savefile''.

pcap_fileno() returns the file descriptor number from which captured packets are read, if a network device was opened with pcap_open_live(), or -1, if a ``savefile'' was opened with pcap_open_offline().

pcap_get_selectable_fd() returns, on UNIX, a file descriptor number for a file descriptor on which one can do a select() or poll() to wait for it to be possible to read packets without blocking, if such a descriptor exists, or -1, if no such descriptor exists. Some network devices opened with pcap_open_live() do not support select() or poll() (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace DAG devices), so -1 is returned for those devices.

Note that on most versions of most BSDs (including Mac OS X) select() and poll() do not work correctly on BPF devices; pcap_get_selectable_fd() will return a file descriptor on most of those versions (the exceptions being FreeBSD 4.3 and 4.4), a simple select() or poll() will not return even after a timeout specified in pcap_open_live() expires. To work around this, an application that uses select() or poll() to wait for packets to arrive must put the pcap_t in non-blocking mode, and must arrange that the select() or poll() have a timeout less than or equal to the timeout specified in pcap_open_live(), and must try to read packets after that timeout expires, regardless of whether select() or poll() indicated that the file descriptor for the pcap_t is ready to be read or not. (That workaround will not work in FreeBSD 4.3 and later; however, in FreeBSD 4.6 and later, select() and poll() work correctly on BPF devices, so the workaround isn't necessary, although it does no harm.)

pcap_get_selectable_fd() is not available on Windows.

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

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_strerror() is provided in case strerror(1) isn't available.

pcap_lib_version() returns a pointer to a string giving information about the version of the libpcap library being used; note that it contains more information than just a version number.

pcap_close() closes the files associated with p and deallocates resources.

pcap_dump_file() returns the standard I/O stream of the ``savefile'' opened by pcap_dump_open().

pcap_dump_flush() flushes the output buffer to the ``savefile,'' so that any packets written with pcap_dump() but not yet written to the ``savefile'' will be written. -1 is returned on error, 0 on success.

pcap_dump_ftell() returns the current file position for the ``savefile'', representing the number of bytes written by pcap_dump_open() and pcap_dump(). -1 is returned on error.

pcap_dump_close() closes the ``savefile.''

SEE ALSO

tcpdump(1), tcpslice(1)

AUTHORS

The original authors are:

Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.

The current version is available from "The Tcpdump Group"'s Web site at

http://www.tcpdump.org/

BUGS

Please send problems, bugs, questions, desirable enhancements, etc. to:

tcpdump-workers@tcpdump.org

Please send source code contributions, etc. to:

patches@tcpdump.org