pcap man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

PCAP(3)								       PCAP(3)

NAME
       pcap - Packet Capture library

SYNOPSIS
       #include <pcap.h>

       char errbuf[PCAP_ERRBUF_SIZE];

       pcap_t *pcap_open_live(char *device, int snaplen,
	       int promisc, int to_ms, char *errbuf)
       pcap_t *pcap_open_dead(int linktype, int snaplen)
       pcap_t *pcap_open_offline(char *fname, char *errbuf)
       pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)

       int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
       int pcap_getnonblock(pcap_t *p, char *errbuf);

       int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
       void pcap_freealldevs(pcap_if_t *)
       char *pcap_lookupdev(char *errbuf)
       int pcap_lookupnet(char *device, bpf_u_int32 *netp,
	       bpf_u_int32 *maskp, char *errbuf)

       int pcap_dispatch(pcap_t *p, int cnt,
	       pcap_handler callback, u_char *user)
       int pcap_loop(pcap_t *p, int cnt,
	       pcap_handler callback, u_char *user)
       void pcap_dump(u_char *user, struct pcap_pkthdr *h,
	       u_char *sp)

       int pcap_compile(pcap_t *p, struct bpf_program *fp,
	       char *str, int optimize, bpf_u_int32 netmask)
       int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
       void pcap_freecode(struct bpf_program *);

       u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)

       int pcap_datalink(pcap_t *p)
       int pcap_snapshot(pcap_t *p)
       int pcap_is_swapped(pcap_t *p)
       int pcap_major_version(pcap_t *p)
       int pcap_minor_version(pcap_t *p)
       int pcap_stats(pcap_t *p, struct pcap_stat *ps)
       FILE *pcap_file(pcap_t *p)
       int pcap_fileno(pcap_t *p)
       void pcap_perror(pcap_t *p, char *prefix)
       char *pcap_geterr(pcap_t *p)
       char *pcap_strerror(int error)

       void pcap_close(pcap_t *p)
       void pcap_dump_close(pcap_dumper_t *p)

DESCRIPTION
       The  Packet  Capture  library provides a high level interface to packet
       capture systems. All packets on the network, even  those	 destined  for
       other hosts, are accessible through this mechanism.

