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 "24 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 of the network on which packets are being
  50 captured; it is used only when checking for IPv4 broadcast addresses in
  51 the filter program.  If the netmask of the network on which packets are
  52 being captured isn't known to the program, or if packets are being
  53 captured on the Linux "any" pseudo-interface that can capture on more
  54 than one network, a value of
  55 .B PCAP_NETMASK_UNKNOWN
  56 can be supplied; tests
  57 for IPv4 broadcast addresses will fail to compile, but all other tests in
  58 the filter program will be OK.
  59 .PP
  60 On Linux, if the
  61 .B pcap_t
  62 handle corresponds to a live packet capture, the resulting filter program
  63 may use Linux BPF extensions.  This works transparently if the filter
  64 program is used to filter packets on the same
  65 .B pcap_t
  66 handle, which should be done when possible.  In other use cases trying to
  67 use a filter program with BPF extensions in
  68 .BR \%pcap_offline_filter (3PCAP)
  69 or for filtering an input savefile would reject more packets than expected
  70 because the extensions depend on auxiliary packet data, which would not be
  71 available.  The workaround is to compile the filter without the extensions
  72 by using a
  73 .B pcap_t
  74 handle from
  75 .BR \%pcap_open_dead (3PCAP)
  76 or
  77 .BR \%pcap_open_offline (3PCAP)
  78 rather than a handle from
  79 .BR \%pcap_create (3PCAP)
  80 or
  81 .BR \%pcap_open_live (3PCAP).
  82 .PP
  83 If BPF extensions are disabled as described above or the OS is not Linux,
  84 .BR pcap_compile ()
  85 may start rejecting some filter expressions for some link-layer header types,
  86 this is the expected behaviour.  For example, the
  87 .B ifindex
  88 keyword is valid for any live capture on Linux, but when reading packets
  89 from a savefile, regardless of the OS it is valid for
  90 .B DLT_LINUX_SLL2
  91 only.
  92 .SH RETURN VALUE
  93 .BR pcap_compile ()
  94 returns
  95 .B 0
  96 on success and
  97 .B PCAP_ERROR
  98 on failure. If
  99 .B PCAP_ERROR
 100 is returned,
 101 .BR pcap_geterr (3PCAP)
 102 or
 103 .BR pcap_perror (3PCAP)
 104 may be called with
 105 .I p
 106 as an argument to fetch or display the error text.
 107 .SH BACKWARD COMPATIBILITY
 108 .PP
 109 The
 110 .B PCAP_NETMASK_UNKNOWN
 111 constant became available in libpcap release 1.1.0.
 112 .PP
 113 In libpcap 1.8.0 and later,
 114 .BR pcap_compile ()
 115 can be used in multiple threads within a single process.  However, in
 116 earlier versions of libpcap, it is
 117 .I not
 118 safe to use
 119 .BR pcap_compile ()
 120 in multiple threads in a single process without some form of mutual
 121 exclusion allowing only one thread to call it at any given time.
 122 .SH SEE ALSO
 123 .BR pcap (3PCAP),
 124 .BR pcap_setfilter (3PCAP),
 125 .BR pcap_freecode (3PCAP)