##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))
< >
< >
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
iiss uusseedd ttoo oobbttaaiinn aa ppaacckkeett ccaappttuurree ddeessccrriippttoorr ttoo llooookk
aatt ppaacckkeettss oonn tthhee nneettwwoorrkk..
<>ddeevviiccee</ii>>
iiss aa ssttrriinngg tthhaatt ssppeecciiffiieess tthhee nneettwwoorrkk ddeevviiccee ttoo ooppeenn;; oonn LLiinnuuxx ssyysstteemmss
wwiitthh 22..22 oorr llaatteerr kkeerrnneellss,, aa
<>ddeevviiccee</ii>>
aarrgguummeenntt ooff ""aannyy"" oorr
<>NNUULLLL</bb>>
ccaann bbee uusseedd ttoo ccaappttuurree ppaacckkeettss ffrroomm aallll iinntteerrffaacceess..
<>ssnnaapplleenn</ii>>
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</ii>>
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</ii>>
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</ii>>
ffllaagg iiss iiggnnoorreedd..
<>ttoo__mmss</ii>>
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</ii>>,,
oonn ppllaattffoorrmmss tthhaatt ssuuppppoorrtt aa rreeaadd ttiimmeeoouutt,,
wwiillll ccaauussee aa rreeaadd ttoo wwaaiitt ffoorreevveerr ttoo aallllooww eennoouugghh ppaacckkeettss ttoo
aarrrriivvee,, wwiitthh nnoo ttiimmeeoouutt..
<>eerrrrbbuuff</ii>>
iiss uusseedd ttoo rreettuurrnn eerrrroorr oorr wwaarrnniinngg tteexxtt.. IItt wwiillll bbee sseett ttoo eerrrroorr tteexxtt wwhheenn
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
ffaaiillss aanndd rreettuurrnnss
<>NNUULLLL</bb>>..
<>eerrrrbbuuff</ii>>
mmaayy aallssoo bbee sseett ttoo wwaarrnniinngg tteexxtt wwhheenn
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
ssuucccceeddss;; ttoo ddeetteecctt tthhiiss ccaassee tthhee ccaalllleerr sshhoouulldd ssttoorree aa zzeerroo--lleennggtthh ssttrriinngg iinn
<>eerrrrbbuuff</ii>>
bbeeffoorree ccaalllliinngg
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
aanndd ddiissppllaayy tthhee wwaarrnniinngg ttoo tthhee uusseerr iiff
<>eerrrrbbuuff</ii>>
iiss nnoo lloonnggeerr aa zzeerroo--lleennggtthh ssttrriinngg..
< >
<>ppccaapp__ooppeenn__ddeeaadd(())</bb>>
iiss uusseedd ffoorr ccrreeaattiinngg aa
<>ppccaapp__tt</bb>>
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(())</bb>>
iiss ccaalllleedd ttoo ooppeenn aa ````ssaavveeffiillee'''' ffoorr rreeaaddiinngg..
<>ffnnaammee</ii>>
ssppeecciiffiieess tthhee nnaammee ooff tthhee ffiillee ttoo ooppeenn.. TThhee ffiillee hhaass
tthhee ssaammee ffoorrmmaatt aass tthhoossee uusseedd bbyy
<>ttccppdduummpp((11))</bb>>
aanndd
<>ttccppsslliiccee((11))</bb>>..
TThhee nnaammee ""--"" iinn aa ssyynnoonnyymm ffoorr
<>ssttddiinn</bb>>..
AAlltteerrnnaattiivveellyy,, yyoouu mmaayy ccaallll
<>ppccaapp__ffooppeenn__oofffflliinnee(())</bb>>
ttoo rreeaadd dduummppeedd ddaattaa ffrroomm aann eexxiissttiinngg ooppeenn ssttrreeaamm
<>ffpp</ii>>..
NNoottee tthhaatt oonn WWiinnddoowwss,, tthhaatt ssttrreeaamm sshhoouulldd bbee ooppeenneedd iinn bbiinnaarryy mmooddee..
<>eerrrrbbuuff</ii>>
iiss uusseedd ttoo rreettuurrnn eerrrroorr tteexxtt aanndd iiss oonnllyy sseett wwhheenn
<>ppccaapp__ooppeenn__oofffflliinnee(())</bb>>
oorr
<>ppccaapp__ffooppeenn__oofffflliinnee(())</bb>>
ffaaiillss aanndd rreettuurrnnss
<>NNUULLLL</bb>>..
< >
<>ppccaapp__dduummpp__ooppeenn(())</bb>>
iiss ccaalllleedd ttoo ooppeenn aa ````ssaavveeffiillee'''' ffoorr wwrriittiinngg.. TThhee nnaammee ""--"" iinn aa ssyynnoonnyymm
ffoorr
<>ssttddoouutt</bb>>..
<>NNUULLLL</bb>>
iiss rreettuurrnneedd oonn ffaaiilluurree..
<>pp</ii>>
iiss aa
<>ppccaapp</ii>>
ssttrruucctt aass rreettuurrnneedd bbyy
<>ppccaapp__ooppeenn__oofffflliinnee(())</bb>>
oorr
<>ppccaapp__ooppeenn__lliivvee(())</bb>>..
<>ffnnaammee</ii>>
ssppeecciiffiieess tthhee nnaammee ooff tthhee ffiillee ttoo ooppeenn.. AAlltteerrnnaattiivveellyy,, yyoouu mmaayy ccaallll
<>ppccaapp__dduummpp__ffooppeenn(())</bb>>
ttoo wwrriittee ddaattaa ttoo aann eexxiissttiinngg ooppeenn ssttrreeaamm
<>ffpp</ii>>..
NNoottee tthhaatt oonn WWiinnddoowwss,, tthhaatt ssttrreeaamm sshhoouulldd bbee ooppeenneedd iinn bbiinnaarryy mmooddee..
IIff
<>NNUULLLL</bb>>
iiss rreettuurrnneedd,,
<>ppccaapp__ggeetteerrrr(())</bb>>
ccaann bbee uusseedd ttoo ggeett tthhee eerrrroorr tteexxtt..
< >
< >
<>ppccaapp__sseettnnoonnbblloocckk(())</bb>>
ppuuttss aa ccaappttuurree ddeessccrriippttoorr,, ooppeenneedd wwiitthh
<>ppccaapp__ooppeenn__lliivvee(())</bb>>,,
iinnttoo ````nnoonn--bblloocckkiinngg'''' mmooddee,, oorr ttaakkeess iitt oouutt ooff ````nnoonn--bblloocckkiinngg'''' mmooddee,,
ddeeppeennddiinngg oonn wwhheetthheerr tthhee
<>nnoonnbblloocckk</ii>>
aarrgguummeenntt iiss nnoonn--zzeerroo oorr zzeerroo.. IItt hhaass nnoo eeffffeecctt oonn ````ssaavveeffiilleess''''..
IIff tthheerree iiss aann eerrrroorr,, --11 iiss rreettuurrnneedd aanndd
<>eerrrrbbuuff</ii>>
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(())</bb>>
wwiillll,, iiff nnoo ppaacckkeettss aarree ccuurrrreennttllyy aavvaaiillaabbllee ttoo bbee rreeaadd,, rreettuurrnn 00
iimmmmeeddiiaatteellyy rraatthheerr tthhaann bblloocckkiinngg wwaaiittiinngg ffoorr ppaacckkeettss ttoo aarrrriivvee..
<>ppccaapp__lloooopp(())</bb>>
aanndd
<>ppccaapp__nneexxtt(())</bb>>
wwiillll nnoott wwoorrkk iinn ````nnoonn--bblloocckkiinngg'''' mmooddee..
< >
<>ppccaapp__ggeettnnoonnbblloocckk(())</bb>>
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</ii>>
iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee..
< >
<>ppccaapp__ffiinnddaallllddeevvss(())</bb>>
ccoonnssttrruuccttss aa lliisstt ooff nneettwwoorrkk ddeevviicceess tthhaatt ccaann bbee ooppeenneedd wwiitthh
<>ppccaapp__ooppeenn__lliivvee(())</bb>>..
((NNoottee tthhaatt tthheerree mmaayy bbee nneettwwoorrkk ddeevviicceess tthhaatt ccaannnnoott bbee ooppeenneedd wwiitthh
ppccaapp__ooppeenn__lliivvee(())
bbyy tthhee
pprroocceessss ccaalllliinngg
<>ppccaapp__ffiinnddaallllddeevvss(())</bb>>,,
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</ii>>
iiss sseett ttoo ppooiinntt ttoo tthhee ffiirrsstt eelleemmeenntt ooff tthhee lliisstt;; eeaacchh eelleemmeenntt ooff tthhee
lliisstt iiss ooff ttyyppee
<>ppccaapp__iiff__tt</bb>>,,
aanndd hhaass tthhee ffoolllloowwiinngg mmeemmbbeerrss::
< >
EEaacchh eelleemmeenntt ooff tthhee lliisstt ooff aaddddrreesssseess iiss ooff ttyyppee
<>ppccaapp__aaddddrr__tt</bb>>,,
aanndd hhaass tthhee ffoolllloowwiinngg mmeemmbbeerrss::
< >
NNoottee tthhaatt nnoott aallll tthhee aaddddrreesssseess iinn tthhee lliisstt ooff aaddddrreesssseess aarree
nneecceessssaarriillyy IIPPvv44 oorr IIPPvv66 aaddddrreesssseess -- yyoouu mmuusstt cchheecckk tthhee
<>ssaa__ffaammiillyy</bb>>
mmeemmbbeerr ooff tthhee
<>ssttrruucctt ssoocckkaaddddrr</bb>>
bbeeffoorree iinntteerrpprreettiinngg tthhee ccoonntteennttss ooff tthhee aaddddrreessss..
< >
<>--11</bb>>
iiss rreettuurrnneedd oonn ffaaiilluurree,, iinn wwhhiicchh ccaassee
<>eerrrrbbuuff</bb>>
iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee;;
<>00</bb>>
iiss rreettuurrnneedd oonn ssuucccceessss..
< >
<>ppccaapp__ffrreeeeaallllddeevvss(())</bb>>
iiss uusseedd ttoo ffrreeee aa lliisstt aallllooccaatteedd bbyy
<>ppccaapp__ffiinnddaallllddeevvss(())</bb>>..
< >
<>ppccaapp__llooookkuuppddeevv(())</bb>>
rreettuurrnnss aa ppooiinntteerr ttoo aa nneettwwoorrkk ddeevviiccee ssuuiittaabbllee ffoorr uussee wwiitthh
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
aanndd
<>ppccaapp__llooookkuuppnneett(())</bb>>..
IIff tthheerree iiss aann eerrrroorr,,
<>NNUULLLL</bb>>
iiss rreettuurrnneedd aanndd
<>eerrrrbbuuff</ii>>
iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee..
< >
<>ppccaapp__llooookkuuppnneett(())</bb>>
iiss uusseedd ttoo ddeetteerrmmiinnee tthhee nneettwwoorrkk nnuummbbeerr aanndd mmaasskk
aassssoocciiaatteedd wwiitthh tthhee nneettwwoorrkk ddeevviiccee
<>ddeevviiccee</bb>>..
BBootthh
<>nneettpp</ii>>
aanndd
<>mmaasskkpp</ii>>
aarree
<>bbppff__uu__iinntt3322</ii>>
ppooiinntteerrss..
AA rreettuurrnn ooff --11 iinnddiiccaatteess aann eerrrroorr iinn wwhhiicchh ccaassee
<>eerrrrbbuuff</ii>>
iiss ffiilllleedd iinn wwiitthh aann aapppprroopprriiaattee eerrrroorr mmeessssaaggee..
< >
<>ppccaapp__ddiissppaattcchh(())</bb>>
iiss uusseedd ttoo ccoolllleecctt aanndd pprroocceessss ppaacckkeettss..
<>ccnntt</ii>>
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</ii>>
ppaacckkeettss mmaayy bbee pprroocceesssseedd.. AA
<>ccnntt</ii>>
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</ii>>
ssppeecciiffiieess aa rroouuttiinnee ttoo bbee ccaalllleedd wwiitthh tthhrreeee aarrgguummeennttss::
aa
<>uu__cchhaarr</ii>>
ppooiinntteerr wwhhiicchh iiss ppaasssseedd iinn ffrroomm
<>ppccaapp__ddiissppaattcchh(())</bb>>,,
aa
<>ccoonnsstt ssttrruucctt ppccaapp__ppkktthhddrr</ii>>
ppooiinntteerr ttoo aa ssttrruuccttuurree wwiitthh tthhee ffoolllloowwiinngg mmeemmbbeerrss::
< >
aanndd aa
<>ccoonnsstt uu__cchhaarr</ii>>
ppooiinntteerr ttoo tthhee ffiirrsstt
<>ccaapplleenn</bb>>
((aass ggiivveenn iinn tthhee
<>ssttrruucctt ppccaapp__ppkktthhddrr</ii>>
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</ii>>
iinn yyoouurr ccaallll ttoo
<>ppccaapp__ooppeenn__lliivvee(())</bb>>
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(())</bb>>
oorr
<>ppccaapp__ggeetteerrrr(())</bb>>
mmaayy bbee uusseedd ttoo ddiissppllaayy tthhee eerrrroorr tteexxtt..
AA rreettuurrnn ooff --22 iinnddiiccaatteess tthhaatt tthhee lloooopp tteerrmmiinnaatteedd dduuee ttoo aa ccaallll ttoo
<>ppccaapp__bbrreeaakklloooopp(())</bb>>
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:
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(())</bb>>,,
<>ppccaapp__lloooopp(())</bb>>,,
<>ppccaapp__nneexxtt(())</bb>>,,
oorr
<>ppccaapp__nneexxtt__eexx(())</bb>>,,
aa ccaallll ttoo
<>ppccaapp__bbrreeaakklloooopp(())</bb>>
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_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:
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:
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.
a 2-byte "packet type", in network byte order, which is one of:
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.
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:
a 2-byte reason code, in network byte order, which is one of:
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:
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:
a 1-byte VPI value;
a 2-byte VCI field, in network byte order.
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.''
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/
tcpdump-workers@tcpdump.org
Please send source code contributions, etc. to:
patches@tcpdump.org
SEE ALSO
tcpdump(1), tcpslice(1)
AUTHORS
The original authors are:
BUGS
Please send problems, bugs, questions, desirable enhancements, etc. to: