1SD_JOURNAL_PRINT(3)            sd_journal_print            SD_JOURNAL_PRINT(3)
2
3
4

NAME

6       sd_journal_print, sd_journal_printv, sd_journal_send, sd_journal_sendv,
7       sd_journal_perror, SD_JOURNAL_SUPPRESS_LOCATION,
8       sd_journal_print_with_location, sd_journal_printv_with_location,
9       sd_journal_send_with_location, sd_journal_sendv_with_location,
10       sd_journal_perror_with_location - Submit log entries to the journal
11

SYNOPSIS

13       #include <systemd/sd-journal.h>
14
15       int sd_journal_print(int priority, const char *format, ...);
16
17       int sd_journal_printv(int priority, const char *format, va_list ap);
18
19       int sd_journal_send(const char *format, ...);
20
21       int sd_journal_sendv(const struct iovec *iov, int n);
22
23       int sd_journal_perror(const char *message);
24
25       int sd_journal_print_with_location(const char *file, const char *line,
26                                          const char *func, int priority,
27                                          const char *format, ...);
28
29       int sd_journal_printv_with_location(int priority, const char *file,
30                                           const char *line, const char *func,
31                                           const char *format, va_list ap);
32
33       int sd_journal_send_with_location(const char *file, const char *line,
34                                         const char *func, const char *format,
35                                         ...);
36
37       int sd_journal_sendv_with_location(const char *file, const char *line,
38                                          const char *func,
39                                          const struct iovec *iov, int n);
40
41       int sd_journal_perror_with_location(const char *file, const char *line,
42                                           const char *func,
43                                           const char *message);
44

DESCRIPTION

46       sd_journal_print() may be used to submit simple, plain text log entries
47       to the system journal. The first argument is a priority value. This is
48       followed by a format string and its parameters, similar to printf(3) or
49       syslog(3). Note that currently the resulting message will be truncated
50       to LINE_MAX - 8. The priority value is one of LOG_EMERG, LOG_ALERT,
51       LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG, as
52       defined in syslog.h, see syslog(3) for details. It is recommended to
53       use this call to submit log messages in the application locale or
54       system locale and in UTF-8 format, but no such restrictions are
55       enforced. Note that log messages written using this function are
56       generally not expected to end in a new-line character. However, as all
57       trailing whitespace (including spaces, new-lines, tabulators and
58       carriage returns) are automatically stripped from the logged string, it
59       is acceptable to specify one (or more). Empty lines (after trailing
60       whitespace removal) are suppressed. On non-empty lines, leading
61       whitespace (as well as inner whitespace) is left unmodified.
62
63       sd_journal_printv() is similar to sd_journal_print() but takes a
64       variable argument list encapsulated in an object of type va_list (see
65       stdarg(3) for more information) instead of the format string. It is
66       otherwise equivalent in behavior.
67
68       sd_journal_send() may be used to submit structured log entries to the
69       system journal. It takes a series of format strings, each immediately
70       followed by their associated parameters, terminated by NULL. The
71       strings passed should be of the format "VARIABLE=value". The variable
72       name must be in uppercase and consist only of characters, numbers and
73       underscores, and may not begin with an underscore. (All assignments
74       that do not follow this syntax will be ignored.) The value can be of
75       any size and format. It is highly recommended to submit text strings
76       formatted in the UTF-8 character encoding only, and submit binary
77       fields only when formatting in UTF-8 strings is not sensible. A number
78       of well-known fields are defined, see systemd.journal-fields(7) for
79       details, but additional application defined fields may be used. A
80       variable may be assigned more than one value per entry. If this
81       function is used, trailing whitespace is automatically removed from
82       each formatted field.
83
84       sd_journal_sendv() is similar to sd_journal_send() but takes an array
85       of struct iovec (as defined in uio.h, see readv(3) for details) instead
86       of the format string. Each structure should reference one field of the
87       entry to submit. The second argument specifies the number of structures
88       in the array.  sd_journal_sendv() is particularly useful to submit
89       binary objects to the journal where that is necessary. Note that this
90       function will not strip trailing whitespace of the passed fields, but
91       passes the specified data along unmodified. This is different from both
92       sd_journal_print() and sd_journal_send() described above, which are
93       based on format strings, and do strip trailing whitespace.
94
95       sd_journal_perror() is a similar to perror(3) and writes a message to
96       the journal that consists of the passed string, suffixed with ": " and
97       a human-readable representation of the current error code stored in
98       errno(3). If the message string is passed as NULL or empty string, only
99       the error string representation will be written, prefixed with nothing.
100       An additional journal field ERRNO= is included in the entry containing
101       the numeric error code formatted as decimal string. The log priority
102       used is LOG_ERR (3).
103
104       Note that sd_journal_send() is a wrapper around sd_journal_sendv() to
105       make it easier to use when only text strings shall be submitted. Also,
106       the following two calls are mostly equivalent:
107
108           sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid());
109
110           sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(),
111                           "PRIORITY=%i", LOG_INFO,
112                           NULL);
113
114       Note that these calls implicitly add fields for the source file,
115       function name and code line where invoked. This is implemented with
116       macros. If this is not desired, it can be turned off by defining
117       SD_JOURNAL_SUPPRESS_LOCATION before including sd-journal.h.
118
119       sd_journal_print_with_location(), sd_journal_printv_with_location(),
120       sd_journal_send_with_location(), sd_journal_sendv_with_location(), and
121       sd_journal_perror_with_location() are similar to their counterparts
122       without "_with_location", but accept additional parameters to
123       explicitly set the source file name, function, and line. Those
124       arguments must contain valid journal entries including the variable
125       name, e.g.  "CODE_FILE=src/foo.c", "CODE_LINE=666", "CODE_FUNC=myfunc".
126       These variants are primarily useful when writing custom wrappers, for
127       example in bindings for a different language.
128
129       syslog(3) and sd_journal_print() may largely be used interchangeably
130       functionality-wise. However, note that log messages logged via the
131       former take a different path to the journal server than the later, and
132       hence global chronological ordering between the two streams cannot be
133       guaranteed. Using sd_journal_print() has the benefit of logging source
134       code line, filenames, and functions as metadata along all entries, and
135       guaranteeing chronological ordering with structured log entries that
136       are generated via sd_journal_send(). Using syslog() has the benefit of
137       being more portable.
138
139       These functions implement a client to the Native Journal Protocol[1].
140

RETURN VALUE

142       The ten functions return 0 on success or a negative errno-style error
143       code. The errno(3) variable itself is not altered.
144
145       If systemd-journald(8) is not running (the socket is not present),
146       those functions do nothing, and also return 0.
147

THREAD SAFETY

149       All functions listed here are thread-safe and may be called in parallel
150       from multiple threads.
151
152       sd_journal_sendv() and sd_journal_sendv_with_location() are "async
153       signal safe" in the meaning of signal-safety(7).
154
155       sd_journal_print(), sd_journal_printv(), sd_journal_send(),
156       sd_journal_perror(), and their counterparts with "_with_location" are
157       not async signal safe.
158

NOTES

160       These APIs are implemented as a shared library, which can be compiled
161       and linked to with the libsystemd pkg-config(1) file.
162

SEE ALSO

164       systemd(1), sd-journal(3), sd_journal_stream_fd(3), syslog(3),
165       perror(3), errno(3), systemd.journal-fields(7), signal(7), socket(7)
166

NOTES

168        1. Native Journal Protocol
169           https://systemd.io/JOURNAL_NATIVE_PROTOCOL
170
171
172
173systemd 249                                                SD_JOURNAL_PRINT(3)
Impressum