chiark / gitweb /
man: update journald rate limit defaults
[elogind.git] / man / sd_journal_get_realtime_usec.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_journal_get_realtime_usec">
25
26         <refentryinfo>
27                 <title>sd_journal_get_realtime_usec</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>sd_journal_get_realtime_usec</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>sd_journal_get_realtime_usec</refname>
47                 <refname>sd_journal_get_monotonic_usec</refname>
48                 <refpurpose>Read timestamps from the current journal entry</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <funcsynopsis>
53                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
54
55                         <funcprototype>
56                                 <funcdef>int <function>sd_journal_get_realtime_usec</function></funcdef>
57                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
58                                 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
59                         </funcprototype>
60
61                         <funcprototype>
62                                 <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef>
63                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
64                                 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
65                                 <paramdef>sd_id128_t *<parameter>boot_id</parameter></paramdef>
66                         </funcprototype>
67
68                 </funcsynopsis>
69         </refsynopsisdiv>
70
71         <refsect1>
72                 <title>Description</title>
73
74                 <para><function>sd_journal_get_realtime_usec()</function>
75                 gets the realtime (wallclock) timestamp of the
76                 current journal entry. It takes two arguments: the
77                 journal context object and a pointer to a 64-bit
78                 unsigned integer to store the timestamp in. The
79                 timestamp is in microseconds since the epoch,
80                 i.e. <constant>CLOCK_REALTIME</constant>.</para>
81
82                 <para><function>sd_journal_get_monotonic_usec()</function>
83                 gets the monotonic timestamp of the current journal
84                 entry. It takes three arguments: the journal context
85                 object, a pointer to a 64-bit unsigned integer to
86                 store the timestamp in, as well as a 128-bit ID buffer
87                 to store the boot ID of the monotonic timestamp.
88                 The timestamp is in microseconds since boot-up of
89                 the specific boot,
90                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
91                 monotonic clock begins new with every reboot, it only
92                 defines a well-defined point in time when used
93                 together with an identifier identifying the boot. See
94                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
95                 for more information. If the boot ID parameter is
96                 passed <constant>NULL</constant>, the function will
97                 fail if the monotonic timestamp of the current entry
98                 is not of the current system boot.</para>
99
100                 <para>Note that these functions will not work before
101                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
102                 (or related call) has been called at least
103                 once, in order to position the read pointer at a valid entry.</para>
104         </refsect1>
105
106         <refsect1>
107                 <title>Return Value</title>
108
109                 <para><function>sd_journal_get_realtime_usec()</function>
110                 and
111                 <function>sd_journal_get_monotonic_usec()</function>
112                 returns 0 on success or a negative errno-style error
113                 code. If the boot ID parameter was passed <constant>NULL</constant> and the
114                 monotonic timestamp of the current journal entry is
115                 not of the current system boot, -ESTALE is returned by <function>sd_journal_get_monotonic_usec()</function>.</para>
116         </refsect1>
117
118         <refsect1>
119                 <title>Notes</title>
120
121                 <para>The
122                 <function>sd_journal_get_realtime_usec()</function>
123                 and
124                 <function>sd_journal_get_monotonic_usec()</function>
125                 interfaces are available as a shared library, which can
126                 be compiled and linked to with the
127                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
128                 file.</para>
129         </refsect1>
130
131         <refsect1>
132                 <title>See Also</title>
133
134                 <para>
135                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
136                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
137                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
140                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
141                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
142                         <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
143                 </para>
144         </refsect1>
145
146 </refentry>