contrib/libpcap/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 "6 December 2017"
  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 .ti +8
  37 int promisc, int to_ms, char *errbuf);
  38 .ft
  39 .fi
  40 .SH DESCRIPTION
  41 .BR pcap_open_live ()
  42 is used to obtain a packet capture handle to look
  43 at packets on the network.
  44 .I device
  45 is a string that specifies the network device to open; on Linux systems
  46 with 2.2 or later kernels, a
  47 .I device
  48 argument of "any" or
  49 .B NULL
  50 can be used to capture packets from all interfaces.
  51 .PP
  52 .I snaplen
  53 specifies the snapshot length to be set on the handle.
  54 .PP
  55 .I promisc
  56 specifies whether the interface is to be put into promiscuous mode.
  57 If
  58 .I promisc
  59 is non-zero, promiscuous mode will be set, otherwise it will not be set.
  60 .PP
  61 .I to_ms
  62 specifies the packet buffer timeout, as a non-negative value, in
  63 milliseconds.  (See
  64 .BR pcap (3PCAP)
  65 for an explanation of the packet buffer timeout.)
  66 .SH RETURN VALUE
  67 .BR pcap_open_live ()
  68 returns a
  69 .I pcap_t *
  70 on success and
  71 .B NULL
  72 on failure.
  73 If
  74 .B NULL
  75 is returned,
  76 .I errbuf
  77 is filled in with an appropriate error message.
  78 .I errbuf
  79 may also be set to warning text when
  80 .BR pcap_open_live ()
  81 succeeds; to detect this case the caller should store a zero-length string in
  82 .I errbuf
  83 before calling
  84 .BR pcap_open_live ()
  85 and display the warning to the user if
  86 .I errbuf
  87 is no longer a zero-length string.
  88 .I errbuf
  89 is assumed to be able to hold at least
  90 .B PCAP_ERRBUF_SIZE
  91 chars.
  92 .SH SEE ALSO
  93 .BR pcap_create (3PCAP),
  94 .BR pcap_activate (3PCAP)