mirror of
https://git.proxmox.com/git/systemd
synced 2025-06-03 10:11:45 +00:00
172 lines
6.8 KiB
Groff
172 lines
6.8 KiB
Groff
'\" t
|
|
.TH "SD_JOURNAL_PRINT" "3" "" "systemd 219" "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)
|