ROUTINES
       NOTE:  errbuf  in  pcap_open_live(),  pcap_open_dead(),	pcap_open_off‐
       line(),	pcap_setnonblock(),  pcap_getnonblock(),   pcap_findalldevs(),
       pcap_lookupdev(), and pcap_lookupnet() is assumed to be able to hold at
       least PCAP_ERRBUF_SIZE chars.

       pcap_open_live() is used to obtain a packet capture descriptor to  look
       at  packets on the network.  device is a string that specifies the net‐
       work device to open; on Linux systems with  2.2	or  later  kernels,  a
       device  argument	 of  "any" or NULL can be used to capture packets from
       all interfaces.	snaplen specifies the maximum number of bytes to  cap‐
       ture.  promisc specifies if the interface is to be put into promiscuous
       mode.  (Note that even if this parameter is false, the interface	 could
       well  be	 in  promiscuous  mode	for some other reason.)	 For now, this
       doesn't work on the "any" device; if an argument of "any"  or  NULL  is
       supplied,  the promisc flag is ignored.	to_ms specifies the read time‐
       out in milliseconds.  The read timeout is used to arrange that the read
       not  necessarily	 return immediately when a packet is seen, but that it
       wait for some amount of time to allow more packets  to  arrive  and  to
       read  multiple  packets	from  the OS kernel in one operation.  Not all
       platforms support a read timeout; on platforms  that  don't,  the  read
       timeout	is  ignored.   errbuf is used to return error or warning text.
       It will be set to error text when pcap_open_live()  fails  and  returns
       NULL.   errbuf  may  also  be set to warning text when pcap_open_live()
       succeds; to detect this case the	 caller	 should	 store	a  zero-length
       string  in errbuf before calling pcap_open_live() and display the warn‐
       ing to the user if errbuf is no longer a zero-length string.

       pcap_open_dead() is used for creating a pcap_t structure	 to  use  when
       calling the other functions in libpcap.	It is typically used when just
       using libpcap for compiling BPF code.

       pcap_open_offline() is called  to  open	a  ``savefile''	 for  reading.
       fname  specifies	 the  name  of the file to open. The file has the same
       format as those used by tcpdump(1) and tcpslice(1).  The name "-" in  a
       synonym for stdin.  errbuf is used to return error text and is only set
       when pcap_open_offline() fails and returns NULL.

       pcap_dump_open() is called to open a ``savefile'' for writing. The name
       "-" in a synonym for stdout.  NULL is returned on failure.  p is a pcap
       struct as returned by pcap_open_offline() or  pcap_open_live().	 fname
       specifies  the  name  of	 the  file  to	open.	If  NULL  is returned,
       pcap_geterr() can be used to get the error text.

       pcap_setnonblock()   puts   a   capture	 descriptor,	opened	  with
       pcap_open_live(), into ``non-blocking'' mode, or takes it out of ``non-
       blocking'' mode, depending on whether the nonblock argument is non-zero
       or  zero.  It has no effect on ``savefiles''.  If there is an error, -1
       is returned and errbuf is filled in with an appropriate error  message;
       otherwise, 0 is returned.  In ``non-blocking'' mode, an attempt to read
       from the capture descriptor with pcap_dispatch() will,  if  no  packets
       are  currently  available  to be read, return 0 immediately rather than
       blocking waiting for packets to arrive.	 pcap_loop()  and  pcap_next()
       will not work in ``non-blocking'' mode.

       pcap_getnonblock()  returns  the	 current ``non-blocking'' state of the
       capture descriptor; it always returns 0 on ``savefiles''.  If there  is
       an  error,  -1  is returned and errbuf is filled in with an appropriate
       error message.

       pcap_findalldevs() constructs a list of network	devices	 that  can  be
       opened  with pcap_open_live().  (Note that there may be network devices
       that cannot be opened with  pcap_open_live()  by	 the  process  calling
       pcap_findalldevs(),  because,  for example, that process might not have
       sufficient privileges to open them for capturing; if so, those  devices
       will  not  appear  on the list.)	 alldevsp is set to point to the first
       element of the list; each element of the list is of type pcap_if_t, and
       has the following members:

	      next   if	 not  NULL, a pointer to the next element in the list;
		     NULL for the last element of the list

	      name   a pointer to a string giving a name  for  the  device  to
		     pass to pcap_open_live()

	      description
		     if	 not  NULL, a pointer to a string giving a human-read‐
		     able description of the device

	      addresses
		     a pointer to the first element of a list of addresses for
		     the interface

	      flags  interface flags:

		     PCAP_IF_LOOPBACK
			    set if the interface is a loopback interface

       Each  element  of the list of addresses is of type pcap_addr_t, and has
       the following members:

	      next   if not NULL, a pointer to the next element in  the	 list;
		     NULL for the last element of the list

	      addr   a pointer to a struct sockaddr containing an address

	      netmask
		     if not NULL, a pointer to a struct sockaddr that contains
		     the netmask corresponding to the address  pointed	to  by
		     addr

	      broadaddr
		     if not NULL, a pointer to a struct sockaddr that contains
		     the  broadcast  address  corresponding  to	 the   address
		     pointed  to by addr; may be null if the interface doesn't
		     support broadcasts

	      dstaddr
		     if not NULL, a pointer to a struct sockaddr that contains
		     the  destination  address	corresponding  to  the address
		     pointed to by addr; may be null if the interface isn't  a
		     point-to-point interface

       pcap_freealldevs()  is  used  to	 free  a  list allocated by pcap_find‐
       alldevs().

       pcap_lookupdev() returns a pointer to a network device suitable for use
       with pcap_open_live() and pcap_lookupnet().  If there is an error, NULL
       is returned and errbuf is filled in with an appropriate error message.

       pcap_lookupnet() is used to determine the network number and mask asso‐
       ciated  with  the  network  device  device.   Both  netp	 and maskp are
       bpf_u_int32 pointers.  A return of -1 indicates an error in which  case
       errbuf is filled in with an appropriate error message.

       pcap_dispatch()	is used to collect and process packets.	 cnt specifies
       the maximum number of packets to process before returning.  This is not
       a  minimum  number;  when reading a live capture, only one bufferful of
       packets is read at a time, so fewer than cnt packets may be  processed.
       A cnt of -1 processes all the packets received in one buffer when read‐
       ing a live capture, or all the packets  in  the	file  when  reading  a
       ``savefile''.   callback	 specifies  a  routine to be called with three
       arguments: a u_char pointer which is passed in from pcap_dispatch(),  a
       pointer	to  the	 pcap_pkthdr  struct (which precede the actual network
       headers and data), and a u_char pointer to the packet data.

       The number of packets read is returned.	0 is returned  if  no  packets
       were  read  from	 a  live capture (if, for example, they were discarded
       because they didn't pass the packet filter, or if,  on  platforms  that
       support a read timeout that starts before any packets arrive, the time‐
       out expires before any packets arrive, or if the	 file  descriptor  for
       the  capture  device is in non-blocking mode and no packets were avail‐
       able to be read) or if no more packets are available in a ``savefile.''
       A  return  of  -1  indicates  an	 error	in which case pcap_perror() or
       pcap_geterr() may be used to display the error text.

       NOTE: when reading a live capture, pcap_dispatch() will not necessarily
       return  when  the  read	times out; on some platforms, the read timeout
       isn't supported, and, on other platforms, the timer doesn't start until
       at  least  one packet arrives.  This means that the read timeout should
       NOT be used in, for example, an interactive application, to  allow  the
       packet capture loop to ``poll'' for user input periodically, as there's
       no  guarantee  that  pcap_dispatch()  will  return  after  the  timeout
       expires.

       pcap_loop() is similar to pcap_dispatch() except it keeps reading pack‐
       ets until cnt packets are processed or an error occurs.	 It  does  not
       return  when  live  read timeouts occur.	 Rather, specifying a non-zero
       read timeout  to	 pcap_open_live()  and	then  calling  pcap_dispatch()
       allows the reception and processing of any packets that arrive when the
       timeout occurs.	A negative cnt causes pcap_loop() to loop forever  (or
       at least until an error occurs).

       pcap_next()  reads  the	next packet (by calling pcap_dispatch() with a
       cnt of 1) and returns a u_char pointer to  the  data  in	 that  packet.
       (The pcap_pkthdr struct for that packet is not supplied.)

       pcap_dump()   outputs   a   packet  to  the  ``savefile''  opened  with
       pcap_dump_open().  Note that its calling arguments are suitable for use
       with  pcap_dispatch()  or  pcap_loop().	 If  called directly, the user
       parameter is of type pcap_dumper_t as returned by pcap_dump_open().

       pcap_compile() is used to compile the string str into a filter program.
       program	is  a  pointer	to  a  bpf_program  struct and is filled in by
       pcap_compile().	optimize controls whether optimization on the  result‐
       ing code is performed.  netmask specifies the netmask of the local net.
       A return of -1 indicates an error in which case	pcap_geterr()  may  be
       used to display the error text.

       pcap_compile_nopcap()  is similar to pcap_compile() except that instead
       of passing a pcap  structure,  one  passes  the	snaplen	 and  linktype
       explicitly.  It is intended to be used for compiling filters for direct
       BPF usage, without necessarily having called pcap_open().  A return  of
       -1  indicates  an  error;  the  error  text is unavailable.  (pcap_com‐
       pile_nopcap() is a wrapper around pcap_open_dead(), pcap_compile(), and
       pcap_close();  the  latter three routines can be used directly in order
       to get the error text for a compilation error.)

       pcap_setfilter() is used to specify a filter program.  fp is a  pointer
       to  a  bpf_program  struct,  usually  the result of a call to pcap_com‐
       pile().	-1 is returned on failure, in which case pcap_geterr() may  be
       used to display the error text; 0 is returned on success.

       pcap_freecode()	is  used  to  free up allocated memory pointed to by a
       bpf_program struct generated by pcap_compile() when that BPF program is
       no longer needed, for example after it has been made the filter program
       for a pcap structure by a call to pcap_setfilter().

       pcap_datalink() returns the link layer type; link layer	types  it  can
       return include:

	    DLT_NULL
		 BSD loopback encapsulation; the link layer header is a 4-byte
		 field, in host	 byte  order,  containing  a  PF_  value  from
		 socket.h for the network-layer protocol of the packet

		 Note  that  ``host  byte  order''  is	the  byte order of the
		 machine on which the packets are captured, and the PF_ values
		 are  for  the OS of the machine on which the packets are cap‐
		 tured; if a live capture is being done, ``host	 byte  order''
		 is  the  byte order of the machine capturing the packets, and
		 the PF_ values are those of the OS of the  machine  capturing
		 the  packets,	but  if a ``savefile'' is being read, the byte
		 order and PF_ values are not necessarily those of the machine
		 reading the capture file.

	    DLT_EN10MB
		 Ethernet (10Mb, 100Mb, 1000Mb, and up)

	    DLT_IEEE802
		 IEEE 802.5 Token Ring

	    DLT_ARCNET
		 ARCNET

	    DLT_SLIP
		 SLIP; the link layer header contains, in order:

		      a	 1-byte	 flag,	which is 0 for packets received by the
		      machine and 1 for packets sent by the machine;

		      a 1-byte field, the upper 4 bits of which	 indicate  the
		      type of packet, as per RFC 1144:

			   0x40 an unmodified IP datagram (TYPE_IP);

			   0x70 an   uncompressed-TCP	IP   datagram  (UNCOM‐
				PRESSED_TCP), with that byte being  the	 first
				byte  of  the  raw IP header on the wire, con‐
				taining the connection number in the  protocol
				field;

			   0x80 a compressed-TCP IP datagram (COMPRESSED_TCP),
				with that byte being the  first	 byte  of  the
				compressed TCP/IP datagram header;

		      for  UNCOMPRESSED_TCP,  the  rest	 of  the  modified  IP
		      header, and for COMPRESSED_TCP,  the  compressed	TCP/IP
		      datagram header;

		 for a total of 16 bytes; the uncompressed IP datagram follows
		 the header

	    DLT_PPP
		 PPP; if the first 2 bytes are 0xff  and  0x03,	 it's  PPP  in
		 HDLC-like  framing,  with  the PPP header following those two
		 bytes, otherwise it's PPP without  framing,  and  the	packet
		 begins with the PPP header

	    DLT_FDDI
		 FDDI

	    DLT_ATM_RFC1483
		 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an
		 IEEE 802.2 LLC header

	    DLT_RAW
		 raw IP; the packet begins with an IP header

	    DLT_PPP_SERIAL
		 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP  with
		 HDLC  framing,	 as  per  section 4.3.1 of RFC 1547; the first
		 byte will be 0xFF for PPP in HDLC-like framing, and  will  be
		 0x0F or 0x8F for Cisco PPP with HDLC framing

	    DLT_PPP_ETHER
		 PPPoE; the packet begins with a PPPoE header, as per RFC 2516

	    DLT_C_HDLC
		 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547

	    DLT_IEEE802_11
		 IEEE 802.11 wireless LAN

	    DLT_LOOP
		 OpenBSD  loopback  encapsulation;  the link layer header is a
		 4-byte field, in network byte order, containing a  PF_	 value
		 from OpenBSD's socket.h for the network-layer protocol of the
		 packet

		 Note that, if a ``savefile'' is being read, those PF_	values
		 are  not necessarily those of the machine reading the capture
		 file.

	    DLT_LINUX_SLL
		 Linux "cooked" capture encapsulation; the link	 layer	header
		 contains, in order:

		      a	 2-byte "packet type", in network byte order, which is
		      one of:

			   0	packet was sent to us by somebody else

			   1	packet was broadcast by somebody else

			   2	packet was multicast, but  not	broadcast,  by
				somebody else

			   3	packet	was  sent by somebody else to somebody
				else

			   4	packet was sent by us

		      a 2-byte field, in  network  byte	 order,	 containing  a
		      Linux ARPHRD_ value for the link layer device type;

		      a	 2-byte	 field,	 in network byte order, containing the
		      length of the link layer address of the  sender  of  the
		      packet (which could be 0);

		      an  8-byte  field containing that number of bytes of the
		      link layer header (if there are more than 8 bytes,  only
		      the first 8 are present);

		      a	 2-byte field containing an Ethernet protocol type, in
		      network byte order, or containing	 1  for	 Novell	 802.3
		      frames  without  an  802.2  LLC  header  or 4 for frames
		      beginning with an 802.2 LLC header.

	    DLT_LTALK
		 Apple LocalTalk; the packet begins  with  an  AppleTalk  LLAP
		 header

       pcap_snapshot()	  returns   the	  snapshot   length   specified	  when
       pcap_open_live was called.

       pcap_is_swapped() returns true if the current ``savefile'' uses a  dif‐
       ferent byte order than the current system.

       pcap_major_version()  returns  the  major  number of the version of the
       pcap used to write the savefile.

       pcap_minor_version() returns the minor number of	 the  version  of  the
       pcap used to write the savefile.

       pcap_file()  returns  the standard I/O stream of the ``savefile,'' if a
       ``savefile'' was opened with pcap_open_offline(), or NULL, if a network
       device was opened with pcap_open_live().

       pcap_stats() returns 0 and fills in a pcap_stat struct. The values rep‐
       resent packet statistics from the start of the run to the time  of  the
       call.  If  there	 is  an error or the underlying packet capture doesn't
       support packet statistics, -1 is returned and the  error	 text  can  be
       obtained	 with  pcap_perror()  or  pcap_geterr().  pcap_stats() is sup‐
       ported only on live captures, not on ``savefiles''; no  statistics  are
       stored  in  ``savefiles'',  so no statistics are available when reading
       from a ``savefile''.

       pcap_fileno() returns the file descriptor number	 from  which  captured
       packets are read, if a network device was opened with pcap_open_live(),
       or -1, if a ``savefile'' was opened with pcap_open_offline().

       pcap_perror() prints the text of the last pcap library error on stderr,
       prefixed by prefix.

       pcap_geterr()  returns  the  error  text	 pertaining  to	 the last pcap
       library error.  NOTE: the pointer it returns will no longer point to  a
       valid error message string after the pcap_t passed to it is closed; you
       must use or copy the string before closing the pcap_t.

       pcap_strerror() is provided in case strerror(1) isn't available.

       pcap_close()  closes  the  files	 associated  with  p  and  deallocates
       resources.

       pcap_dump_close() closes the ``savefile.''

SEE ALSO
       tcpdump(1), tcpslice(1)

AUTHORS
       The original authors are:

       Van  Jacobson,  Craig  Leres  and  Steven  McCanne, all of the Lawrence
       Berkeley National Laboratory, University of California, Berkeley, CA.

       The current version is available from "The Tcpdump Group"'s Web site at

	      http://www.tcpdump.org/

BUGS
       Please send problems, bugs, questions, desirable enhancements, etc. to:

	      tcpdump-workers@tcpdump.org

       Please send source code contributions, etc. to:

	      patches@tcpdump.org

				3 January 2001			       PCAP(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net