.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BPTRACE 1"
.TH BPTRACE 1 "2014-07-08" "perl v5.20.1" "BP executables"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
bptrace \- Bundle Protocol (BP) network trace utility
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBbptrace\fR \fIown_endpoint_ID\fR \fIdestination_endpoint_ID\fR \fIreport\-to_endpoint_ID\fR \fI\s-1TTL\s0\fR \fIclass_of_service\fR "\fItrace_text\fR" [\fIstatus_report_flags\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBbptrace\fR uses \fIbp_send()\fR to issue a single bundle to a designated
destination endpoint, with status reporting options enabled as selected
by the user, then terminates.  The status reports returned as the bundle
makes its way through the network provide a view of the operation of the
network as currently configured.
.PP
\&\fI\s-1TTL\s0\fR indicates the number of seconds the trace bundle may remain in the
network, undelivered, before it is automatically destroyed.
.PP
\&\fIclass_of_service\fR is \fIcustody-requested\fR.\fIpriority\fR[.\fIordinal\fR[.\fIunreliable\fR.\fIcritical\fR[.\fIflow-label\fR]]],
where \fIcustody-requested\fR must be 0 or 1 (Boolean), \fIpriority\fR must be 0
(bulk) or 1 (standard) or 2 (expedited), \fIordinal\fR must be 0\-254,
\&\fIunreliable\fR must be 0 or 1 (Boolean), \fIcritical\fR must also be 0 or 1
(Boolean), and \fIflow-label\fR may be any unsigned integer.  \fIordinal\fR is
ignored if \fIpriority\fR is not 2.  Setting \fIclass_of_service\fR to \*(L"0.2.254\*(R"
or \*(L"1.2.254\*(R" gives a bundle the highest possible priority.  Setting
\&\fIunreliable\fR to 1 causes \s-1BP\s0 to forego retransmission in
the event of data loss, both at the \s-1BP\s0 layer and at the convergence layer.
Setting \fIcritical\fR to 1 causes contact graph routing to forward the bundle
on all plausible routes rather than just the \*(L"best\*(R" route it computes; this
may result in multiple copies of the bundle arriving at the destination
endpoint, but when used in conjunction with priority 2.254 it ensures that
the bundle will be delivered as soon as physically possible.
.PP
\&\fItrace_text\fR can be any string of \s-1ASCII\s0 text; alternatively, if we want to send
a file, it can be \*(L"@\*(R" followed by the file name.
.PP
\&\fIstatus_report_flags\fR must be a sequence of status report flags, separated
by commas, with no embedded whitespace.  Each status report flag must be one
of the following: rcv, ct, fwd, dlv, del.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.ie n .IP """0""" 4
.el .IP "``0''" 4
.IX Item "0"
\&\fBbptrace\fR has terminated.
.SH "FILES"
.IX Header "FILES"
No configuration files are needed.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
No environment variables apply.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following diagnostics may be issued to the \fBion.log\fR log file:
.IP "bptrace can't attach to \s-1BP.\s0" 4
.IX Item "bptrace can't attach to BP."
\&\fBbpadmin\fR has not yet initialized \s-1BP\s0 operations.
.IP "bptrace can't open own endpoint." 4
.IX Item "bptrace can't open own endpoint."
Another \s-1BP\s0 application task currently has \fIown_endpoint_ID\fR open for
bundle origination and reception.  Try again after that task has terminated.
If no such task exists, it may have crashed while still holding the endpoint
open; the easiest workaround is to select a different source endpoint.
.IP "No space for bptrace text." 4
.IX Item "No space for bptrace text."
Probably an unrecoverable database error, in which case the local \s-1ION\s0
node must be terminated and re-initialized.
.IP "bptrace can't create \s-1ZCO.\s0" 4
.IX Item "bptrace can't create ZCO."
Probably an unrecoverable database error, in which case the local \s-1ION\s0
node must be terminated and re-initialized.
.IP "bptrace can't send message." 4
.IX Item "bptrace can't send message."
\&\s-1BP\s0 system error.  Check for earlier diagnostic messages describing the
cause of the error; correct problem and rerun.
.SH "BUGS"
.IX Header "BUGS"
Report bugs to <ion\-bugs@korgano.eecs.ohiou.edu>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbp\fR\|(3)