1PCAP_NEXT_EX(3PCAP)                                        PCAP_NEXT_EX(3PCAP)
2
3
4

NAME

6       pcap_next_ex, pcap_next - read the next packet from a pcap_t
7

SYNOPSIS

9       #include <pcap/pcap.h>
10
11       int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
12               const u_char **pkt_data);
13       const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h);
14

DESCRIPTION

16       pcap_next_ex()  reads  the  next  packet  and returns a success/failure
17       indication.  If the packet  was  read  without  problems,  the  pointer
18       pointed  to  by  the  pkt_header  argument  is  set  to  point  to  the
19       pcap_pkthdr struct for the packet, and the pointer pointed  to  by  the
20       pkt_data  argument  is  set  to  point  to the data in the packet.  The
21       struct pcap_pkthdr and the packet data are not to be freed by the call‐
22       er,  and  are  not  guaranteed  to  be  valid  after  the  next call to
23       pcap_next_ex(), pcap_next(), pcap_loop(3PCAP), or pcap_dispatch(3PCAP);
24       if the code needs them to remain valid, it must make a copy of them.
25
26       pcap_next()  reads  the  next packet (by calling pcap_dispatch() with a
27       cnt of 1) and returns a u_char pointer to the data in that packet.  The
28       packet  data is not to be freed by the caller, and is not guaranteed to
29       be  valid  after  the  next  call   to   pcap_next_ex(),   pcap_next(),
30       pcap_loop(),  or pcap_dispatch(); if the code needs it to remain valid,
31       it must make a copy of it.  The pcap_pkthdr structure pointed to  by  h
32       is filled in with the appropriate values for the packet.
33
34       The  bytes of data from the packet begin with a link-layer header.  The
35       format of the link-layer header is indicated by the return value of the
36       pcap_datalink(PCAP) routine when handed the pcap_t value also passed to
37       pcap_loop() or pcap_dispatch().  https://www.tcpdump.org/linktypes.html
38       lists  the  values  pcap_datalink() can return and describes the packet
39       formats that correspond to those values.  The value it returns will  be
40       valid     for     all     packets    received    unless    and    until
41       pcap_set_datalink(3PCAP)  is  called;  after  a  successful   call   to
42       pcap_set_datalink(),  all  subsequent  packets  will  have a link-layer
43       header of the type specified by the link-layer header type value passed
44       to pcap_set_datalink().
45
46       Do NOT assume that the packets for a given capture or ``savefile`` will
47       have any given link-layer header type, such as DLT_EN10MB for Ethernet.
48       For  example,  the  "any" device on Linux will have a link-layer header
49       type of DLT_LINUX_SLL even if all devices on the system at the time the
50       "any"  device  is  opened  have  some  other  data  link  type, such as
51       DLT_EN10MB for Ethernet.
52

RETURN VALUE

54       pcap_next_ex() returns 1 if the packet was read without problems, 0  if
55       packets  are being read from a live capture and the packet buffer time‐
56       out expired, PCAP_ERROR if an error occurred while reading the  packet,
57       and  PCAP_ERROR_BREAK if packets are being read from a ``savefile'' and
58       there are no more packets to read from the savefile.  If PCAP_ERROR  is
59       returned, pcap_geterr(3PCAP) or pcap_perror(3PCAP) may be called with p
60       as an argument to fetch or display the error text.
61
62       pcap_next() returns a pointer  to  the  packet  data  on  success,  and
63       returns  NULL  if  an error occurred, or if no packets were read from a
64       live capture (if, for example, they were discarded because they  didn't
65       pass  the packet filter, or if, on platforms that support a packet buf‐
66       fer timeout that starts before any packets arrive, the timeout  expires
67       before  any  packets  arrive, or if the file descriptor for the capture
68       device is in non-blocking mode and no  packets  were  available  to  be
69       read),  or if no more packets are available in a ``savefile.'' Unfortu‐
70       nately, there is no way to determine whether an error occurred or not.
71

SEE ALSO

73       pcap(3PCAP)
74
75
76
77                                 25 July 2018              PCAP_NEXT_EX(3PCAP)
Impressum