path: root/upstream/archlinux/man3/sd_journal_print.3

'\" 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