path: root/man/sd_journal_print.3

'\" t
.TH "SD_JOURNAL_PRINT" "3" "" "systemd 221" "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 \- 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" ");"
.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)\&. 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\&.
.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\&.
.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\&.
.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 SD_JOURNAL_SUPPRESS_LOCATION before including
sd\-journal\&.h\&.
.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\&.
.SH "RETURN VALUE"
.PP
The four calls 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 "ASYNC SIGNAL SAFETY"
.PP
\fBsd_journal_sendv()\fR
is "async signal safe" in the meaning of
\fBsignal\fR(7)\&.
.PP
\fBsd_journal_print\fR,
\fBsd_journal_printv\fR,
\fBsd_journal_send\fR, and
\fBsd_journal_perror\fR
are not async signal safe\&.
.SH "NOTES"
.PP
The
\fBsd_journal_print()\fR,
\fBsd_journal_printv()\fR,
\fBsd_journal_send()\fR
and
\fBsd_journal_sendv()\fR
interfaces are available as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.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)