The Tcpdump Group git mirrors - libpcap/blob - pcap_stats.3pcap

   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 .\"
  20 .TH PCAP_STATS 3PCAP "5 March 2022"
  21 .SH NAME
  22 pcap_stats \- get capture statistics
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .ft B
  30 int pcap_stats(pcap_t *p, struct pcap_stat *ps);
  31 .ft
  32 .fi
  33 .SH DESCRIPTION
  34 .BR pcap_stats ()
  35 fills in the
  36 .B struct pcap_stat
  37 pointed to by its second argument.  The values represent
  38 packet statistics from the start of the run to the time of the call.
  39 .PP
  40 .BR pcap_stats ()
  41 is supported only on live captures, not on ``savefiles''; no statistics
  42 are stored in ``savefiles'', so no statistics are available when reading
  43 from a ``savefile''.
  44 .PP
  45 A
  46 .B struct pcap_stat
  47 has the following members:
  48 .RS
  49 .TP
  50 .B ps_recv
  51 number of packets received;
  52 .TP
  53 .B ps_drop
  54 number of packets dropped because there was no room in the operating
  55 system's buffer when they arrived, because packets weren't being read
  56 fast enough;
  57 .TP
  58 .B ps_ifdrop
  59 number of packets dropped by the network interface or its driver.
  60 .RE
  61 .PP
  62 The statistics do not behave the same way on all platforms.
  63 .B ps_recv
  64 might count packets whether they passed any filter set with
  65 .BR pcap_setfilter (3PCAP)
  66 or not, or it might count only packets that pass the filter.
  67 It also might, or might not, count packets dropped because there was no
  68 room in the operating system's buffer when they arrived.
  69 .B ps_drop
  70 is not available on all platforms; it is zero on platforms where it's
  71 not available.  If packet filtering is done in libpcap, rather than in
  72 the operating system, it would count packets that don't pass the filter.
  73 Both
  74 .B ps_recv
  75 and
  76 .B ps_drop
  77 might, or might not, count packets not yet read from the operating
  78 system and thus not yet seen by the application.
  79 .B ps_ifdrop
  80 might, or might not, be implemented; if it's zero, that might mean that
  81 no packets were dropped by the interface, or it might mean that the
  82 statistic is unavailable, so it should not be treated as an indication
  83 that the interface did not drop any packets.
  84 .SH RETURN VALUE
  85 .BR pcap_stats ()
  86 returns
  87 .B 0
  88 on success,
  89 .B PCAP_ERROR_NOT_ACTIVATED
  90 if called on a capture handle that has been created but not activated,
  91 or
  92 .B PCAP_ERROR
  93 if there is another error or if
  94 .I p
  95 doesn't support packet statistics. If
  96 .B PCAP_ERROR
  97 is returned,
  98 .BR pcap_geterr (3PCAP)
  99 or
 100 .BR pcap_perror (3PCAP)
 101 may be called with
 102 .I p
 103 as an argument to fetch or display the error text.
 104 .SH SEE ALSO
 105 .BR pcap (3PCAP)