From 4160043a0fac8b812905b7502ce34adf3af538f1 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 6 Sep 2016 02:27:18 -0400 Subject: move man pages to appropriate directories --- src/libsystemd/sd_journal_print.xml | 260 ++++++++++++++++++++++++++++++++++++ 1 file changed, 260 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..17fdc9c1f2 --- /dev/null +++ b/src/libsystemd/sd_journal_print.xml @@ -0,0 +1,260 @@ + + + + + + + + + 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. + + 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. + + 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. + + 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. + + + + Async signal safety + 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