contrib/libpcap/pcap_open_live.3pcap

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_open_live.3pcap,v 1.1.2.3 2008-04-06 03:21:56 guy Exp $
   2 .\"
   3 .\" Copyright (c) 1994, 1996, 1997
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that: (1) source code distributions
   8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   9 .\" distributions including binary code include the above copyright notice and
  10 .\" this paragraph in its entirety in the documentation or other materials
  11 .\" provided with the distribution, and (3) all advertising materials mentioning
  12 .\" features or use of this software display the following acknowledgement:
  13 .\" ``This product includes software developed by the University of California,
  14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  15 .\" the University nor the names of its contributors may be used to endorse
  16 .\" or promote products derived from this software without specific prior
  17 .\" written permission.
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  21 .\"
  22 .TH PCAP_OPEN_LIVE 3PCAP "5 April 2008"
  23 .SH NAME
  24 pcap_open_live \- open a device for capturing
  25 .SH SYNOPSIS
  26 .nf
  27 .ft B
  28 #include <pcap/pcap.h>
  29 .ft
  30 .LP
  31 .nf
  32 .ft B
  33 char errbuf[PCAP_ERRBUF_SIZE];
  34 .ft
  35 .LP
  36 .ft B
  37 pcap_t *pcap_open_live(const char *device, int snaplen,
  38 .ti +8
  39 int promisc, int to_ms, char *errbuf);
  40 .ft
  41 .fi
  42 .SH DESCRIPTION
  43 .B pcap_open_live()
  44 is used to obtain a packet capture handle to look
  45 at packets on the network.
  46 .I device
  47 is a string that specifies the network device to open; on Linux systems
  48 with 2.2 or later kernels, a
  49 .I device
  50 argument of "any" or
  51 .B NULL
  52 can be used to capture packets from all interfaces.
  53 .PP
  54 .I snaplen
  55 specifies the snapshot length to be set on the handle.
  56 .PP
  57 .I promisc
  58 specifies if the interface is to be put into promiscuous mode.
  59 .PP
  60 .I to_ms
  61 specifies the read timeout in milliseconds.
  62 .SH RETURN VALUE
  63 .B pcap_open_live()
  64 returns a
  65 .I pcap_t *
  66 on success and
  67 .B NULL
  68 on failure.
  69 If
  70 .B NULL
  71 is returned,
  72 .I errbuf
  73 is filled in with an appropriate error message.
  74 .I errbuf
  75 may also be set to warning text when
  76 .B pcap_open_live()
  77 succeds; to detect this case the caller should store a zero-length string in
  78 .I errbuf
  79 before calling
  80 .B pcap_open_live()
  81 and display the warning to the user if
  82 .I errbuf
  83 is no longer a zero-length string.
  84 .I errbuf
  85 is assumed to be able to hold at least
  86 .B PCAP_ERRBUF_SIZE
  87 chars.
  88 .SH SEE ALSO
  89 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP)