The Tcpdump Group git mirrors - libpcap/blob - pcap_open_live.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_OPEN_LIVE 3PCAP "11 March 2025"
  21 .SH NAME
  22 pcap_open_live \- open a device for capturing
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .nf
  30 .ft B
  31 char errbuf[PCAP_ERRBUF_SIZE];
  32 .ft
  33 .LP
  34 .ft B
  35 pcap_t *pcap_open_live(const char *device, int snaplen,
  36     int promisc, int to_ms, char *errbuf);
  37 .ft
  38 .fi
  39 .SH DESCRIPTION
  40 .BR pcap_open_live ()
  41 is used to obtain a packet capture handle to capture packets on a device
  42 (typically a network interface, see
  43 .BR \%pcap_findalldevs (3PCAP)
  44 for a more detailed explanation).
  45 .I device
  46 is a string that specifies the capture device to open, in this function
  47 .B NULL
  48 means the same as the string "any".
  49 .PP
  50 .I snaplen
  51 specifies the snapshot length to be set on the handle.  If the packet
  52 data should not be truncated at the end, a value of 262144 should be
  53 sufficient for most devices, but D-Bus devices require a value of 128MiB
  54 (128*1024*1024).
  55 .PP
  56 .I promisc
  57 specifies whether the device is to be put into promiscuous mode.
  58 If
  59 .I promisc
  60 is non-zero, promiscuous mode will be set, otherwise it will not be set.
  61 .PP
  62 .I to_ms
  63 specifies the packet buffer timeout, as a non-negative value, in
  64 milliseconds.  (See
  65 .BR pcap (3PCAP)
  66 for an explanation of the packet buffer timeout.)
  67 .PP
  68 .I errbuf
  69 is a buffer large enough to hold at least
  70 .B PCAP_ERRBUF_SIZE
  71 chars.
  72 .SH RETURN VALUE
  73 .BR pcap_open_live ()
  74 returns a
  75 .B pcap_t *
  76 on success and
  77 .B NULL
  78 on failure.
  79 If
  80 .B NULL
  81 is returned,
  82 .I errbuf
  83 is filled in with an appropriate error message.
  84 .I errbuf
  85 may also be set to warning text when
  86 .BR pcap_open_live ()
  87 succeeds; to detect this case the caller should store a zero-length string in
  88 .I errbuf
  89 before calling
  90 .BR pcap_open_live ()
  91 and display the warning to the user if
  92 .I errbuf
  93 is no longer a zero-length string.
  94 .SH SEE ALSO
  95 .BR pcap_create (3PCAP),
  96 .BR pcap_activate (3PCAP)