diff --git a/Makefile.am b/Makefile.am
index 540eb80f10..6cf776031b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -504,7 +504,9 @@ MANPAGES = \
man/systemd.preset.5 \
man/sd-id128.7 \
man/sd_id128_to_string.3 \
- man/sd_id128_randomize.3
+ man/sd_id128_randomize.3 \
+ man/sd-journal.7 \
+ man/sd_journal_print.3
MANPAGES_ALIAS = \
man/reboot.8 \
@@ -541,7 +543,10 @@ MANPAGES_ALIAS = \
man/sd_id128_equal.7 \
man/sd_id128_from_string.3 \
man/sd_id128_get_machine.3 \
- man/sd_id128_get_boot.3
+ man/sd_id128_get_boot.3 \
+ man/sd_journal_printv.3 \
+ man/sd_journal_send.3 \
+ man/sd_journal_sendv.3
man/reboot.8: man/halt.8
man/poweroff.8: man/halt.8
@@ -578,6 +583,9 @@ man/sd_id128_equal.7: man/sd-id128.7
man/sd_id128_from_string.3: man/sd_id128_to_string.3
man/sd_id128_get_machine.3: man/sd_id128_randomize.3
man/sd_id128_get_boot.3: man/sd_id128_randomize.3
+man/sd_journal_printv.3: man/sd_journal_print.3
+man/sd_journal_send.3: man/sd_journal_print.3
+man/sd_journal_sendv.3: man/sd_journal_print.3
XML_FILES = \
${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}}
diff --git a/man/sd-journal.xml b/man/sd-journal.xml
new file mode 100644
index 0000000000..0485458535
--- /dev/null
+++ b/man/sd-journal.xml
@@ -0,0 +1,125 @@
+
+
+
+
+
+
+
+
+ sd-journal
+ systemd
+
+
+
+ Developer
+ Lennart
+ Poettering
+ lennart@poettering.net
+
+
+
+
+
+ sd-journal
+ 7
+
+
+
+ sd-journal
+ APIs for submitting and querying log entries to and from the Journal
+
+
+
+
+ #include <systemd/sd-journal.h>
+
+
+
+ pkg-config --cflags --libs libsystemd-journal
+
+
+
+
+
+ Description
+
+ sd-journal.h provides APIs
+ to submit and query log entries. The APIs exposed act
+ both as client for the
+ systemd-journald.service8
+ journal service and as parser for the journal files
+ on disk.
+
+
+ See
+ sd_journal_print3,
+ sd_journal_stream_fd3,
+ sd_journal_open3,
+ sd_journal_next3,
+ sd_journal_get_realtime_usec3,
+ sd_journal_add_match3,
+ sd_journal_seek_head3,
+ sd_journal_get_cursor3,
+ sd_journal_cutoff_realtime_usec3
+ and
+ sd_journal_get_fd3
+ for more information about the functions
+ implemented.
+
+ Command line access for submitting entries to
+ the journal is available with the
+ systemd-cat1
+ tool. Command line access for querying entries from
+ the journal is available with the
+ journalctl1
+ tool.
+
+
+
+ Notes
+
+ These APIs are implemented as shared library,
+ which can be compiled and linked to with the
+ libsystemd-journal
+ pkg-config1
+ file.
+
+
+
+ See Also
+
+ systemd1,
+ sd_journal_print3,
+ sd_journal_stream_fd3,
+ sd_journal_open3,
+ sd_journal_next3,
+ sd_journal_get_realtime_usec3,
+ sd_journal_add_match3,
+ sd_journal_seek_head3,
+ sd_journal_get_cursor3,
+ sd_journal_cutoff_realtime_usec3,
+ journalctl1,
+ sd-id1287,
+ pkg-config1
+
+
+
+
diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml
index 499c55fb60..1e23596f4b 100644
--- a/man/sd_id128_randomize.xml
+++ b/man/sd_id128_randomize.xml
@@ -125,7 +125,7 @@
Return Value
- The three calls returns 0 on success (in which
+ The three calls return 0 on success (in which
case ret is filled in), or a
negative errno-style error code.
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
new file mode 100644
index 0000000000..c40498b38a
--- /dev/null
+++ b/man/sd_journal_print.xml
@@ -0,0 +1,206 @@
+
+
+
+
+
+
+
+
+ sd_journal_print
+ systemd
+
+
+
+ Developer
+ Lennart
+ Poettering
+ lennart@poettering.net
+
+
+
+
+
+ sd_journal_print
+ 3
+
+
+
+ sd_journal_print
+ sd_journal_printv
+ sd_journal_send
+ sd_journal_sendv
+ Submit log entries to the journal
+
+
+
+
+ #include <systemd/sd-journal.h>
+
+
+ int sd_journal_print
+ int priority
+ const char* format
+ ...
+
+
+
+ int sd_journal_printv
+ int priority
+ const char* format
+ va_list ap
+
+
+
+ int sd_journal_send
+ const char* format
+ ...
+
+
+
+ int sd_journal_sendv
+ const struct iovec *iov
+ int n
+
+
+
+
+
+
+ Description
+
+ sd_journal_print() 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
+ printf3
+ or
+ syslog3. The
+ priority value is one of
+ LOG_EMERG,
+ LOG_ALERT,
+ LOG_CRIT,
+ LOG_ERR,
+ LOG_WARNING,
+ LOG_NOTICE,
+ LOG_INFO,
+ LOG_DEBUG, as defined in
+ syslog.h, see
+ syslog3
+ 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.
+
+ sd_journal_printv() is
+ similar to sd_journal_print() but
+ takes a variable argument list encapsulated in an
+ object of type va_list (see
+ stdarg3
+ for more information) instead of the format string. It
+ is otherwise equivalent in behaviour.
+
+ sd_journal_send() 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 a NULL. 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. 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
+ systemd.journal-fields7
+ for details, but additional application defined fields
+ may be used.
+
+ sd_journal_sendv() is
+ similar to sd_journal_send() but
+ takes an array of struct iovec (as
+ defined in uio.h, see
+ readv3
+ 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. sd_journal_sendv() is
+ particularly useful to submit binary objects to the
+ journal where that is necessary.
+
+ Note that sd_journal_send()
+ is a wapper around
+ sd_journal_sendv() to make it
+ easier to use when only text strings shall be
+ submitted. Also, the following two calls are
+ mostly equivalent:
+
+ 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);
+
+ 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.
+
+
+
+ Return Value
+
+ The four calls return 0 on success or a
+ negative errno-style error code.
+
+
+
+ Notes
+
+ The sd_journal_print(),
+ sd_journal_printv(),
+ sd_journal_send() and
+ sd_journal_sendv() interfaces
+ are available as shared library, which can be compiled
+ and linked to with the
+ libsystemd-journal
+ pkg-config1
+ file.
+
+
+
+ See Also
+
+
+ systemd1,
+ sd-journal7,
+ sd_journal_stream_fd3,
+ syslog3,
+ systemd.journal-fields7
+
+
+
+
diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml
index 83c59d463b..3c71a59c95 100644
--- a/man/systemd-journald.service.xml
+++ b/man/systemd-journald.service.xml
@@ -165,7 +165,8 @@
systemd1,
journalctl1,
journald.conf5,
- systemd.journal-fields7
+ systemd.journal-fields7,
+ sd-journal7
diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml
index 518c0fc059..fd0beb968f 100644
--- a/man/systemd.journal-fields.xml
+++ b/man/systemd.journal-fields.xml
@@ -53,11 +53,12 @@
Entries in the journal resemble an environment
block in their syntax, however with fields that can
include binary data. Primarily, fields are formatted
- ASCII strings, and binary formatting is used only
- where formatting as ASCII makes little sense. New
- fields may be freely defined by applications, but a
- few fields have special meaning. All fields with
- special meaning are optional.
+ UTF-8 text strings, and binary formatting is used only
+ where formatting as UTF-8 text strings makes little
+ sense. New fields may freely be defined by
+ applications, but a few fields have special
+ meaning. All fields with special meanings are
+ optional.
@@ -355,7 +356,8 @@
systemd1,
journalctl1,
- journald.conf5
+ journald.conf5,
+ sd-journal7
diff --git a/src/systemd/sd-journal.h b/src/systemd/sd-journal.h
index 792e31fc02..a69aa25a68 100644
--- a/src/systemd/sd-journal.h
+++ b/src/systemd/sd-journal.h
@@ -40,7 +40,7 @@ int sd_journal_printv(int priority, const char *format, va_list ap);
int sd_journal_send(const char *format, ...) __attribute__((sentinel));
int sd_journal_sendv(const struct iovec *iov, int n);
-/* Used by the macros below */
+/* Used by the macros below. Don't call this directly. */
int sd_journal_print_with_location(int priority, const char *file, const char *line, const char *func, const char *format, ...) __attribute__ ((format (printf, 5, 6)));
int sd_journal_printv_with_location(int priority, const char *file, const char *line, const char *func, const char *format, va_list ap);
int sd_journal_send_with_location(const char *file, const char *line, const char *func, const char *format, ...) __attribute__((sentinel));