From: Lennart Poettering Date: Tue, 24 Jan 2023 15:39:02 +0000 (+0100) Subject: man: clarify that MESSAGE= should not appear more than once in the same journal entry X-Git-Tag: v253-rc1~8 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=98a13530145fa4b663c4402689717deccd2080ea;p=thirdparty%2Fsystemd.git man: clarify that MESSAGE= should not appear more than once in the same journal entry One would think this was clear already, but apparently it's not clear enough, hence let's be more explicit. Fixes: #26175 --- diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index caedb6e4ae0..d9e3d5760ce 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -25,11 +25,15 @@ Entries in the journal (as written by systemd-journald.service8) - resemble a UNIX process environment block in syntax but with fields that may include binary data. - Primarily, fields are formatted UTF-8 text strings, and binary encoding is used only where formatting as - UTF-8 text strings makes little sense. New fields may freely be defined by applications, but a few fields - have special meanings. All fields with special meanings are optional. In some cases, fields may appear - more than once per entry. + resemble a UNIX process environment block in syntax but with field values that may include binary data, + and with non-unique field names permitted. Primarily, field values are formatted UTF-8 text strings — + binary encoding is used only where formatting as UTF-8 text strings makes little sense. New fields may + freely be defined by applications, but a few fields have special meanings, which are listed + below. Typically, fields may only appear once per log entry, however there are special exceptions: some + fields may appear more than once per entry, in which case this is explicitly mentioned below. Even though + the logging subsystem makes no restrictions on which fields to accept non-unique values for, it is + strongly recommended to avoid relying on this for the fields listed below (except where listed otherwise, + as mentioned) in order to avoid unnecessary incompatibilities with other applications. @@ -42,10 +46,13 @@ MESSAGE= - The human-readable message string for this entry. This - is supposed to be the primary text shown to the user. It is - usually not translated (but might be in some cases), and is - not supposed to be parsed for metadata. + The human-readable message string for this entry. This is supposed to be the primary text + shown to the user. It is usually not translated (but might be in some cases), and is not supposed + to be parsed for metadata. In order to encode multiple lines in a single log entry, separate them + by newline characters (ASCII code 10), but encode them as a single MESSAGE= + field. Do not add multiple values of this field type to the same entry (also see above), as + consuming applications generally do not expect this and are unlikely to show all values in that + case.