From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_journal_print.xml | 276 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 man/sd_journal_print.xml (limited to 'man/sd_journal_print.xml') diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml new file mode 100644 index 0000000..7778234 --- /dev/null +++ b/man/sd_journal_print.xml @@ -0,0 +1,276 @@ + + + + + + + + sd_journal_print + systemd + + + + sd_journal_print + 3 + + + + sd_journal_print + sd_journal_printv + sd_journal_send + sd_journal_sendv + sd_journal_perror + SD_JOURNAL_SUPPRESS_LOCATION + sd_journal_print_with_location + sd_journal_printv_with_location + sd_journal_send_with_location + sd_journal_sendv_with_location + sd_journal_perror_with_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 + + + + int sd_journal_print_with_location + int priority + const char *file + const char *line + const char *func + const char *format + … + + + + int sd_journal_printv_with_location + int priority + const char *file + const char *line + const char *func + const char *format + va_list ap + + + + int sd_journal_send_with_location + const char *file + const char *line + const char *func + const char *format + … + + + + int sd_journal_sendv_with_location + const char *file + const char *line + const char *func + const struct iovec *iov + int n + + + + int sd_journal_perror_with_location + const char *file + const char *line + const char *func + 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. + Note that currently the resulting message will be truncated to LINE_MAX - 8. + 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 will 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. + + + sd_journal_print_with_location(), + sd_journal_printv_with_location(), sd_journal_send_with_location(), + sd_journal_sendv_with_location(), and + sd_journal_perror_with_location() are similar to their counterparts without + _with_location, but accept additional parameters to explicitly set the source file + name, function, and line. The arguments file and line must contain valid + journal entries including the variable name, e.g. CODE_FILE=src/foo.c and + CODE_LINE=666, while func must only contain the function name, i.e. the value + without CODE_FUNC=. These variants are primarily useful when writing custom wrappers, for + example in bindings for a different language. + + 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. + + These functions implement a client to the Native Journal Protocol. + + + + Return Value + + The ten functions 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 + + + + sd_journal_sendv() and sd_journal_sendv_with_location() + are "async signal safe" in the meaning of + signal-safety7. + + + sd_journal_print(), + sd_journal_printv(), + sd_journal_send(), + sd_journal_perror(), + and their counterparts with _with_location + are not async signal safe. + + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_stream_fd3, + syslog3, + perror3, + errno3, + systemd.journal-fields7, + signal7, + socket7 + + + + -- cgit v1.2.3