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 systemd.
   7
   8   Copyright 2015 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_event_now" xmlns:xi="http://www.w3.org/2001/XInclude">
  25
  26   <refentryinfo>
  27     <title>sd_event_now</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_event_now</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_event_now</refname>
  47
  48     <refpurpose>Retrieve current event loop iteration timestamp</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <funcsynopsis>
  53       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_event_now</function></funcdef>
  57         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  58         <paramdef>clockid_t <parameter>clock</parameter></paramdef>
  59         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  60       </funcprototype>
  61
  62     </funcsynopsis>
  63   </refsynopsisdiv>
  64
  65   <refsect1>
  66     <title>Description</title>
  67
  68     <para><function>sd_event_now()</function> returns the timestamp
  69     the most recent event loop iteration began. This timestamp is
  70     taken right after returning from the event sleep, and before
  71     dispatching any event sources. The <parameter>event</parameter>
  72     parameter takes the even loop object to retrieve the timestamp
  73     from. The <parameter>clock</parameter> parameter specifies the clock to
  74     retrieve the timestamp for, and is one of
  75     <constant>CLOCK_REALTIME</constant> (or its equivalent
  76     <constant>CLOCK_REALTIME_ALARM</constant>),
  77     <constant>CLOCK_MONOTONIC</constant> or
  78     <constant>CLOCK_BOOTTIME</constant> (or its equivalent
  79     <constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry
  80     project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  81     for more information on the various clocks. The retrieved
  82     timestamp is stored in the <parameter>usec</parameter> parameter,
  83     in µs since the clock's epoch. If this function is invoked before
  84     the first event loop iteration the current time is returned, as
  85     reported by <function>clock_gettime()</function>. To distinguish
  86     this case from a regular invocation the return value will be
  87     positive non-zero in this case, while it is zero when the returned
  88     timestamp refers to the actual event loop iteration.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Return Value</title>
  93
  94     <para>If the first event loop iteration has not run yet
  95     <function>sd_event_now()</function> returns the requested
  96     timestamp in <parameter>usec</parameter> and returns a positive,
  97     non-zero return value. Otherwise, on success it will return the
  98     iteration's timestamp in <parameter>usec</parameter> and 0 as
  99     return value. On failure, the call returns a negative errno-style
 100     error code.</para>
 101   </refsect1>
 102
 103   <refsect1>
 104     <title>Errors</title>
 105
 106     <para>Returned errors may indicate the following problems:</para>
 107
 108     <variablelist>
 109       <varlistentry>
 110         <term><constant>-EINVAL</constant></term>
 111
 112         <listitem><para>An invalid parameter was
 113         passed.</para></listitem>
 114
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><constant>-ECHILD</constant></term>
 119
 120         <listitem><para>The event loop object was created in a
 121         different process.</para></listitem>
 122       </varlistentry>
 123
 124     </variablelist>
 125   </refsect1>
 126
 127   <xi:include href="libsystemd-pkgconfig.xml" />
 128
 129   <refsect1>
 130     <title>See Also</title>
 131
 132     <para>
 133       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 134       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 136       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 137       <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 138     </para>
 139   </refsect1>
 140
 141 </refentry>