<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>!"#$&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~</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
				&lt;topic&gt;" 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>
