The Tcpdump Group git mirrors - libpcap/blob - pcap_activate.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_ACTIVATE 3PCAP "3 June 2024"
  21 .SH NAME
  22 pcap_activate \- activate a capture handle
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .ft B
  30 int pcap_activate(pcap_t *p);
  31 .ft
  32 .fi
  33 .SH DESCRIPTION
  34 .BR pcap_activate ()
  35 is used to activate a packet capture handle to look
  36 at packets on the network, with the options that were set on the handle
  37 being in effect.
  38 .SH RETURN VALUE
  39 .BR pcap_activate ()
  40 returns
  41 .B 0
  42 on success without warnings, a non-zero positive value on
  43 success with warnings, and a negative value on error.
  44 A non-zero return value indicates what warning or error condition
  45 occurred.
  46 .LP
  47 The possible warning values are:
  48 .TP
  49 .B PCAP_WARNING_PROMISC_NOTSUP
  50 Promiscuous mode was requested, but the capture source doesn't support
  51 promiscuous mode.
  52 .TP
  53 .B PCAP_WARNING_TSTAMP_TYPE_NOTSUP
  54 The time stamp type specified in a previous
  55 .BR pcap_set_tstamp_type (3PCAP)
  56 call isn't supported by the capture source (the time stamp type is
  57 left as the default),
  58 .TP
  59 .B PCAP_WARNING
  60 Another warning condition occurred;
  61 .BR pcap_geterr (3PCAP)
  62 or
  63 .BR pcap_perror (3PCAP)
  64 may be called with
  65 .I p
  66 as an argument to fetch or display a message describing the warning
  67 condition.
  68 .LP
  69 The possible error values are:
  70 .TP
  71 .B PCAP_ERROR_ACTIVATED
  72 The handle has already been activated.
  73 .TP
  74 .B PCAP_ERROR_NO_SUCH_DEVICE
  75 The capture source specified when the handle was created doesn't
  76 exist.
  77 .TP
  78 .B PCAP_ERROR_PERM_DENIED
  79 The process doesn't have permission to open the capture source.
  80 .TP
  81 .B PCAP_ERROR_PROMISC_PERM_DENIED
  82 The process has permission to open the capture source but doesn't
  83 have permission to put it into promiscuous mode.
  84 .TP
  85 .B PCAP_ERROR_RFMON_NOTSUP
  86 Monitor mode was specified but the capture source doesn't support
  87 monitor mode.
  88 .TP
  89 .B PCAP_ERROR_IFACE_NOT_UP
  90 The capture source device is not up.
  91 .TP
  92 .B PCAP_ERROR_CAPTURE_NOTSUP
  93 Packet capture is not supported on the capture source.
  94 .TP
  95 .B PCAP_ERROR
  96 Another error occurred.
  97 .BR pcap_geterr ()
  98 or
  99 .BR pcap_perror ()
 100 may be called with
 101 .I p
 102 as an argument to fetch or display a message describing the error.
 103 .LP
 104 If
 105 .BR PCAP_WARNING_PROMISC_NOTSUP ,
 106 .BR PCAP_ERROR_NO_SUCH_DEVICE ,
 107 .BR PCAP_ERROR_PERM_DENIED ,
 108 or
 109 .B PCAP_ERROR_CAPTURE_NOTSUP
 110 is returned,
 111 .BR pcap_geterr ()
 112 or
 113 .BR pcap_perror ()
 114 may be called with
 115 .I p
 116 as an argument to fetch or display an message giving additional details
 117 about the problem that might be useful for debugging the problem if it's
 118 unexpected.
 119 .LP
 120 Additional warning and error codes may be added in the future; a program
 121 should check for positive, negative, and zero return codes, and treat
 122 all positive return codes as warnings and all negative return
 123 codes as errors.
 124 .BR pcap_statustostr (3PCAP)
 125 can be called, with a warning or error code as an argument, to fetch a
 126 message describing the warning or error code.
 127 .LP
 128 If
 129 .BR pcap_activate ()
 130 fails, the
 131 .B pcap_t *
 132 is not closed and freed; it should be closed using
 133 .BR pcap_close (3PCAP).
 134 .SH SEE ALSO
 135 .BR pcap (3PCAP)