From eb4b7726f3d9603da6a03029e67024e275c067c6 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 20 May 2017 17:21:57 -0400 Subject: ./tools/notsd-move --- src/libsystemd/sd_journal_print.xml | 246 ++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 src/libsystemd/sd_journal_print.xml (limited to 'src/libsystemd/sd_journal_print.xml') diff --git a/src/libsystemd/sd_journal_print.xml b/src/libsystemd/sd_journal_print.xml new file mode 100644 index 0000000000..2d8dd635aa --- /dev/null +++ b/src/libsystemd/sd_journal_print.xml @@ -0,0 +1,246 @@ + + + + + + + + + sd_journal_print + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_print + 3 + + + + sd_journal_print + sd_journal_printv + sd_journal_send + sd_journal_sendv + sd_journal_perror + SD_JOURNAL_SUPPRESS_LOCATION + Submit log entries to the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_print + int priority + const char *format + ... + + + + int sd_journal_printv + int priority + const char *format + va_list ap + + + + int sd_journal_send + const char *format + ... + + + + int sd_journal_sendv + const struct iovec *iov + int n + + + + int sd_journal_perror + const char *message + + + + + + + Description + + sd_journal_print() may be used to submit simple, plain text log entries to the system + journal. The first argument is a priority value. This is followed by a format string and its parameters, similar to + printf3 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 + syslog.h, see syslog3 for details. It is + recommended to use this call to submit log messages in the application locale or system locale and in UTF-8 format, + but no such restrictions are enforced. Note that log messages written using this function are generally not + expected to end in a new-line character. However, as all trailing whitespace (including spaces, new-lines, + tabulators and carriage returns) are automatically stripped from the logged string, it is acceptable to specify one + (or more). Empty lines (after trailing whitespace removal) are suppressed. On non-empty lines, leading whitespace + (as well as inner whitespace) is left unmodified. + + sd_journal_printv() is similar to + sd_journal_print() but takes a variable + argument list encapsulated in an object of type + va_list (see + stdarg3 + for more information) instead of the format string. It 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 + 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. (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. A variable may be assigned more than one value per + entry. If this function is used, trailing whitespace is automatically removed from each formatted field. + + sd_journal_sendv() is similar to sd_journal_send() but takes an + array of struct iovec (as defined in uio.h, see readv3 for details) + instead of the format string. Each structure should reference one field of the entry to submit. The second argument + specifies the number of structures in the array. sd_journal_sendv() is particularly useful to + submit binary objects to the journal where that is necessary. Note that this function wil not strip trailing + whitespace of the passed fields, but passes the specified data along unmodified. This is different from both + sd_journal_print() and sd_journal_send() described above, which are based + on format strings, and do strip trailing whitespace. + + 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 + wrapper around sd_journal_sendv() to make it + easier to use when only text strings shall be submitted. Also, the + following two calls are mostly equivalent: + + sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); + +sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), + "PRIORITY=%i", LOG_INFO, + NULL); + + 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 SD_JOURNAL_SUPPRESS_LOCATION before including + sd-journal.h. + + syslog3 + 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, filenames, and + functions as metadata along all entries, and + guaranteeing chronological ordering with structured + log entries that are generated via + sd_journal_send(). Using + syslog() has the benefit of being + more portable. + + + + Return Value + + The four calls return 0 on success or a negative errno-style + error code. The + errno3 + variable itself is not altered. + + If + systemd-journald8 + is not running (the socket is not present), those functions do + nothing, and also return 0. + + + + Thread safety + All functions listed here are thread-safe and may be called in parallel from multiple threads. + + sd_journal_sendv() is "async signal safe" in the meaning of + signal7. + + + sd_journal_print, + sd_journal_printv, + sd_journal_send, and + sd_journal_perror are + not async signal safe. + + + + Notes + + The sd_journal_print(), + sd_journal_printv(), + sd_journal_send() and + sd_journal_sendv() interfaces are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_stream_fd3, + syslog3, + perror3, + errno3, + systemd.journal-fields7, + signal7, + socket7 + + + + -- cgit v1.2.3-54-g00ecf