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

   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_COMPILE 3PCAP "31 January 2025"
  21 .SH NAME
  22 pcap_compile \- compile a filter expression
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .ft B
  30 int pcap_compile(pcap_t *p, struct bpf_program *fp,
  31     const char *str, int optimize, bpf_u_int32 netmask);
  32 .ft
  33 .fi
  34 .SH DESCRIPTION
  35 .BR pcap_compile ()
  36 is used to compile the string
  37 .I str
  38 into a filter program.  See
  39 .BR \%pcap-filter (@MAN_MISC_INFO@)
  40 for the syntax of that string.
  41 .I fp
  42 is a pointer to a
  43 .I bpf_program
  44 struct and is filled in by
  45 .BR pcap_compile ().
  46 .I optimize
  47 controls whether optimization on the resulting code is performed.
  48 .I netmask
  49 specifies the IPv4 netmask (in host byte order) of the network on which
  50 packets are being
  51 captured; it is used only when checking for IPv4 broadcast addresses in
  52 the filter program.  If the netmask of the network on which packets are
  53 being captured isn't known to the program, or if packets are being
  54 captured on the Linux "any" pseudo-interface that can capture on more
  55 than one network, a value of
  56 .B PCAP_NETMASK_UNKNOWN
  57 can be supplied; tests
  58 for IPv4 broadcast addresses will fail to compile, but all other tests in
  59 the filter program will be OK.
  60 .PP
  61 On Linux, if the
  62 .B pcap_t
  63 handle corresponds to a live packet capture, the resulting filter program
  64 may use Linux BPF extensions.  This works transparently if the filter
  65 program is used to filter packets on the same
  66 .B pcap_t
  67 handle, which should be done when possible.  In other use cases trying to
  68 use a filter program with BPF extensions in
  69 .BR \%pcap_offline_filter (3PCAP)
  70 or for filtering an input savefile would reject more packets than expected
  71 because the extensions depend on auxiliary packet data, which would not be
  72 available.  The workaround is to compile the filter without the extensions
  73 by using a
  74 .B pcap_t
  75 handle from
  76 .BR \%pcap_open_dead (3PCAP)
  77 or
  78 .BR \%pcap_open_offline (3PCAP)
  79 rather than a handle from
  80 .BR \%pcap_create (3PCAP)
  81 or
  82 .BR \%pcap_open_live (3PCAP).
  83 .PP
  84 If BPF extensions are disabled as described above or the OS is not Linux,
  85 .BR pcap_compile ()
  86 may start rejecting some filter expressions for some link-layer header types,
  87 this is the expected behaviour.  For example, the
  88 .B ifindex
  89 keyword is valid for any live capture on Linux, but when reading packets
  90 from a savefile, regardless of the OS it is valid for
  91 .B DLT_LINUX_SLL2
  92 only.
  93 .SH RETURN VALUE
  94 .BR pcap_compile ()
  95 returns
  96 .B 0
  97 on success and
  98 .B PCAP_ERROR
  99 on failure. If
 100 .B PCAP_ERROR
 101 is returned,
 102 .BR pcap_geterr (3PCAP)
 103 or
 104 .BR pcap_perror (3PCAP)
 105 may be called with
 106 .I p
 107 as an argument to fetch or display the error text.
 108 .SH BACKWARD COMPATIBILITY
 109 .PP
 110 The
 111 .B PCAP_NETMASK_UNKNOWN
 112 constant became available in libpcap release 1.1.0.
 113 .PP
 114 In libpcap 1.8.0 and later,
 115 .BR pcap_compile ()
 116 can be used in multiple threads within a single process.  However, in
 117 earlier versions of libpcap, it is
 118 .I not
 119 safe to use
 120 .BR pcap_compile ()
 121 in multiple threads in a single process without some form of mutual
 122 exclusion allowing only one thread to call it at any given time.
 123 .SH SEE ALSO
 124 .BR pcap (3PCAP),
 125 .BR pcap_setfilter (3PCAP),
 126 .BR pcap_freecode (3PCAP)