Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 238 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/sd_journal_print.3 b/upstream/debian-unstable/man3/sd_journal_print.3
new file mode 100644
index 00000000..890816bb
--- /dev/null
+++ b/upstream/debian-unstable/man3/sd_journal_print.3
@@ -0,0 +1,238 @@
+'\" t
+.TH "SD_JOURNAL_PRINT" "3" "" "systemd 255" "sd_journal_print"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+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
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <systemd/sd\-journal\&.h>
+.fi
+.ft
+.HP \w'int\ sd_journal_print('u
+.BI "int sd_journal_print(int\ " "priority" ", const\ char\ *" "format" ", \&...);"
+.HP \w'int\ sd_journal_printv('u
+.BI "int sd_journal_printv(int\ " "priority" ", const\ char\ *" "format" ", va_list\ " "ap" ");"
+.HP \w'int\ sd_journal_send('u
+.BI "int sd_journal_send(const\ char\ *" "format" ", \&...);"
+.HP \w'int\ sd_journal_sendv('u
+.BI "int sd_journal_sendv(const\ struct\ iovec\ *" "iov" ", int\ " "n" ");"
+.HP \w'int\ sd_journal_perror('u
+.BI "int sd_journal_perror(const\ char\ *" "message" ");"
+.HP \w'int\ sd_journal_print_with_location('u
+.BI "int sd_journal_print_with_location(int\ " "priority" ", const\ char\ *" "file" ", const\ char\ *" "line" ", const\ char\ *" "func" ", const\ char\ *" "format" ", \&...);"
+.HP \w'int\ sd_journal_printv_with_location('u
+.BI "int sd_journal_printv_with_location(int\ " "priority" ", const\ char\ *" "file" ", const\ char\ *" "line" ", const\ char\ *" "func" ", const\ char\ *" "format" ", va_list\ " "ap" ");"
+.HP \w'int\ sd_journal_send_with_location('u
+.BI "int sd_journal_send_with_location(const\ char\ *" "file" ", const\ char\ *" "line" ", const\ char\ *" "func" ", const\ char\ *" "format" ", \&...);"
+.HP \w'int\ sd_journal_sendv_with_location('u
+.BI "int sd_journal_sendv_with_location(const\ char\ *" "file" ", const\ char\ *" "line" ", const\ char\ *" "func" ", const\ struct\ iovec\ *" "iov" ", int\ " "n" ");"
+.HP \w'int\ sd_journal_perror_with_location('u
+.BI "int sd_journal_perror_with_location(const\ char\ *" "file" ", const\ char\ *" "line" ", const\ char\ *" "func" ", const\ char\ *" "message" ");"
+.SH "DESCRIPTION"
+.PP
+\fBsd_journal_print()\fR
+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
+\fBprintf\fR(3)
+or
+\fBsyslog\fR(3)\&. Note that currently the resulting message will be truncated to
+\fBLINE_MAX \- 8\fR\&. The priority value is one of
+\fBLOG_EMERG\fR,
+\fBLOG_ALERT\fR,
+\fBLOG_CRIT\fR,
+\fBLOG_ERR\fR,
+\fBLOG_WARNING\fR,
+\fBLOG_NOTICE\fR,
+\fBLOG_INFO\fR,
+\fBLOG_DEBUG\fR, as defined in
+syslog\&.h, see
+\fBsyslog\fR(3)
+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\&.
+.PP
+\fBsd_journal_printv()\fR
+is similar to
+\fBsd_journal_print()\fR
+but takes a variable argument list encapsulated in an object of type
+\fIva_list\fR
+(see
+\fBstdarg\fR(3)
+for more information) instead of the format string\&. It is otherwise equivalent in behavior\&.
+.PP
+\fBsd_journal_send()\fR
+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
+\fBNULL\fR\&. 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
+\fBsystemd.journal-fields\fR(7)
+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\&.
+.PP
+\fBsd_journal_sendv()\fR
+is similar to
+\fBsd_journal_send()\fR
+but takes an array of
+\fIstruct iovec\fR
+(as defined in
+uio\&.h, see
+\fBreadv\fR(3)
+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\&.
+\fBsd_journal_sendv()\fR
+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
+\fBsd_journal_print()\fR
+and
+\fBsd_journal_send()\fR
+described above, which are based on format strings, and do strip trailing whitespace\&.
+.PP
+\fBsd_journal_perror()\fR
+is a similar to
+\fBperror\fR(3)
+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
+\fBerrno\fR(3)\&. If the message string is passed as
+\fBNULL\fR
+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
+\fBLOG_ERR\fR
+(3)\&.
+.PP
+Note that
+\fBsd_journal_send()\fR
+is a wrapper around
+\fBsd_journal_sendv()\fR
+to make it easier to use when only text strings shall be submitted\&. Also, the following two calls are mostly equivalent:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+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);
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+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
+\fBSD_JOURNAL_SUPPRESS_LOCATION\fR
+before including
+sd\-journal\&.h\&.
+.PP
+\fBsd_journal_print_with_location()\fR,
+\fBsd_journal_printv_with_location()\fR,
+\fBsd_journal_send_with_location()\fR,
+\fBsd_journal_sendv_with_location()\fR, and
+\fBsd_journal_perror_with_location()\fR
+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\&.
+.PP
+\fBsyslog\fR(3)
+and
+\fBsd_journal_print()\fR
+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
+\fBsd_journal_print()\fR
+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
+\fBsd_journal_send()\fR\&. Using
+\fBsyslog()\fR
+has the benefit of being more portable\&.
+.PP
+These functions implement a client to the
+\m[blue]\fBNative Journal Protocol\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.SH "RETURN VALUE"
+.PP
+The ten functions return 0 on success or a negative errno\-style error code\&. The
+\fBerrno\fR(3)
+variable itself is not altered\&.
+.PP
+If
+\fBsystemd-journald\fR(8)
+is not running (the socket is not present), those functions do nothing, and also return 0\&.
+.SH "THREAD SAFETY"
+.PP
+All functions listed here are thread\-safe and may be called in parallel from multiple threads\&.
+.PP
+\fBsd_journal_sendv()\fR
+and
+\fBsd_journal_sendv_with_location()\fR
+are "async signal safe" in the meaning of
+\fBsignal-safety\fR(7)\&.
+.PP
+\fBsd_journal_print()\fR,
+\fBsd_journal_printv()\fR,
+\fBsd_journal_send()\fR,
+\fBsd_journal_perror()\fR, and their counterparts with
+"_with_location"
+are not async signal safe\&.
+.SH "NOTES"
+.PP
+Functions described here are available as a shared library, which can be compiled against and linked to with the
+\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
+file\&.
+.PP
+The code described here uses
+\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
+\fBsetenv\fR(3)
+from a parallel thread\&. It is recommended to only do calls to
+\fBsetenv()\fR
+from an early phase of the program when no other threads have been started\&.
+.SH "HISTORY"
+.PP
+\fBsd_journal_print()\fR,
+\fBsd_journal_printv()\fR,
+\fBsd_journal_send()\fR, and
+\fBsd_journal_sendv()\fR
+were added in version 187\&.
+.PP
+\fBsd_journal_perror()\fR
+was added in version 188\&.
+.PP
+\fBsd_journal_print_with_location()\fR,
+\fBsd_journal_printv_with_location()\fR,
+\fBsd_journal_send_with_location()\fR,
+\fBsd_journal_sendv_with_location()\fR, and
+\fBsd_journal_perror_with_location()\fR
+were added in version 246\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsd-journal\fR(3),
+\fBsd_journal_stream_fd\fR(3),
+\fBsyslog\fR(3),
+\fBperror\fR(3),
+\fBerrno\fR(3),
+\fBsystemd.journal-fields\fR(7),
+\fBsignal\fR(7),
+\fBsocket\fR(7)
+.SH "NOTES"
+.IP " 1." 4
+Native Journal Protocol
+.RS 4
+\%https://systemd.io/JOURNAL_NATIVE_PROTOCOL
+.RE