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 "20 January 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 .B 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 if the interface is to be put into promiscuous mode.
  57 .PP
  58 .I to_ms
  59 specifies the packet buffer timeout, as a non-negative value, in
  60 milliseconds.  (See
  61 .BR pcap (3PCAP)
  62 for an explanation of the packet buffer timeout.)
  63 .SH RETURN VALUE
  64 .B pcap_open_live()
  65 returns a
  66 .I pcap_t *
  67 on success and
  68 .B NULL
  69 on failure.
  70 If
  71 .B NULL
  72 is returned,
  73 .I errbuf
  74 is filled in with an appropriate error message.
  75 .I errbuf
  76 may also be set to warning text when
  77 .B pcap_open_live()
  78 succeeds; to detect this case the caller should store a zero-length string in
  79 .I errbuf
  80 before calling
  81 .B pcap_open_live()
  82 and display the warning to the user if
  83 .I errbuf
  84 is no longer a zero-length string.
  85 .I errbuf
  86 is assumed to be able to hold at least
  87 .B PCAP_ERRBUF_SIZE
  88 chars.
  89 .SH SEE ALSO
  90 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP)