Provided by: libncap44t64_1.9.2-8.1build2_amd64 
NAME
ncap — network data capture
SYNOPSIS
#include <ncap.h>
ncap_t
ncap_create(int maxmsgsize);
DESCRIPTION
The ncap library is a high level interface for network data capture. The source of network data can be
either live traffic or files containing previously captured or generated data. Files can be in ncap
format, as defined below, or in pcap(3) format, and can be either normal binary files or network sockets.
The ncap_create() function returns a new ncap object (structure) having various methods (function
pointers) which can be referenced to add data sources, poll for data, loop while collecting data, and so
on. maxmsgsize is the size of the largest message (in portable binary export format) you are expecting
to handle, usually this is 70000, to allow for a 64Kbyte payload plus ncap message header overhead.
ncap_create() returns NULL if an error occurs, in which case errno will be set to indicate the error
cause.
The ncap_t data structure is defined in the <ncap.h> include file, which defines at least the following
symbols:
typedef enum { ncap_success = 0, ncap_failure } ncap_result_e;
typedef void (*ncap_callback_t)(ncap_t, void *, ncap_msg_ct);
typedef struct ncap *ncap_t;
struct ncap {
char * errstr;
ncap_result_e (*add_if)(ncap_t, const char *name,
const char *bpf, int promisc,
const int vlans[], int nvlan,
int *fdes);
ncap_result_e (*drop_if)(ncap_t, int fdes);
ncap_result_e (*add_nf)(ncap_t, int fdes, const char *);
ncap_result_e (*drop_nf)(ncap_t, int fdes);
ncap_result_e (*add_pf)(ncap_t, FILE *, const char *);
ncap_result_e (*drop_pf)(ncap_t, FILE *);
ncap_result_e (*add_dg)(ncap_t, int fdes);
ncap_result_e (*drop_dg)(ncap_t, int fdes);
ncap_result_e (*filter)(ncap_t, const char *);
ncap_result_e (*collect)(ncap_t, int polling,
ncap_callback_t,
void *closure);
void (*stop)(ncap_t);
struct ncap_msg (*cons)(ncap_t, struct timespec,
unsigned, unsigned,
ncap_np_e, ncap_np_ct,
ncap_tp_e, ncap_tp_ct,
size_t, const u_char *);
int (*match)(ncap_t, ncap_msg_ct);
ncap_result_e (*write)(ncap_t, ncap_msg_ct, int fdes);
ncap_result_e (*fwrite)(ncap_t, ncap_msg_ct, FILE *);
ncap_result_e (*send)(ncap_t, ncap_msg_ct, int fdes,
int flags);
void (*destroy)(ncap_t);
};
The elements of ncap_t are defined as follows:
errstr A pointer to a text string describing the most recent error condition. If no error has
occurred, this string will be empty, but never NULL.
add_if Adds a network interface as a data source. Interface naming rules are as in pcap(3). A bpf(4)
program (in text form) can be provided in order to filter the data source in the kernel and
thus reduce the amount of data collected by this object. It is an error to specify a non-NULL
bpf program if an NCAP filter has been installed. The interface can be made promiscuous, in
which case it is eligible to receive data for which this system is neither the source or
destination, if the attached network and interface support this mode. A list of VLANs can be
provided in which case tagged 802.1Q frames are eligible and will be collected if their tag
number is on the provided list. If the list contains only VLAN tag number zero (0) then all
tagged frames will be eligible. The file descriptor opened for this interface can be returned
in order to be used by select(2) or in drop_if as defined below.
drop_if Removes the designated interface from further consideration or data collection.
add_nf Adds a previously opened NCAP file as a data source.
drop_nf Drops an NCAP file as a data source.
add_pf Adds a previously opened PCAP file as a data source.
drop_pf Drops an PCAP file as a data source.
add_dg Adds a previously opened datagram socket as a data source.
drop_dg Drops a datagram socket as a data source.
watch_fd Adds a file descriptor to the set watched by collect, such that a readability event on this
descriptor will result in the designated watcher callback being activated with the supplied
closure.
drop_fd Removes a file descriptor from the set being watched by collect.
filter Installs an NCAP filter, specified as ASCII text. It is an error to install a filter if any
interface has been added with a supplied BPF program.
collect Run the data collection engine, either once (if polling) or continuously (until stop() is
called). Each collected message will be formatted into an ncap_msg structure and, if no filter
has been installed or if the message matches the installed filter, passed to the supplied
callback along with the supplied closure.
stop Can be called from within a collect() callback or from within an operating system signal
handler, this will end the loop inside collect().
cons Returns a ncap_msg structure filled in according to the arguments. It's wise to use this
rather than doing inline initialization in case new fields are added to the ncap_msg structure
later on.
match Tests a supplied message against any installed filter. Returns TRUE if no filter is installed
or if the message matches the installed filter, else FALSE.
write, fwrite, send
Exports an ncap_msg structure to a file descriptor, file pointer, or datagram socket in
portable binary format. If no message is supplied (e.g., NULL) , a "file header" is output,
containing a magic number and the ncap library version number. A file header must be the first
thing in an ncap file, and should be sent periodically on a datagram socket. If the result is
ncap_failure
then errno will have been set by an underlying failed system call.
destroy Release all resources held by this ncap object, including heap memory and underlying pcap(3)
objects. Standard I/O files as provided to add_pf() are not closed here and are the
responsibility of the caller.
Message Formats
An in-memory ncap message has the following structure:
typedef enum { ncap_ip4 = 0, ncap_ip6 } ncap_np_e;
typedef union ncap_np *ncap_np_t;
typedef const union ncap_np *ncap_np_ct;
union ncap_np {
struct {
struct in_addr src, dst;
} ip4;
struct {
struct in6_addr src, dst;
} ip6;
};
typedef enum { ncap_udp = 0, ncap_tcp } ncap_tp_e;
typedef union ncap_tp *ncap_tp_t;
typedef const union ncap_tp *ncap_tp_ct;
union ncap_tp {
struct {
unsigned sport, dport;
} udp;
struct {
unsigned sport, dport;
unsigned offset;
unsigned flags;
} tcp;
};
#define ncap_tcp_syn 0x0001 /* first segment */
#define ncap_tcp_fin 0x0002 /* last segment */
#define ncap_tcp_rst 0x0004 /* session reset */
#define ncap_tcp_sum 0x0008 /* checksum failed */
typedef struct ncap_msg *ncap_msg_t;
typedef const struct ncap_msg *ncap_msg_ct;
struct ncap_msg {
/* Fixed part. */
struct timespec ts;
unsigned user1, user2;
ncap_np_e np;
ncap_tp_e tp;
size_t paylen;
/* Variable part. */
union ncap_np npu;
union ncap_tp tpu;
const u_char * payload;
};
The portable binary export format of an ncap message is as follows:
Fixed part (size is 28):
uint32_t message length (includes self, padding)
uint32_t sec, nsec
uint32_t user1, user2
uint16_t network union type (includes padding)
uint16_t transport union type (includes padding)
uint32_t payload length (no padding)
Variable part (size is always evenly divisible by 4):
u_char [] network union
u_char [] transport union
u_char [] payload
Reliable streams of portable binary format ncap messages should begin with a "file header", and datagram
streams should include a "file header" every so often for receiver synchronization. A "file header" has
the following structure:
magic 4 octets having the value of ASCII "NCAP".
vers 4 octets having the network byte order of the ncap version (currently 0x00 0x00 0x00 0x2a).
SEE ALSO
select(2), sendmsg(2), writev(2), pcap(3), fdopen(3), bpf(4)
BUGS
ncap filters are not implemented yet, so for now, use bpf(3) filters in add_if().
LICENSE
Copyright (c) 2007 by Internet Systems Consortium, Inc. ("ISC")
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is
hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL,
DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Debian August, 2007 NCAP(3)