mirror of
https://github.com/eclipse-mosquitto/mosquitto.git
synced 2026-02-08 13:41:58 +08:00
238 lines
11 KiB
XML
238 lines
11 KiB
XML
<refsect1 id='outputformat' xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Output Format</title>
|
|
<para>
|
|
There are three ways of formatting the printed output. In all cases a
|
|
new-line character is appended for each message received unless the
|
|
<option>-N</option> argument is given.
|
|
</para>
|
|
<para>
|
|
Payload-only is the default output format and will print the payload
|
|
exactly as it is received.
|
|
</para>
|
|
<para>
|
|
Verbose mode is activated with <option>-v</option> and prints the
|
|
message topic and the payload, separated by a space.
|
|
</para>
|
|
<para>
|
|
The final option is formatted output, which allows the user to
|
|
define a custom output format. The behaviour is controlled with
|
|
the <option>-F format-string</option> option. The format string is
|
|
a free text string where interpreted sequences are replaced by
|
|
different parameters. The available interpreted sequences are
|
|
described below.
|
|
</para>
|
|
<para>
|
|
Three characters are used to start an interpreted sequence:
|
|
<option>%</option>, <option>@</option> and <option>\</option>.
|
|
Sequences starting with <option>%</option> are either parameters
|
|
related to the MQTT message being printed, or are helper sequences
|
|
to avoid the need to type long date format strings for example.
|
|
Sequences starting with <option>@</option> are passed to the
|
|
<citerefentry><refentrytitle><link xlink:href="https://linux.die.net/man/3/strftime">strftime</link></refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
function (with the @ replaced with a % - note that only the
|
|
character immediately after the @ is passed to strftime). This
|
|
allows the construction of a wide variety of time based outputs.
|
|
The output options for strftime vary from platform to platform, so
|
|
please check what is available for your platform. One extension to
|
|
strftime is provided which is <option>@N</option>, which can be
|
|
used to obtain the number of nanoseconds passed in the current
|
|
second. The resolution of this option varies depending on the
|
|
platform. The final sequence character is <option>\</option>,
|
|
which is used to input some characters that would otherwise be
|
|
difficult to enter.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>Flag characters</title>
|
|
<para>
|
|
The parameters %A, %C, %d, %E, %F, %f, %I, %l, %m, %p, %R, %S, %t,
|
|
%x, and %X can have optional flags immediately after the %
|
|
character.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>0</option></term>
|
|
<listitem>
|
|
<para>
|
|
The value should be zero padded. This applies to the
|
|
parameters %A, %E, %d, %F, %f, %l, %m, %S, %X, and %x.
|
|
It will be ignored for other parameters. If used with
|
|
the <option>-</option> flag, the <option>0</option>
|
|
flag will be ignored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-</option></term>
|
|
<listitem>
|
|
<para>
|
|
The value will be left aligned to the field width,
|
|
padded with blanks. The default is right alignment, with
|
|
either 0 or blank padding.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Field width</title>
|
|
<para>
|
|
Some of the MQTT related parameters can be formatted with an
|
|
option to set their field width in a similar way to regular
|
|
printf style formats, i.e. this sets the minimum width when
|
|
printing this parameter. If the output length is smaller than
|
|
this width, the field will be padded to meet this width. This
|
|
applies to the options %A, %C, %d, %E, %F, %f, %I, %l, %m, %p,
|
|
%R, %S, %t, %x, %X.
|
|
</para>
|
|
<para>
|
|
For example <option>%10t</option> would set the minimum topic
|
|
field width to 10 characters.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Maximum width</title>
|
|
<para>
|
|
Some of the MQTT related parameters can be formatted with an
|
|
option to set a maximum field width in a similar way to regular
|
|
printf style formats, for example <option>%.20t</option> for a
|
|
maximum width of 20. This applies to the options %C, %I, %R, %t.
|
|
</para>
|
|
<para>
|
|
For example <option>%10.10t</option> would set the minimum topic
|
|
field width to 10 characters, and the maximum topic width to
|
|
10 characters, i.e. the field will always be exactly 10
|
|
characters long.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Hexadecimal binary field width</title>
|
|
<para>
|
|
The %x and %X parameters output the payload as a single
|
|
hexadecimal string by default. It is also possible to split the
|
|
hexadecimal payload into fields by a chosen length of nibbles.
|
|
For example, <option>%.2x</option> would split the payload into
|
|
two nibble or one byte values, separated by spaces and might produce
|
|
an output of <computeroutput>18 83</computeroutput>.
|
|
</para>
|
|
<para>
|
|
The separator character is a space by default, but can be changed
|
|
to one of <option>!"#$&'()*+,-./:;<=>?@[\]^_`{|}~</option>
|
|
by adding that character after the binary field width. For example
|
|
<option>%.2:x</option> might produce an output of
|
|
<computeroutput>18:83</computeroutput>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Floating point number printing consideration</title>
|
|
<para>
|
|
The output format supports only the IEEE 754 floating point standard
|
|
as described in Annex F of ISO/IEC 9899:1999. Don't try to use %f or
|
|
%d if the platform of the publisher uses a different floating point
|
|
representation standard than IEEE 754 or you will get invalid data.
|
|
If you are unsure what floating representation your platform is
|
|
using, then it is most likely IEEE 754. If you get malformed or
|
|
unexpected values, check if the floating point number in the payload
|
|
from the publisher is encoded in IEEE 754.
|
|
</para>
|
|
<para>
|
|
If want to print floats, make sure you only subscribe to topics that
|
|
send only IEEE 754 formatted floats. The processing is very strict
|
|
about floats and if anything that is not a float is received, an
|
|
error message will be printed.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>MQTT related parameters</title>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para><option>%%</option> a literal %.</para></listitem>
|
|
<listitem><para><option>%A</option> the MQTT v5 topic-alias property, if present.</para></listitem>
|
|
<listitem><para><option>%C</option> the MQTT v5 content-type property, if present.</para></listitem>
|
|
<listitem><para><option>%D</option> the MQTT v5 correlation-data property, if present. Note that this
|
|
property is specified as binary data, so may produce non-printable characters.</para></listitem>
|
|
<listitem><para><option>%d</option> the payload treated as an 8 byte IEEE 754 float (double).</para></listitem>
|
|
<listitem><para><option>%E</option> the MQTT v5 message-expiry-interval property, if present.</para></listitem>
|
|
<listitem><para><option>%F</option> the MQTT v5 payload-format-indicator property, if present.</para></listitem>
|
|
<listitem><para><option>%f</option> the payload treated as an 4 byte IEEE 754 float.</para></listitem>
|
|
<listitem><para><option>%l</option> the length of the payload in bytes.</para></listitem>
|
|
<listitem><para><option>%m</option> the message id (only relevant for messages with QoS>0).</para></listitem>
|
|
<listitem><para><option>%P</option> the MQTT v5 user-property property, if present. This will be printed in the
|
|
form key:value. It is possible for any number of user properties to be attached to a message, and to
|
|
have duplicate keys.</para></listitem>
|
|
<listitem><para><option>%p</option> the payload raw bytes (may produce non-printable characters depending on the payload).</para></listitem>
|
|
<listitem><para><option>%q</option> the message QoS.</para></listitem>
|
|
<listitem><para><option>%R</option> the MQTT v5 response-topic property, if present.</para></listitem>
|
|
<listitem><para><option>%r</option> the retained flag for the message.</para></listitem>
|
|
<listitem><para><option>%S</option> the MQTT v5 subscription-identifier property, if present.</para></listitem>
|
|
<listitem><para><option>%t</option> the message topic.</para></listitem>
|
|
<listitem><para><option>%x</option> the payload with each byte as a hexadecimal number (lower case).</para></listitem>
|
|
<listitem><para><option>%X</option> the payload with each byte as a hexadecimal number (upper case).</para></listitem>
|
|
</itemizedlist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Helpers</title>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para><option>%I</option> ISO-8601 format date and time, e.g. 2016-08-10T09:47:38+0100</para></listitem>
|
|
<listitem><para><option>%j</option> JSON output of message
|
|
parameters and timestamp, with a quoted and escaped
|
|
payload. For example
|
|
<code>{"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello world"}</code>
|
|
</para></listitem>
|
|
<listitem><para><option>%J</option> JSON output of message
|
|
parameters and timestamp, with a non-quoted and
|
|
non-escaped payload - this means the payload must
|
|
itself be valid JSON. For example:
|
|
<code>{"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}</code>.
|
|
</para>
|
|
<para>
|
|
If the payload is not valid JSON, then the error message
|
|
"Error: Message payload is not valid JSON on topic
|
|
<topic>" will be printed to stderr.
|
|
</para></listitem>
|
|
|
|
<listitem><para><option>%U</option> Unix timestamp with nanoseconds, e.g. 1470818943.786368637</para></listitem>
|
|
</itemizedlist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Time related parameters</title>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para><option>@@</option> a literal @.</para></listitem>
|
|
<listitem><para><option>@X</option> pass the character represented
|
|
by <option>X</option> to the strftime function as
|
|
<option>%X</option>. The options supported are platform
|
|
dependent.</para></listitem>
|
|
<listitem><para><option>@N</option> the number of nanoseconds that
|
|
have passed in the current second, with varying timing
|
|
resolution depending on platform.</para></listitem>
|
|
</itemizedlist>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Escape characters</title>
|
|
<itemizedlist mark="circle">
|
|
<listitem><para><option>\\</option> a literal \.</para></listitem>
|
|
<listitem><para><option>\0</option> a null character. Can be used
|
|
to separate different parameters that may contain spaces
|
|
(e.g. topic, payload) so that processing with tools such as
|
|
<citerefentry><refentrytitle><link xlink:href="https://linux.die.net/man/1/xargs">xargs</link></refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
is easier.</para></listitem>
|
|
<listitem><para><option>\a</option> alert/bell.</para></listitem>
|
|
<listitem><para><option>\e</option> the escape sequence, which can
|
|
be used with ANSI colour codes to provide coloured output
|
|
for example.</para></listitem>
|
|
<listitem><para><option>\n</option> end of line.</para></listitem>
|
|
<listitem><para><option>\r</option> carriage return.</para></listitem>
|
|
<listitem><para><option>\t</option> horizontal tab.</para></listitem>
|
|
<listitem><para><option>\v</option> vertical tab.</para></listitem>
|
|
</itemizedlist>
|
|
</refsect2>
|
|
</refsect1>
|