.\" #Id: ngrep.8,v 1.9 2001/12/31 22:07:02 jpr5 Exp #
.\" $Id: ngrep-lib.3,v 1.5 2002/01/02 03:30:48 mavetju Exp $
.\" 
.\" All content, except portions of the bpf filter explanation, are:
.\"
.\" Copyright (c) 2001  Jordan Ritter <jpr5@darkridge.com> 
.\"
.\" Modifications for ngrep-lib by Edwin Groothuis <edwin@mavetju.org>
.\"
.\" Please refer to the COPYRIGHT file for more information.  
.\"
.TH NGREP-LIB 3 "January 2002" Unix "User Manuals"

.SH NAME

ngrep-lib \- network grep library

.SH DESCRIPTION

The ngrep library is a front-end for accessing the Packet Capture
Library (libpcap) without going through the hassle of programming
the filters, making sure you pick the right size for the header
etc.

.SH USAGE

Needed include-files are:

\fB#include <pcap.h>\fR
.br
\fB#include <ngrep-lib.h>\fR
.br
\fB#include <sys/types.h>\fR
.br
\fB#include <sys/socket.h>\fR
.br
\fB#include <netinet/in.h>\fR
.br
\fB#include <netinet/in_systm.h>\fR
.br
\fB#include <netinet/ip.h>\fR
.br
\fB#include <netinet/tcp.h>\fR
.br
\fB#include <netinet/udp.h>\fR
.br
\fB#include <netinet/ip_icmp.h>\fR
.br
\fB#include <net/if_arp.h>\fR
.br
\fB#include <arpa/inet.h>\fR
.br


These are the functions to access the library:

\fBvoid ngrep_callback_arp(void *my_arp);
.br
\fBvoid ngrep_callback_ip(void *my_ip);
.br
\fBvoid ngrep_callback_tcp(void *my_tcp);
.br
\fBvoid ngrep_callback_udp(void *my_udp);
.br
\fBvoid ngrep_callback_icmp(void *my_icmp);
.br
\fBvoid ngrep_callback_process(void *my_ip, void *my_tcp, void *my_udp, void *my_icmp);\fR

This function initializes the callback functions for ngrep. They
can be NULL, in which case there is no callback.
\fBngrep_callback_process\fR is defined for historical reasons.

\fBvoid ngrep_callback_info(void *my_info, void *my_stats);\fR

This function initializes the callback functions for info. The
first is actually the same first lines with the output of ngrep,
with the interface, filter, match and output information. The second
is the output at the end where you get the amount of received and
dropped packets.

\fBvoid ngrep_setfilter(char *bpffilter, char *matchexpression, char *options);\fR

This function initializes the filter, the match expression and the
options. The parameters are the same as you use them on the command
line for ngrep. For example:

ngrep_setfilter("port 4000 or icmp",NULL,"-d tun0");

\fBvoid ngrep_run(void);\fR

This function runs ngrep.

\fBvoid ngrep_main(char *bpffilter, char *match, char *options);\fR

This function is the same as calling ngrep_setfilter() and ngrep_run();

.SH CALLBACK FUNCTIONS

\fBvoid my_ip(struct ip *iphdr);\fR

This callback function has one parameter: the IP header. This one
should be used as the first parameter with \fBngrep_callback_process()\fR.
It will be called when an IP packet has arrived during \fBngrep_run()\fR.

\fBvoid my_tcp(struct ip *iphdr, struct tcphdr *tcphdr, char *data,int len);\fR

\fBvoid my_udp(struct ip *iphdr, struct udphdr *udphdr, char *data,int len);\fR

\fBvoid my_icmp(struct ip *iphdr, struct icmp *icmphdr, char *data,int len);\fR

\fBvoid my_arp(struct arphdr *arphdr);\fR

These callback functions have four parameters: the IP header, the
TCP/UDP or ICMP header, the data and the size of the data. These
should be used as the second, third or fourth parameter of
\fBngrep_callback_process()\fR. These will be called when TCP, UDP
or ICMP packets have arrived during \fBngrep_run()\fR.

\fBvoid my_info(char *interface, char *filter, char *match, char *output);\fR

This callback function is called during \fBngrep_setfilter()\fR
with information regarding the filters set by \fBngrep_setfilter()\fR.

\fBvoid my_stats(long received, long dropped);\fR

This callback function is called after \fBngrep_run()\fR has
finished. It contains some statistical information.

See test-lib.c for how to use them.

.SH LINKING

Use \fB-lngrep -lpcap\fR to link the executable.

.SH OPTIONS

See the man-page of ngrep(8) for the syntax of the options, match
and bpffilter. The only option removed is -q (quiet), that's now
done via the info and stats callback function.

.SH AUTHOR

ngrep written by Jordan Ritter <jpr5@darkridge.com>.

ngrep-library written by Edwin Groothuis <edwin@mavetju.org>.

.SH REPORTING BUGS

Send bug reports to the author.

.SH BUGS

At this moment, the maximum number of total spaces in the parameters
passed to ngrep_main() is 95.

The ARP callback function is only used for Ethernet networks.

.SH SEE ALSO

pcap(3), ngrep(8)