X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_journal_print.xml;h=e61a648703cdcb1825253f1894ef299d384dfd88;hp=71551f779a04843620e5bd307dffe5e360b39f17;hb=accdd018ede77ef1c057775396c18c73406cbcb4;hpb=cb07866b1b7c11e687a322d70dd9f9d73bbbe488 diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 71551f779..e61a64870 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -47,6 +47,8 @@ sd_journal_printv sd_journal_send sd_journal_sendv + sd_journal_perror + SD_JOURNAL_SUPPRESS_LOCATION Submit log entries to the journal @@ -80,6 +82,11 @@ int n + + int sd_journal_perror + const char* message + + @@ -95,14 +102,14 @@ or syslog3. The priority value is one of - LOG_EMERG, - LOG_ALERT, - LOG_CRIT, - LOG_ERR, - LOG_WARNING, - LOG_NOTICE, - LOG_INFO, - LOG_DEBUG, as defined in + LOG_EMERG, + LOG_ALERT, + LOG_CRIT, + LOG_ERR, + LOG_WARNING, + LOG_NOTICE, + LOG_INFO, + LOG_DEBUG, as defined in syslog.h, see syslog3 for details. It is recommended to use this call to @@ -113,32 +120,34 @@ sd_journal_printv() is similar to sd_journal_print() but takes a variable argument list encapsulated in an - object of type va_list (see + object of type va_list (see stdarg3 for more information) instead of the format string. It - is otherwise equivalent in behaviour. + is otherwise equivalent in behavior. sd_journal_send() may be used to submit structured log entries to the system journal. It takes a series of format strings, each immediately followed by their associated parameters, - terminated by a NULL. The strings passed should be of + terminated by NULL. The strings passed should be of the format VARIABLE=value. The - variable name must be in uppercase and consist only - of characters, numbers and underscores, and may not - begin with an underscore. The value can be of any size - and format. It is highly recommended to submit - text strings formatted in the UTF-8 character encoding - only, and submit binary fields only when formatting in - UTf-8 strings is not sensible. A number of well known - fields are defined, see + variable name must be in uppercase and consist only of + characters, numbers and underscores, and may not begin + with an underscore. (All assignments that do not + follow this syntax will be ignored.) The value can be + of any size and format. It is highly recommended to + submit text strings formatted in the UTF-8 character + encoding only, and submit binary fields only when + formatting in UTF-8 strings is not sensible. A number + of well known fields are defined, see systemd.journal-fields7 for details, but additional application defined fields - may be used. + may be used. A variable may be assigned more than one + value per entry. sd_journal_sendv() is similar to sd_journal_send() but - takes an array of struct iovec (as + takes an array of struct iovec (as defined in uio.h, see readv3 for details) instead of the format string. Each @@ -149,8 +158,23 @@ particularly useful to submit binary objects to the journal where that is necessary. + sd_journal_perror() is a + similar to + perror3 + and writes a message to the journal that consists of + the passed string, suffixed with ": " and a human + readable representation of the current error code + stored in + errno3. If + the message string is passed as NULL or empty string, + only the error string representation will be written, + prefixed with nothing. An additional journal field + ERRNO= is included in the entry containing the numeric + error code formatted as decimal string. The log + priority used is LOG_ERR (3). + Note that sd_journal_send() - is a wapper around + is a wrapper around sd_journal_sendv() to make it easier to use when only text strings shall be submitted. Also, the following two calls are @@ -165,20 +189,20 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( Note that these calls implicitly add fields for the source file, function name and code line where invoked. This is implemented with macros. If this is - not desired it can be turned off by defining + not desired, it can be turned off by defining SD_JOURNAL_SUPPRESS_LOCATION before including sd-journal.h. syslog3 - and and sd_journal_print() may - mostly be used interchangably + and sd_journal_print() may + largely be used interchangeably functionality-wise. However, note that log messages logged via the former take a different path to the journal server than the later, and hence global chronological ordering between the two streams cannot be guaranteed. Using sd_journal_print() has the - benefit of logging source code line, file names, and + benefit of logging source code line, filenames, and functions as meta data along all entries, and guaranteeing chronological ordering with structured log entries that are generated via @@ -190,8 +214,10 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( Return Value - The four calls return 0 on success or a - negative errno-style error code. + The four calls return 0 on success or a negative + errno-style error code. The + errno3 + variable itself is not altered. @@ -203,8 +229,7 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( sd_journal_sendv() interfaces are available as shared library, which can be compiled and linked to with the - libsystemd-journal - pkg-config1 + libsystemd-journal pkg-config1 file. @@ -216,6 +241,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( sd-journal3, sd_journal_stream_fd3, syslog3, + perror3, + errno3, systemd.journal-fields7