chiark / gitweb /
man: update journald rate limit defaults
[elogind.git] / man / sd_journal_get_cutoff_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_cutoff_realtime_usec">
25
26         <refentryinfo>
27                 <title>sd_journal_get_cutoff_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_cutoff_realtime_usec</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>sd_journal_get_cutoff_realtime_usec</refname>
47                 <refname>sd_journal_get_cutoff_monotonic_usec</refname>
48                 <refpurpose>Read cut-off 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_cutoff_realtime_usec</function></funcdef>
57                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
58                                 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
59                                 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
60                         </funcprototype>
61
62                         <funcprototype>
63                                 <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef>
64                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
65                                 <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef>
66                                 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
67                                 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
68                         </funcprototype>
69
70                 </funcsynopsis>
71         </refsynopsisdiv>
72
73         <refsect1>
74                 <title>Description</title>
75
76                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
77                 gets the realtime (wallclock) timestamps of the first
78                 and last entries accessible in the journal.  It takes
79                 three arguments: the journal context object and two
80                 pointers to 64-bit unsigned integers to store the
81                 timestamps in. The timestamps are in microseconds
82                 since the epoch,
83                 i.e. <constant>CLOCK_REALTIME</constant>. Either one
84                 of the two timestamp arguments may be passed as
85                 <constant>NULL</constant> in case the timestamp is not
86                 needed, but not both.</para>
87
88                 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
89                 gets the monotonic timestamps of the first and last
90                 entries accessible in the journal. It takes three
91                 arguments: the journal context object, a 128-bit
92                 identifier for the boot, and two pointers to 64-bit
93                 unsigned integers to store the timestamps. The
94                 timestamps are in microseconds since boot-up of the
95                 specific boot,
96                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
97                 monotonic clock begins new with every reboot it only
98                 defines a well-defined point in time when used
99                 together with an identifier identifying the boot, see
100                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
101                 for more information. The function will return the
102                 timestamps for the boot identified by the passed boot
103                 ID. Either one of the two timestamp arguments may be
104                 passed as <constant>NULL</constant> in case the
105                 timestamp is not needed, but not both.</para>
106         </refsect1>
107
108         <refsect1>
109                 <title>Return Value</title>
110
111                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
112                 and
113                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
114                 return 1 on success, 0 if not suitable entries are in
115                 the journal or a negative errno-style error code.</para>
116         </refsect1>
117
118         <refsect1>
119                 <title>Notes</title>
120
121                 <para>The
122                 <function>sd_journal_get_cutoff_realtime_usec()</function>
123                 and
124                 <function>sd_journal_get_cutoff_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_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
140                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
141                 </para>
142         </refsect1>
143
144 </refentry>