man/sd_event_now.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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 elogind.
   7   SPDX-License-Identifier: LGPL-2.1+
   8
   9
  10   Copyright 2015 Lennart Poettering
  11
  12   elogind is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   elogind is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude">
  27
  28   <refentryinfo>
  29     <title>sd_event_now</title>
  30     <productname>elogind</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_event_now</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_event_now</refname>
  49
  50     <refpurpose>Retrieve current event loop iteration timestamp</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_event_now</function></funcdef>
  59         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  60         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  61         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  62       </funcprototype>
  63
  64     </funcsynopsis>
  65   </refsynopsisdiv>
  66
  67   <refsect1>
  68     <title>Description</title>
  69
  70     <para><function>sd_event_now()</function> returns the time when
  71     the most recent event loop iteration began. A timestamp
  72     is taken right after returning from the event sleep, and before
  73     dispatching any event sources. The <parameter>event</parameter>
  74     parameter specifies the event loop object to retrieve the timestamp
  75     from. The <parameter>clock</parameter> parameter specifies the clock to
  76     retrieve the timestamp for, and is one of
  77     <constant>CLOCK_REALTIME</constant> (or equivalently
  78     <constant>CLOCK_REALTIME_ALARM</constant>),
  79     <constant>CLOCK_MONOTONIC</constant>, or
  80     <constant>CLOCK_BOOTTIME</constant> (or equivalently
  81     <constant>CLOCK_BOOTTIME_ALARM</constant>), see
  82     <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  83     for more information on the various clocks. The retrieved
  84     timestamp is stored in the <parameter>usec</parameter> parameter,
  85     in µs since the clock's epoch. If this function is invoked before
  86     the first event loop iteration, the current time is returned, as
  87     reported by <function>clock_gettime()</function>. To distinguish
  88     this case from a regular invocation the return value will be
  89     positive, and zero when the returned timestamp refers to an actual
  90     event loop iteration.</para>
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>Return Value</title>
  95
  96     <para>If the first event loop iteration has not run yet
  97     <function>sd_event_now()</function> writes current time to
  98     <parameter>usec</parameter> and returns a positive return value.
  99     Otherwise, it will write the requested timestamp to <parameter>usec</parameter>
 100     and return 0. On failure, the call returns a negative errno-style
 101     error code.</para>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Errors</title>
 106
 107     <para>Returned values may indicate the following problems:</para>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term><constant>-EINVAL</constant></term>
 112
 113         <listitem><para>An invalid parameter was
 114         passed.</para></listitem>
 115
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><constant>-EOPNOTSUPP</constant></term>
 120
 121         <listitem><para>Unsupported clock type.
 122         </para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><constant>-ECHILD</constant></term>
 127
 128         <listitem><para>The event loop object was created in a
 129         different process.</para></listitem>
 130       </varlistentry>
 131     </variablelist>
 132   </refsect1>
 133
 134   <xi:include href="libelogind-pkgconfig.xml" />
 135
 136   <refsect1>
 137     <title>See Also</title>
 138
 139     <para>
 140       <!-- 0 /// elogind is in section 8
 141       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 142       --><!-- else -->
 143       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 144       <!-- // 0 -->
 145       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 146       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 149     </para>
 150   </refsect1>
 151
 152 </refentry>