JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | .\" Copyright (c) 1994, 1996, 1997 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that: (1) source code distributions |
| 6 | .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| 7 | .\" distributions including binary code include the above copyright notice and |
| 8 | .\" this paragraph in its entirety in the documentation or other materials |
| 9 | .\" provided with the distribution, and (3) all advertising materials mentioning |
| 10 | .\" features or use of this software display the following acknowledgement: |
| 11 | .\" ``This product includes software developed by the University of California, |
| 12 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| 13 | .\" the University nor the names of its contributors may be used to endorse |
| 14 | .\" or promote products derived from this software without specific prior |
| 15 | .\" written permission. |
| 16 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| 17 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 18 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 19 | .\" |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 20 | .TH PCAP_NEXT_EX 3PCAP "20 January 2017" |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 21 | .SH NAME |
| 22 | pcap_next_ex, pcap_next \- read the next packet from a pcap_t |
| 23 | .SH SYNOPSIS |
| 24 | .nf |
| 25 | .ft B |
| 26 | #include <pcap/pcap.h> |
| 27 | .ft |
| 28 | .LP |
| 29 | .ft B |
| 30 | int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header, |
| 31 | .ti +8 |
| 32 | const u_char **pkt_data); |
| 33 | const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h); |
| 34 | .ft |
| 35 | .fi |
| 36 | .SH DESCRIPTION |
| 37 | .B pcap_next_ex() |
| 38 | reads the next packet and returns a success/failure indication. |
| 39 | If the packet was read without problems, the pointer pointed to by the |
| 40 | .I pkt_header |
| 41 | argument is set to point to the |
| 42 | .I pcap_pkthdr |
| 43 | struct for the packet, and the |
| 44 | pointer pointed to by the |
| 45 | .I pkt_data |
| 46 | argument is set to point to the data in the packet. The |
| 47 | .I struct pcap_pkthdr |
| 48 | and the packet data are not to be freed by the caller, and are not |
| 49 | guaranteed to be valid after the next call to |
| 50 | .BR pcap_next_ex() , |
| 51 | .BR pcap_next() , |
| 52 | .BR pcap_loop() , |
| 53 | or |
| 54 | .BR pcap_dispatch() ; |
| 55 | if the code needs them to remain valid, it must make a copy of them. |
| 56 | .PP |
| 57 | .B pcap_next() |
| 58 | reads the next packet (by calling |
| 59 | .B pcap_dispatch() |
| 60 | with a |
| 61 | .I cnt |
| 62 | of 1) and returns a |
| 63 | .I u_char |
| 64 | pointer to the data in that packet. The |
| 65 | packet data is not to be freed by the caller, and is not |
| 66 | guaranteed to be valid after the next call to |
| 67 | .BR pcap_next_ex() , |
| 68 | .BR pcap_next() , |
| 69 | .BR pcap_loop() , |
| 70 | or |
| 71 | .BR pcap_dispatch() ; |
| 72 | if the code needs it to remain valid, it must make a copy of it. |
| 73 | The |
| 74 | .I pcap_pkthdr |
| 75 | structure pointed to by |
| 76 | .I h |
| 77 | is filled in with the appropriate values for the packet. |
| 78 | .PP |
| 79 | The bytes of data from the packet begin with a link-layer header. The |
| 80 | format of the link-layer header is indicated by the return value of the |
| 81 | .B pcap_datalink() |
| 82 | routine when handed the |
| 83 | .B pcap_t |
| 84 | value also passed to |
| 85 | .B pcap_loop() |
| 86 | or |
| 87 | .BR pcap_dispatch() . |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 88 | .I https://www.tcpdump.org/linktypes.html |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 89 | lists the values |
| 90 | .B pcap_datalink() |
| 91 | can return and describes the packet formats that |
| 92 | correspond to those values. The value it returns will be valid for all |
| 93 | packets received unless and until |
| 94 | .B pcap_set_datalink() |
| 95 | is called; after a successful call to |
| 96 | .BR pcap_set_datalink() , |
| 97 | all subsequent packets will have a link-layer header of the type |
| 98 | specified by the link-layer header type value passed to |
| 99 | .BR pcap_set_datalink() . |
| 100 | .PP |
| 101 | Do |
| 102 | .B NOT |
| 103 | assume that the packets for a given capture or ``savefile`` will have |
| 104 | any given link-layer header type, such as |
| 105 | .B DLT_EN10MB |
| 106 | for Ethernet. For example, the "any" device on Linux will have a |
| 107 | link-layer header type of |
| 108 | .B DLT_LINUX_SLL |
| 109 | even if all devices on the system at the time the "any" device is opened |
| 110 | have some other data link type, such as |
| 111 | .B DLT_EN10MB |
| 112 | for Ethernet. |
| 113 | .SH RETURN VALUE |
| 114 | .B pcap_next_ex() |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 115 | returns 1 if the packet was read without problems, 0 if packets are |
| 116 | being read from a live capture and the packet buffer timeout expired, |
| 117 | \-1 if an error occurred while reading the packet, and \-2 if packets |
| 118 | are being read from a ``savefile'' and there are no more packets to read |
| 119 | from the savefile. If \-1 is returned, |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 120 | .B pcap_geterr() |
| 121 | or |
| 122 | .B pcap_perror() |
| 123 | may be called with |
| 124 | .I p |
| 125 | as an argument to fetch or display the error text. |
| 126 | .PP |
| 127 | .B pcap_next() |
| 128 | returns a pointer to the packet data on success, and returns |
| 129 | .B NULL |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 130 | if an error occurred, or if no packets were read from a live capture |
| 131 | (if, for example, they were discarded because they didn't pass the |
| 132 | packet filter, or if, on platforms that support a packet buffer timeout |
| 133 | that starts before any packets arrive, the timeout expires before any |
| 134 | packets arrive, or if the file descriptor for the capture device is in |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 135 | non-blocking mode and no packets were available to be read), or if no |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 136 | more packets are available in a ``savefile.'' Unfortunately, there is no |
| 137 | way to determine whether an error occurred or not. |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 138 | .SH SEE ALSO |
| 139 | pcap(3PCAP), pcap_geterr(3PCAP), pcap_dispatch(3PCAP), |
| 140 | pcap_datalink(3PCAP) |