'\" t .TH "SD_JOURNAL_PRINT" "3" "" "elogind 252.9" "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 .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 syslog\&. 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 syslog\&. 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 \fBelogind.journal-fields\fR(7) for details\&. Other fields are ignored by elogind, but more variables may be added in the future\&. 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\&. A number of well\-known fields are defined, see \fBelogind.journal-fields\fR(7) for details\&. Other fields are ignored by elogind, but more variables may be added in the future\&. 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 syslog 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\&. 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\&. Those arguments must contain valid journal entries including the variable name, e\&.g\&. "CODE_FILE=src/foo\&.c", "CODE_LINE=666", "CODE_FUNC=myfunc"\&. 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 sent via \fBsd_journal_print()\fR and \fBsd_journal_send()\fR are sent to syslog, as elogind does not provide a journal server\&. .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\&. .SH "NOTES" .PP These APIs are implemented as a shared library, which can be compiled and linked to with the \fBlibelogind\fR\ \&\fBpkg-config\fR(1) file\&. .SH "SEE ALSO" .PP \fBelogind\fR(8), \fBsd_journal_stream_fd\fR(3), \fBsyslog\fR(3), \fBperror\fR(3), \fBerrno\fR(3), \fBelogind.journal-fields\fR(7), \fBsignal\fR(7), \fBsocket\fR(7)