contrib/libpcap/pcap_stats.3pcap

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_stats.3pcap,v 1.3 2008-04-06 02:53:22 guy Exp $
   2 .\"
   3 .\" Copyright (c) 1994, 1996, 1997
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that: (1) source code distributions
   8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   9 .\" distributions including binary code include the above copyright notice and
  10 .\" this paragraph in its entirety in the documentation or other materials
  11 .\" provided with the distribution, and (3) all advertising materials mentioning
  12 .\" features or use of this software display the following acknowledgement:
  13 .\" ``This product includes software developed by the University of California,
  14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  15 .\" the University nor the names of its contributors may be used to endorse
  16 .\" or promote products derived from this software without specific prior
  17 .\" written permission.
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  21 .\"
  22 .TH PCAP_STATS 3PCAP "7 September 2009"
  23 .SH NAME
  24 pcap_stats \- get capture statistics
  25 .SH SYNOPSIS
  26 .nf
  27 .ft B
  28 #include <pcap/pcap.h>
  29 .ft
  30 .LP
  31 .ft B
  32 int pcap_stats(pcap_t *p, struct pcap_stat *ps);
  33 .ft
  34 .fi
  35 .SH DESCRIPTION
  36 .B pcap_stats()
  37 fills in the
  38 .B struct pcap_stat
  39 pointed to by its second argument.  The values represent
  40 packet statistics from the start of the run to the time of the call.
  41 .PP
  42 .B pcap_stats()
  43 is supported only on live captures, not on ``savefiles''; no statistics
  44 are stored in ``savefiles'', so no statistics are available when reading
  45 from a ``savefile''.
  46 .PP
  47 A
  48 .B struct pcap_stat
  49 has the following members:
  50 .RS
  51 .TP
  52 .B ps_recv
  53 number of packets received;
  54 .TP
  55 .B ps_drop
  56 number of packets dropped because there was no room in the operating
  57 system's buffer when they arrived, because packets weren't being read
  58 fast enough;
  59 .TP
  60 .B ps_ifdrop
  61 number of packets dropped by the network interface or its driver.
  62 .RE
  63 .PP
  64 The statistics do not behave the same way on all platforms.
  65 .B ps_recv
  66 might count packets whether they passed any filter set with
  67 .BR pcap_setfilter (3PCAP)
  68 or not, or it might count only packets that pass the filter.
  69 It also might, or might not, count packets dropped because there was no
  70 room in the operating system's buffer when they arrived.
  71 .B ps_drop
  72 is not available on all platforms; it is zero on platforms where it's
  73 not available.  If packet filtering is done in libpcap, rather than in
  74 the operating system, it would count packets that don't pass the filter.
  75 Both
  76 .B ps_recv
  77 and
  78 .B ps_drop
  79 might, or might not, count packets not yet read from the operating
  80 system and thus not yet seen by the application.
  81 .B ps_ifdrop
  82 might, or might not, be implemented; if it's zero, that might mean that
  83 no packets were dropped by the interface, or it might mean that the
  84 statistic is unavailable, so it should not be treated as an indication
  85 that the interface did not drop any packets.
  86 .SH RETURN VALUE
  87 .B pcap_stats()
  88 returns 0 on success and returns \-1 if there is an error or if
  89 .I p
  90 doesn't support packet statistics.
  91 If \-1 is returned,
  92 .B pcap_geterr()
  93 or
  94 .B pcap_perror()
  95 may be called with
  96 .I p
  97 as an argument to fetch or display the error text.
  98 .SH SEE ALSO
  99 pcap(3PCAP), pcap_geterr(3PCAP)