From: Sami Kerola Date: Sun, 4 Dec 2016 10:43:45 +0000 (+0000) Subject: docs: improve mtr-packet(8) manual page X-Git-Tag: v0.88~15^2~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=22b7454a2faed8f37b608cfff320e567c5f96ab6;p=thirdparty%2Fmtr.git docs: improve mtr-packet(8) manual page Indent argument descriptions, and groff_man(7) style. --- diff --git a/mtr-packet.8.in b/mtr-packet.8.in index de4d72b..9908015 100644 --- a/mtr-packet.8.in +++ b/mtr-packet.8.in @@ -1,14 +1,14 @@ .TH MTR-PACKET 8 "@VERSION@" "mtr-packet" "System Administration" +.HP 7 .SH NAME mtr-packet - send and receive network probes .SH DESCRIPTION .B mtr-packet reads command requests from .I stdin, -each separated by a newline character, and responds with command replies -to -.I stdout\c -, also each separated by a newline character. The syntactic structure of +each separated by a newline character, and responds with command replies to +.IR stdout , +also each separated by a newline character. The syntactic structure of requests and replies are the same. The following format is used: .LP .RS @@ -23,28 +23,27 @@ requests and replies are the same. The following format is used: .I TOKEN is a unique integer value. The same value will be used as the .I TOKEN -for the response. This is necessary for associating replies with -requests, as commands may be completed in a different order than they are -requested. The invoker of +for the response. This is necessary for associating replies with requests, +as commands may be completed in a different order than they are requested. +The invoker of .B mtr-packet should always use the .I TOKEN value to determine which command request has completed. .LP .I COMMAND -is a string identifying the command request type. A common command -is -.B send-probe\c -, which will transmit one network probe. +is a string identifying the command request type. A common command is +.BR send-probe , +which will transmit one network probe. .LP .I ARGUMENT-NAME -strings and +strings and .I ARGUMENT-VALUE strings always come in pairs. It is a syntactic error to provide an .I ARGUMENT-NAME without a corresponding -.I ARGUMENT-VALUE\c -\&. Valid +.IR ARGUMENT-VALUE . +Valid .I ARGUMENT-NAME strings depend on the .I COMMAND @@ -52,40 +51,43 @@ being used. .SH REQUESTS .TP .B send-probe -Send a network probe to a particular IP address. An IP address must -be provided as an argument. +Send a network probe to a particular IP address. An IP address must be +provided as an argument. .B send-probe will reply with -.B reply\c -, -.B no-reply\c -, or -.B ttl-expired\c -\&. - +.BR reply , +.BR no-reply , +or +.BR ttl-expired . +.IP The following arguments may be used: - +.IP .B ip-4 .I IP-ADDRESS - +.HP 14 +.IP The Internet Protocol version 4 address to probe. - +.HP 7 +.IP .B timeout .I TIMEOUT-SECONDS - -The number of seconds to wait for a response to the probe before -discarding the probe as lost, and generating a +.HP 14 +.IP +The number of seconds to wait for a response to the probe before discarding +the probe as lost, and generating a .B no-reply command reply. - +.HP 7 +.IP .B ttl .I TIME-TO-LIVE - -The time-to-live value for the Internet Protocol packet header used -in constructing the probe. This value determines the number of -network hops through which the probe will travel before a response -is generated by an intermediate network host. - +.HP 14 +.IP +The time-to-live value for the Internet Protocol packet header used in +constructing the probe. This value determines the number of network hops +through which the probe will travel before a response is generated by an +intermediate network host. +.HP 7 .TP .B check-support Check for support for a particular feature in this version of @@ -93,103 +95,111 @@ Check for support for a particular feature in this version of and in this particular operating environment. .B check-support will reply with -.B feature-supported\c -\&. A +.BR feature-supported . +A .B feature argument is required. - +.HP 7 +.IP .B feature .I FEATURE-NAME - -The name of a feature requested. Some features which can be checked -are +.HP 14 +.IP +The name of a feature requested. Some features which can be checked are .B send-probe and -.B ip-4\c -\&. The feature +.BR ip-4 . +The feature .B version can be checked to retrieve the version of -.B mtr-packet\c -\&. - +.BR mtr-packet . .SH REPLIES .TP .B reply -The destination host received the +The destination host received the .B send-probe probe and replied. Arguments of the reply are the following: - +.HP 7 +.IP .B ip-4 .I IP-ADDRESS - +.HP 14 +.IP The Internet Protocol address of the host which replied to the probe. - +.HP 7 +.IP .B round-trip-time .I TIME - -The time which passed between the transmission of the probe and its -response. The time is provided as a integral number of -microseconds elapsed. - +.HP 14 +.IP +The time which passed between the transmission of the probe and its +response. The time is provided as a integral number of microseconds +elapsed. +.HP 7 .TP .B no-reply No response to the probe request was received before the timeout expired. .TP .B ttl-expired -The time-to-live value of the transmitted probe expired before -the probe arrived at its intended destination. Arguments of +The time-to-live value of the transmitted probe expired before the probe +arrived at its intended destination. Arguments of .B ttl-expired are: - +.HP 7 +.IP .B ip-4 .I IP-ADDRESS - -The Internet Protocol address of the host at which the time-to-live -value expired. - +.HP 14 +.IP +The Internet Protocol address of the host at which the time-to-live value +expired. +.HP 7 +.IP .B round-trip-time .I TIME - -The time which passed between the transmission of the probe and its -response. The time is provided as a integral number of -microseconds elapsed. - +.HP 14 +.IP +The time which passed between the transmission of the probe and its +response. The time is provided as a integral number of microseconds +elapsed. +.HP 7 .TP .B feature-support A reply to provided to .B check-support -indicating the availability of a particular feature. The argument -provided is: - +indicating the availability of a particular feature. The argument provided +is: +.HP 7 +.IP .B support .I PRESENT - -In most cases, the +.HP 14 +.IP +In most cases, the .I PRESENT value will be either -.B ok\c -, indicating the feature is supported, or -.B no\c -, indicating no support for the feature. - +.BR ok , +indicating the feature is supported, or +.BR no , +indicating no support for the feature. +.IP In the case that .B version is the requested -.I FEATURE-NAME\c -, the version of +.IR FEATURE-NAME , +the version of .B mtr-packet is provided as the .I PRESENT value. - +.HP 7 .SH EXAMPLE A controlling program may start .B mtr-packet as a child process and issue the following command on -.I stdin\c -: +.IR stdin : .LP .RS 42 send-probe ip-4 127.0.0.1 @@ -211,11 +221,11 @@ This indicates that the loopback address replied to the probe, and the round-trip time of the probe was 126 microseconds. .SH CONTACT INFORMATION .PP -For the latest version, see the mtr web page at +For the latest version, see the mtr web page at .UR http://\:www.\:bitwizard.\:nl/\:mtr/ .UE .PP -The mtr mailinglist was little used and is no longer active. +The mtr mailinglist was little used and is no longer active. .PP For patches, bug reports, or feature requests, please open an issue on GitHub at: