diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/sd_journal_print.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/sd_journal_print.3 | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/sd_journal_print.3 b/upstream/opensuse-tumbleweed/man3/sd_journal_print.3 deleted file mode 100644 index 4d66af33..00000000 --- a/upstream/opensuse-tumbleweed/man3/sd_journal_print.3 +++ /dev/null @@ -1,221 +0,0 @@ -'\" t -.TH "SD_JOURNAL_PRINT" "3" "" "systemd 254" "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 "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 |