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 "3 January 2014"
  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 read timeout in milliseconds.
  60 .SH RETURN VALUE
  61 .B pcap_open_live()
  62 returns a
  63 .I pcap_t *
  64 on success and
  65 .B NULL
  66 on failure.
  67 If
  68 .B NULL
  69 is returned,
  70 .I errbuf
  71 is filled in with an appropriate error message.
  72 .I errbuf
  73 may also be set to warning text when
  74 .B pcap_open_live()
  75 succeeds; to detect this case the caller should store a zero-length string in
  76 .I errbuf
  77 before calling
  78 .B pcap_open_live()
  79 and display the warning to the user if
  80 .I errbuf
  81 is no longer a zero-length string.
  82 .I errbuf
  83 is assumed to be able to hold at least
  84 .B PCAP_ERRBUF_SIZE
  85 chars.
  86 .SH SEE ALSO
  87 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP)