Libcoral operates on "sources", which include several types of live network interfaces/devices, and several types of tracefiles containing data recorded from one or more network interfaces/devices. The naming scheme for sources is described in the command usage document.
A typical program using CRL.pm has this basic structure:
configure CRL.pm and one or more sources
open sources
start sources
while (read cell or packet != undef
) {
process the data we just read
if (stop condition occurs) {
stop sources
}
}
close sources
All identifiers defined in this document are in the Coral
namespace.
In the descriptions below, there are several pairs of functions with the same
base name, with or without an "_all" suffix.
The function suffixed with "_all" operates on
all sources, and the other one operates on a single source indicated by
the src parameter.
Note on 'types'
The 'types' listed in the class definitions and function parameters
vary somewhat from standard Perl form. When possible, instead of
merely calling them 'SCALAR' or 'LIST', additional information has been
given as to the type of the parameter. Optional parameters are followed
by "=" and their default value. Examples of types:
Also, the 'FILEHANDLE' types must be attached to an actual stdio FILE.
The API
quick_start(BOOL time_sort = 1, BOOL partial_pkt = 1, NUM api = API_PKT);
To limit the number of sources that will be allowed, call
set_max_sources()
before calling this function.
This function returns nothing. If any fatal errors are encountered, it exits.
The code consists of:
sub quick_start { my ($time_sort, $partial_pkt, $api) = @_; if (defined $time_sort and $time_sort == 0) { if (set_options($OPT_SORT_TIME
, 0) < 0) { puts("Warning: could not unset time-sorting option!"); } } elsif (set_options(0, $OPT_SORT_TIME
) < 0) { puts("Warning: could not set time-sorting option!"); } if (defined $partial_pkt and $partial_pkt == 0) { if (set_options($OPT_PARTIAL_PKT
, 0) < 0) { puts("Warning: could not unset partial packeting option!"); } } elsif (set_options(0, $OPT_PARTIAL_PKT
) < 0) { puts("Warning: could not set partial packeting option!"); } if (defined $api) { if (set_api($api) < 0) { puts("Warning: could not specify api!"); } } elsif (set_api($API_PKT) < 0) { puts("Warning: could not specify packet api!"); } if (config_arguments(scalar(@ARGV), \@ARGV) < 0) { puts("Error: could not parse command-line options!"); exit(1); } if (open_all() <= 0) { # no openable sources is considered an error puts("Error: could not open any sources!"); exit(1); } if (start_all() < 0) { puts("Error: could not start any sources!"); exit(1); } }
You should call set_api()
before calling these functions to enable certain configuration commands.
Also, you should set the defaults for configurable values with the
set functions before calling any of these
functions, and (if needed) get the value after.
This way, the option and its default value will appear in the
usage()
message, and the user can override the
defaults with command line options. If your application does not use a
particular configurable value, you should leave it set to its initial value,
so it will not appear in the usage()
message,
and the config functions will not allow it
to be changed on the command line.
config_arguments(NUM argc, LIST REF argv);
-C
" options and sourcename arguments
contained in argv.
Argv is a reference to a list
of strings containing the command line;
argc is the number of strings in argv.
For a description of Coral options, see the
Command Usage documentation.
A CoralReef source is created (with new_source()
)
from each sourcename argument.
If an option syntax error is encountered, this function prints a usage message.
If other arguments are desired, use
config_options()
instead
and parse the arguments yourself;
if other options are desired, parse the options and arguments yourself and call
config_command()
for each "-C
" option.
Returns a non-negative integer for success, -1 for failure.
To limit the number of sources that will be allowed, call
set_max_sources()
before calling this function.
Sample call: $nxt_idx = config_options(scalar(@ARGV),
\@ARGV, "<outputfile>");
config_options(NUM argc, LIST REF argv, STR argmsg);
config_arguments()
, except it
processes only the options, not the non-option arguments.
If argmsg is undef
, this
function assumes that arguments (other than Coral options) are not allowed,
and considers it an error if other arguments are found;
otherwise, other arguments (but not other options) are allowed.
If successful, this function returns the index of the first non-option
argument.
It is the programmer's resposibility to handle
the remaining command line arguments.
If an error is encountered, this function returns -1, and prints a usage message
with usage($0, argmsg)
.
If other options are desired, use config_command()
instead.
Returns a non-negative integer for success, -1 for failure.
Sample call: $nxt_idx = config_options(scalar(@ARGV),
\@ARGV, "<outputfile>");
config_command(STR command, STR filename, NUM linenum);
config_options()
or config_arguments()
if you need to accept your own options in addition to CoralReef options,
or you want to accept CoralReef commands from inputs other than the command line.
Filename and linenum are printed in error
messages; pass undef and 0 to have them not printed.
Returns 0 for success, -1 for failure.
config_file(STR filename);
config_arguments()
,
config_options()
, or config_command()
is used.
usage(STR appname, STR argmsg = undef);
Some example values for argmsg:
undef
"[<argument>]"
"[-f] [-b<N>] <source>..."
quick_start(0); # or 1 for time-sortingfollowed by the read_cell routines. If other options are desired, you must parse the options and arguments yourself. If a bad option is given, this code will print a message like this to stderr, followed by descriptions of the Coral commands:
Usage: app [-C <command>]... <source>
set
functions can be called
before the config
functions to set default
values that can be overridden on the command line or config file, and will
be displayed in the usage
message.
If the integer configuration values are set to a negative value,
they will not be displayed in the usage
message.
The set
functions can also be called
after the config
functions
so their values can't be overridden.
They must not be called after sources are opened.
The set
functions return 0 if successful, or -1 for failure;
the get
functions return the value of the requested datum.
set_api(NUM api);
set_api()
must be
API_CELL
, or
API_PKT
,
optionally bitwise ORed with
API_WRITE
.
It initializes libcoral for use with the corresponding APIs,
and should be called before any coral config, reading, or writing function.
Setting the APIs enables command line and configuration file options and functions that are specific to those APIs. CRL.pm will generate an error if any disallowed option or function is attempted.
The api parameter should contain exactly one of the following constants:
API | allowed configuration commands | allowed functions |
API_CELL
|
cells
blocks
deny
| |
API_PKT
|
packets
filter
deny
| add_pcap_filter() |
The api parameter may optionally be bitwise-ORed with this constant, if write will be used:
API | allowed configuration commands | allowed functions |
API_WRITE
|
gzip
|
set_gzip()
|
set_max_sources(NUM n); get_max_sources();
set_max_sources()
sets the maximum number of allowed Coral
sources to n. It should be called before
config_arguments()
,
config_options()
,
config_command()
, and
new_source()
to restrict them.
It returns 0 if successful,
or -1 if n is negative or greater than 16.
get_max_sources()
returns the maximum number of allowed Coral
sources.
The default max_sources value is 16.
set_options(NUM off, NUM on); get_options();
set_options()
disables the options in the bitmask
off and enables the options in the bitmask on.
get_options()
returns a bitmask of currently enabled options.
The options are:
OPT_SORT_TIME
(default: off, unless quick_start() is used.)
read_cell_all()
read cells in timestamp order.
For this option to make sense, one of the following must be true:
all interfaces have start epochs and were started at the same time, or
all interfaces have unix epochs, or
the OPT_NORMALIZE_TIME
option is on.
If none of these conditions is true, libcoral will automatically enable the
OPT_NORMALIZE_TIME
option.
OPT_PARTIAL_PKT
(default: on)
read_pkt()
to handle partial packets.
OPT_FATM_RAW_TIME
(default: off)
OPT_POINT_RAW_TIME
(default: off)
OPT_RAW_TIME
(OPT_FATM_RAW_TIME
| OPT_POINT_RAW_TIME
)
.
OPT_NORMALIZE_TIME
(default: on)
OPT_SORT_TIME
)
with different default epochs.
But normalizing may introduce inaccuracy if
the interfaces' hosts' CPU clocks are inaccurate,
and may introduce additional processing overhead.
The default epochs for the various types of interfaces are:
start_all
());
start_all
());
OPT_NO_FILTER
(default: off)
OPT_IP_CKSUM
(default: off)
fmt_get_payload()
to print and verify IP checksums.
set_iomode(NUM off, NUM on, NUM first = -1, BOOL fixed = 0);
source_set_iomode()
.)
The arguments to this function are:
config
functions, in applications
with a non-configurable iomode).
The I/O mode flags:
flag | equivalent CLI iomode | description |
TX | tx | allow transmitting (not implemented) |
RX | rx | allow receiving |
RX_IDLE | idle | read all cells, including ATM idle cells |
RX_OAM | ctrl | read ATM OAM/RM cells |
RX_LAST | last | read last cell of each ATM AAL5 user PDU (packet) |
RX_USER_ALL | user | read all bytes of each packet or frame |
RX_ECHO | echo | retransmit received cells on devices which support it (always enabled on POINT cards) |
RX_UNKNOWN | for traces, read whatever cells are in the trace file; for devices, use default mode (i.e., rx first=48). Setting this flag clears all other settings. |
This function returns 0 for success, -1 for failure. It only affects sources that are created after it is called.
Setting first overrides a previously set
RX_USER_ALL
flag, and
setting the RX_USER_ALL
flag
overrides a previously set first value.
Attempting to set both at once has undefined results.
The default I/O mode is RX, and first==48. Currently, an attempt to explicitly use an I/O mode to read a trace that does not match the I/O mode used to record the trace will generate a warning, but all the data in the trace will still be read. In a future release, the read functions may filter trace files according to the I/O mode (or generate an error if that is not possible).
For a summary of the iomode options supported by the various interface types, see the command usage document.
set_errfilename(STR filename);
set_errfilename()
sets,
the destination for future libcoral error and warning messages.
filename is the name of a file that will be opened by CRL.pm.
Any previously set error file will be closed only if it was set by name other
than "-".
If filename is undef
,
stderr will be used.
If filename is "-"
, stdout will be used.
The default message destination is stderr.
set_verbosity(NUM verbosity); get_verbosity();
coral_set_max_pkts(NUM n); coral_set_max_cells(NUM n); coral_set_max_blks(NUM n); coral_get_max_pkts(); coral_get_max_cells(); coral_get_max_blks();
count | affected APIs |
max_pkts | packet |
max_cells | cell |
max_blks | cell |
set_comment(STR comment); get_comment();
write
functions. The default comment may
be overridden by
the comment parameter of write_open()
.
set_duration(NUM duration); get_duration();
If the duration value is greater than 0, it determines how long libcoral will read from sources after they are started; after the duration has expired, the reading function will indicate EOF. Libcoral uses both real time and cell timestamps to test duration, so it will work with tracefiles and devices receiving live traffic.
With the default duration of -1, the config
functions
will not allow duration to be set.
To have your application not use duration by default, but still let the
user override it, set it to 0
before calling the config
functions.
Before version 3.3.0, libcoral did not test duration when reading; the programmer was expected to handle it himself. Now, the programmer should do nothing other than enable it, and let libcoral's reading functions handle the duration.
set_interval(LIST REF interval); get_interval();
get_interval()
returns (-1, -1, -1); otherwise, it returns (0, sec, usec),
where sec and usec are the seconds and microseconds,
respectively of a nonnegative interval value.
The interval value is never automatically used by libcoral; it just provides a
convenient and consistent way to let the user set an interval on the command
line or in a config file. The programmer may use the interval by passing
the result of get_interval()
in as a parameter to
read_pkt_init()
or
read_cell_i()
.
Libcoral uses cell timestamps to test for intervals, so the intervals it
reports will be correct for both tracefiles and devices, although the act
of reporting may be delayed because of internal buffering.
With the default interval of -1, the config
functions
will not allow interval to be set.
To have your application not use interval by default, but still let the
user override it, set it to 0.0
before calling the config
functions.
set_gzip(STR mode);
undef
, write_open()
will not gzip files
unless they end in ".gz".
If mode is "", write_open()
will gzip files with the
default parameters (compression level 1).
If mode is a non-empty string,
write_open()
will append it to the "wb" mode when calling
gzopen()
; see the zlib documentation for details.
new_source(STR sourcename);
undef
for failure.
This function is useful for creating a source directly from the program
(instead of through command line and config file with the
config
functions).
new_fsource(FILEHANDLE file, STR sourcename = undef);
undef
, open()
will examine it for a prefix or suffix
to determine how to interpret the data read from file;
otherwise, open()
will assume data from file contains a
CoralReef (crl) trace.
This function is useful for creating a source directly from a
file handle in the program;
for example, a socket connected to another process that used
write_fopen()
.
Mixing CoralReef operations with other operations on handle file may have unpredictable effects.
source_set_iomode(SCALAR src, NUM off, NUM on, NUM first = -1); source_set_iomode_all(NUM off, NUM on, NUM first = -1);
To set the default I/O mode of sources that have not yet been defined, use set_iomode().
source_set_firmware(SCALAR src, STR firmware); source_set_firmware_all(STR firmware);
/proc/dag
will report the device is "Busy");
the card must be re-initialized before CoralReef can read from it again.
open(SCALAR src); open_all();
config_arguments()
, config_options()
,
config_command()
, and new_source()
,
but do not start them.
If successful, these functions return the number of interfaces opened.
If unsuccessful, these functions return -1 and close
the source which failed.
Note that a single tracefile source may contain multiple interfaces.
start(SCALAR src); start_all();
open()
or open_all()
.
Addtionally, start_all()
resets the clocks of all
open interfaces that allow it, to synchronize them.
A source can not be read until it is started with one of these functions.
(Prior to version 3.3, it was not strictly necessary to start tracefile
sources.)
stop_all(); stop(SCALAR src);
close_all(); close(SCALAR src);
read_pkt_init(SCALAR src, SCALAR iface, LIST REF interval = undef);
read_pkt()
.
If iface is not undef
,
packets will be read from iface;
otherwise, if src is not undef
,
packets will be read from all interfaces of src;
otherwise, packets will be read from all interfaces of all open sources.
There is no restriction on reading multiple pcap sources or mixing pcap and
OCx sources, as there was prior to version 3.4.
If iface belongs to a source with multiple interfaces, data
from the other interfaces of that source will be discarded.
Packets can be read from only one set of sources at a time;
calling read_pkt_init()
invalidates any sources that were
previously initialized for packet reading.
Interval is the amount of time read_pkt()
will wait between returning statistical information (measured against packet
timestamps).
To set the interval, give read_pkt_init()
a
reference to a 2-element array representing the seconds
and microseconds of the interval, such as [100, 0], which might
come from get_interval()
.
Interval defaults to undef
, which disables interval handling.
read_pkt_init()
returns 0 if successful, or -1 if an
error occurs.
Because read_pkt()
implicitly
sorts packets by timestamp, the packet timestamps must be comparable.
If necessary,
read_pkt_init()
will automatically enable the
OPT_NORMALIZE_TIME
option to guarantee that the timestamps are comparable.
read_pkt_init()
returns 0 if successful, or -1 if an
error occurs.
read_pkt(Pkt_result_REF pkt_result, Interval_result_REF interval_result = undef);
read_pkt_init()
.
If a packet filter has been set, only
packets that match the filter will be read.
Packets read are always sorted by time, regardless of the setting of the
OPT_SORT_TIME
option.
If the OPT_PARTIAL_PKT
option is turned off, only complete packets will be read
(but truncated packets are always counted by the truncated field of
Pkt_stats).
pkt_result and interval_result are
references to objects created by the user
that will be filled in by the call.
For success, read_pkt()
returns
interface which was read,
and the contents of the objects indicate what happened:
if (defined pkt_result->packet) {
pkt_result
.pkt_result->packet
will reference a
Pkt_buffer
containing the link layer (LLC/SNAP, ethernet, etc) PDU.
On ATM interfaces,
pkt_result->header
will reference a
Pkt_buffer
containing the first 4 bytes of the ATM header of the last captured cell
of the packet (in network byte order);
pkt_result->trailer
will reference a
Pkt_buffer
containing the AAL5 trailer (in network byte order), if available; and
pkt_result->subiface
will contain the ATM vpvc
(in host byte order) from which the packet was read.
On IEEE 802.3/Ethernet interfaces carrying IEEE 802.1Q VLAN traffic,
pkt_result->subiface
will be the VLAN ID.
On other types of interfaces, pkt_result->header
and pkt_result->trailer
will be undef
,
and pkt_result->subiface
will be 0.
} elsif (not defined interval_result->stats) {
interval_result->begin
.
(interval_result->end
is not valid.)
} else {
interval_result->begin
and
ending at interval_result->end
has ended.
Statistics for the interval are contained in
interval_result->stats
.
}
If the interval specified in read_pkt_init()
was
undef
or 0,
interval_result may be omitted or undef
,
and read_pkt()
will never return with
pkt_result->packet ==
.
The beginning of an interval is not aligned to a multiple of
the interval size.
When reading from a live interface, internal buffering may cause reporting of
the end of the interval to be delayed, but the data reported will cover exactly
the requested interval.
(In versions 3.2.x, the reported interval included "quiet" (trafficless) time
after the end of the requested time.
In versions 3.1 and earlier, the data reported
included packets past the end of the interval that fell in the same internal
buffer as the end of the interval.) Interval comparisons are made against
packet timestamps, not a real clock, so the same results will be produced by
reading a live interface or reading a trace taken on that interface in the
same period.
undef
The protocol of pkt_result->packet
is determined by the interface type.
For ATM interfaces, the protocol is determined by the virtual channel and
proto
configuration rules .
Note that if the configuration is incorrect, the packet buffer will
not make sense.
For TSH interfaces, the protocol for a valid packet is always
NETPROTO_IPv4
,
and IP options are always zero; the protocol of an invalid packet is
PROTO_UNKNOWN
.
To indicate EOF, a stopped device, or
expired duration,
read_pkt()
returns
undef
with $! == 0
.
For an error, read_pkt()
returns undef
with
$!
set to indicate the type of error.
(Certain types of errors that were reported as EOF in versions prior 3.5
are now correctly reported as errors.)
If get_verbosity() >= 1, then
at the end of every interval,
if there were any packet errors
(nonzero fields in interval_result->stats
)
during the interval,
read_pkt()
prints warnings to the error file.
If intervals were not used, the warnings are printed only at EOF,
covering the entire duration.
get_payload(Pkt_buffer_REF src, Pkt_buffer_REF dst);
src->caplen > 0
.
Dst is also a reference to a Pkt_buffer,
but is created by the user, eg:
"$argument = new Pkt_buffer;
".
get_payload()
skips past the lower level (outer) protocol
encapsulation in src and fills in dst with information
about the payload of src
(see Pkt_buffer).
If get_payload()
understands the src protocol
but does not recognize the protocol of the payload,
dst->protocol
will contain
PROTO_UNKNOWN
or some other undefined value.
get_payload()
returns 0 if it successfully parsed
the src protocol information, or one of the following negative
error codes:
DLT_ATM_RFC1483
.
This function treats IPv6 extension headers as encapsulated protocols.
So, for example, say you have an Ethernet frame containing an IPv6 packet
with a Routing header, Fragment header, and UDP datagram.
If you call get_payload()
with that packet as src,
and then repeatedly with the dst of the previous call as the src
of the next,
the value of dst->protocol
after each successive call would be
NETPROTO_IPv6
,
IPPROTO_ROUTING
,
IPPROTO_FRAGMENT
,
IPPROTO_UDP
, and
PROTO_UNKNOWN
,
respectively.
Note: TSH files contain IPv4 packet headers only, and when CoralReef reads an IPv4 packet from a TSH file it fills the missing IP options (if any) with zeros to create a syntactically valid substring of an IP packet.
fmt_get_payload(Pkt_buffer_REF src, Pkt_buffer_REF dst, STR REF buf);
fmt_get_payload()
is like
get_payload()
, except that it also writes
human-readable information about the lower level protocol into buf.
Returns a nonnegative number if successful,
or -1 for any of the following errors:
vsnprintf()
is not available on your system
and buf is not undef
;
or any of the errors listed in the documentation for
get_payload().
The information written into buf attempts to cover all relevant information
about the protocol. Irrelevant information is omitted for brevity (for
example: for TCP, the urgent pointer is printed only if the URG flag is set;
for IPv4, type-of-service is printed only if it is nonzero,
and the fragment offset is printed only if the packet is a fragment).
The IP checksum will be printed and verified only if the
OPT_IP_CKSUM
option is set.
get_payload_by_proto(Pkt_buffer_REF src, Pkt_buffer_REF dst, NUM proto); get_payload_by_layer(Pkt_buffer_REF src, Pkt_buffer_REF dst, NUM layer);
add_pcap_filter(STR expr)
undef
, add_pcap_filter()
sets expr as a global pcap filter expression.
If a filter expression was already set (either by this function or by
config "filter" commands),
the old and new expressions are joined as
"(old_expr) and (expr)
".
The expression will be compiled and set on every source that is subsequently
opened; it has no effect on sources that are already open.
If expr is undef
,
add_pcap_filter()
clears
any previously set global pcap filter expression.
This function will not work until set_api(API_PKT)
is called.
This function returns 0 if successful,
or -1 with $! set if there is an error.
See also the section on -Cfilter in the command usage document.
get_pcap_filter()
undef
if no filter expression has been set.
The cell reading functions may be used only with ATM interfaces that have been started. For working with layers 3 and above, the packet reading functions are usually better.
After any of these reading functions are successful,
binfop will be a reference to a byte string representing the block info,
and cellp will be a reference to a Cell object.
binfop can be parsed by the Unpack functions.
binfop may be passed a value of undef
if the block info will not be
needed.
If timeout is undef
or omitted,
these functions will wait until data are available or an interrupt occurs.
But if timeout is not undef
,
these functions will also return after
the amount of time specified in timeout even if there are no data.
To set the timeout, input a reference to a
2-element array representing the seconds and microseconds
of the timeout, such as [100, 0].
The deny
protocol rules
are applied by the cell reading functions
to filter the cells and determine their protocol.
Note: prior to version 3.4.2, the cell reading functions did not apply
the the configuration deny
rules.
Calls to the different CoralReef reading functions may not be interleaved on a given set of sources.
A call to any CoralReef reading function on a given set of sources invalidates all data in buffers set by previous calls to any reading functions on the same set of sources.
undef
with $!==0
for EOF,
stopped device, or
expired duration.
(If end-of-file is encountered someplace other than a block boundary, it
is considered an error.)
undef
with $!==EAGAIN
if timeout is exceeded
undef
with $!==EBADF
if sources are not ATM.
undef
with other $! value for other errors
undef
interface reference for success
read_cell(SCALAR src, STR REF binfop, Cell_REF cellp, LIST REF timeout = undef); read_cell_all(STR REF binfop, Cell_REF cellp, LIST REF timeout = undef);
read_cell()
reads a single cell from the indicated source;
read_cell_all()
reads from all open sources.
If the OPT_SORT_TIME
option is off,
read_cell_all()
reads cells in the most
efficient order (i.e., block order);
but if the OPT_SORT_TIME
option is on, it will read them
in time-sorted order (interleaving cells from blocks of different interfaces).
If the OPT_SORT_TIME
is set,
timeout is ignored (it is always treated as undef
).
See the section introduction above for more details and return values.
read_cell_i(SCALAR src, STR REF binfop, Cell_REF cellp, Interval_result_REF int_result, LIST REF interval = undef); read_cell_all_i(STR REF binfop, Cell_REF cellp, Interval_result_REF int_result, LIST REF interval = undef);
read_cell()
and read_cell_all()
,
except that there is no timeout and they support intervals.
If the value of interval is greater than 0.0, then
time sorting is automatically enabled regardless of the setting of the
OPT_SORT_TIME
option, and
whenever *interval
seconds have passed or EOF is reached,
the functions will return non-undef
with
cellp == undef
to indicate that an interval has ended,
and the start
and end
fields of int_result
will be filled in with the boundaries of the interval.
binfop
is undefined at the end of an interval.
int_result->stats
is always undef
.
When EOF is reached, the final partial interval is returned, and the
next call will return undef
.
See the section introduction above for more details and return values.
cell_to_pkt(SCALAR iface, Cell_REF cell, Pkt_buffer_REF pkt)
cell_to_pkt
fills in the object
referenced by pkt with
information from cell and iface,
for use with functions that expect a
Pkt_buffer argument.
Iface and the cell's vp:vc are used to determine the protocol of
the data according to the configuration
proto
rules.
If iface is undef
,
pkt->protocol
will be set to
PROTO_UNKNOWN
.
The return value is 0 if
iface and the cell's vp:vc match a configuration
deny
rule, otherwise 1.
get_ip(SCALAR iface, REFERENCE data)
undef
if there was any error.
(IP version != 4 counts as an error.)
The byte string can then be parsed by the
Unpack functions.
get_cell_timestamp(Cell_REF cell);
$stamp = get_cell_timestamp($cell);
$stamp = $cell->timestamp($iface);
read_clock_sec_nsec(SCALAR iface, SCALAR t); read_clock_double(SCALAR iface, SCALAR t);
If the OPT_NORMALIZE_TIME
option is set, the result will be measured from the unix epoch;
otherwise, the result will have some interface-dependant epoch.
Normalization may introduce some error in the precision; this error will be
the same for all timestamps from the same interface, but may be different
for different interfaces.
These functions automatically correct the case in which the FORE card doesn't
increment the firmware clock because it misses a hardware clock wrap,
unless the OPT_FATM_RAW_TIME
option is set.
read_clock_double()
returns the time
as floating point number of seconds.
Note that some precision may be lost by the conversion to double.
read_clock_sec_nsec()
returns the time as a 2-element list of seconds and nanoseconds.
next_interface(SCALAR iface);
next_source(SCALAR src);
undef
,
these functions return a pointer to the first CoralReef interface/source;
otherwise, they return a pointer to the interface/source following
iface/src.
They return undef
if there is no next interface/source.
The order in which interfaces/sources are returned
is not necessarily the order in which they were opened.
These functions are used to step through all interfaces/sources, for example:
$iface = undef;
while (($iface = next_interface($iface))) {
# operate on iface
}
next_src_iface(SCALAR src, SCALAR iface);
source_get_filename(SCALAR src);
undef
if src is bad.
source_get_name(SCALAR src);
undef
if src is bad.
get_source_count();
interface_get_src(SCALAR iface);
undef
if iface is bad.
interface_get_type(SCALAR iface);
source_get_type(SCALAR src);
interface_get_datalink(SCALAR iface);
PROTO_UNKNOWN
if the protocol is unknown,
or -1 if iface is bad.
The data link layer type is one of the DLT_*
(layer 2) constants
defined in the
Command Usage document.
interface_get_physical(SCALAR iface);
PROTO_UNKNOWN
if the protocol is unknown,
or -1 if iface is bad.
The physical layer type is one of the PHY_*
(layer 1) constants
defined in the
Command Usage document.
interface_get_bandwidth(SCALAR iface);
source_get_number(SCALAR src);
interface_get_number(SCALAR iface);
interface_get_capture_tv(SCALAR iface);
interface_get_capturetime(SCALAR iface);
interface_get_capture_tv(iface)
.
proto_abbr(NUM protocol);
proto_desc(NUM protocol);
proto_str(NUM protocol);
prefix_name
constant (listed in the
Command Usage document)
indentifying a communication protocol.
These functions return a pointer to a string describing protocol:
proto_abbr
: a short name, or undef
;
proto_desc
: a long description, or undef
;
proto_str
: a long description, or "unknown N".
proto_id(STR name);
coral_proto_{abbr,desc,str}()
.
proto_layer(NUM protocol);
cell_size(SCALAR iface);
write_open(STR name, STR comment = undef, STR encoding = undef, NUM version = 0);
".gz"
or the
"gzip" configuration option was
given, and CoralReef was compiled with libz, the file will be gzipped.
(set_api() must be called with the API_WRITE bit
to enable the "gzip" configuration option.)
If the name is "-"
, data will be written to stdout.
Returns a coral write descriptor (writer)
for success, undef
for failure.
The reccommended suffix for CoralReef trace files is ".crl", and for encoded
CoralReef trace files is ".enc.crl".
Writes comment and encoding strings into the file header, with encoding version set to version. Comment and encoding default to undef, version defaults to 0. Comment may be up to 255 characters, encoding may be up to 31 characters.
To ensure that all data from all sources are read, you must call
stop()
on any sources which have not reached EOF.
Then, to ensure that all data from all sources are written, you must call
write_close()
on the writer, before calling
close()
on the sources.
write_fopen(FILEHANDLE file, STR comment = undef, STR encoding = undef, NUM version = 0);
Mixing CoralReef operations with other operations on handle file may have unpredictable effects.
write_init_all(SCALAR writer); write_init_source(SCALAR writer, SCALAR src);
write_init_interface(SCALAR writer, SCALAR iface);
write_cell(SCALAR writer, SCALAR iface, SCALAR cell);
write_close(SCALAR writer);
stop()
on any sources which have not reached EOF.
To ensure that all data from all sources are written, you must call
write_close()
on the writer, before calling
close()
on the sources.
filename(STR str, STR REF dst);
~name/
" replaced with the home directory of user
name, and any leading "~/" replaced with the home directory of the user
who owns the process.
puts(STR str);
puts(str)
, except that it prints to the
CoralReef errfile instead of stdout,
and it is guaranteed to not modify errno
.
fprint_data(FILEHANDLE file, NUM indent, SCALAR data, NUM len); print_data(NUM indent, SCALAR data, NUM len);
print_data
prints len bytes from data
to stdout
in a easily readable format:
16 hex values per line, with each line indented indent spaces.
fprint_data
is like
print_data
, except
it prints to file instead of stdout
.
fprint_cell(FILEHANDLE file, NUM indent, SCALAR iface, SCALAR cell); print_cell(NUM indent, SCALAR iface, SCALAR cell);
stdout
in an easily readable format, with the timestamp in seconds, the
ATM header expanded by fields, and the payload in hex,
with each line indented indent spaces.
This format is used by the application crl_print
.
fprint_cell
is like print_cell
, except
it prints to file.
fmprint_pkt(FILEHANDLE file, SCALAR iface, SCALAR timestamp, NUM minlayer, NUM maxlayer, Pkt_buffer_REF packet, Pkt_buffer_REF header, Pkt_buffer_REF trailer);
fmprint_pkt
prints packet and optionally
header and trailer
(which were read from iface) to file
in an easily readable format, with the timestamp in seconds.
Protocol layers less than minlayer will be skipped;
layers between minlayer and maxlayer will be
expanded by fields in an easily readable format;
layers greater than maxlayer or not understood by libcoral
will be printed in hex.
This format is used by the application crl_print_pkt
.
fprint_pkt(FILEHANDLE file, SCALAR iface, SCALAR timestamp, NUM maxlayer, Pkt_buffer_REF packet, Pkt_buffer_REF header, Pkt_buffer_REF trailer);
fprint_pkt(iface, timestamp,
maxlayer, packet,
header, trailer)
is equivalent to
fmprint_pkt(iface, timestamp,
1, maxlayer, packet,
header, trailer)
.
fmt_if_subif(STR REF buf, SCALAR iface, NUM subif);
if_fmt_subif
prints a formatted representation of
iface id and subif into buf.
If the data link type of iface does not have subinterfaces,
the format is just the interface number
(interface_get_number);
if it does, the format is
"if[subif]", where subif is formated as by
fmt_subif.
This function returns the length of the formatted string.
fmt_subif(STR REF buf, SCALAR iface, NUM subif);
coral_fmt_subif
prints a formatted representation of
subif into buf.
The format depends on the data link type of iface:
dump(SCALAR src); dump_all();
crl_info
.
stats(SCALAR *src); stats_all();
in_cksum_add(NUM psum, SCALAR data, NUM len); in_cksum_result(NUM psum);
psum
to 0
$psum = in_cksum_add($psum, data, len)
for each segment of buffer,
where data is the segment
and len is the length of the segment
in_cksum_result($psum)
to get result.
$header = $cell->header($iface);
SCALAR timestamp # time cell was read (interpret with read_clock functions) STR header # link layer header (eg, ATM) STR hec # HEC that libcoral doesn't include in the header STR payload # link or sub-network layer packet
NUM caplen # length of data actually captured in buf NUM totlen # total length of pkt (negative if unknown) STR buf # data (in a byte-string format) NUM protocol # protocol (ie, what kind of buffer is this?)
NUM l2_recv; # Layer 2 PDUs received NUM l2_drop; # Layer 2 PDUs dropped NUM pkts_recv; # packets received NUM pkts_drop; # packets dropped NUM truncated; # packets truncated by insufficient capture NUM driver_corrupt; # cell looks bad from the capture device NUM too_many_vpvc; # too many simultaneous vpvc pairs NUM buffer_overflow; # AAL5 cell stream > MAX_PACKET_SIZE NUM aal5_trailer; # AAL5 trailer had bad length NUM ok_packet;The
l2_recv
and l2_drop
fields count layer 2 PDUs
(e.g., ATM cells), and may not be totally accurate.
On interfaces that operate on blocks (i.e., POINT, FORE ATM, and DAG),
the layer 2 PDUs reported are those belonging to every block that started
within the interval. If there are many blocks per interval the error should
be small, but if traffic is low the error is more significant.
SCALAR timestamp # time packet was read (interpret with read_clock functions) Pkt_buffer_REF packet # link or sub-network layer packet Pkt_buffer_REF header # link layer header (eg, ATM) Pkt_buffer_REF trailer # link layer trailer (eg, AAL5) NUM subiface # sub-interface id (ATM VPVC or VLAN ID)The
subiface
field can be formatted with
fmt_subif().
LIST begin # beginning of interval (sec, usec) LIST end # end of interval (sec, usec) Pkt_stats_REF stats # statistics for interval