<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_timestamp_check">

  <refmeta>
    <refentrytitle>pam_timestamp_check</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="source">Linux-PAM</refmiscinfo>
    <refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv xml:id="pam_timestamp_check-name">
    <refname>pam_timestamp_check</refname>
    <refpurpose>Check to see if the default timestamp is valid</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis xml:id="pam_timestamp_check-cmdsynopsis" sepchar=" ">
      <command>pam_timestamp_check</command>
      <arg choice="opt" rep="norepeat">
	-k
      </arg>
      <arg choice="opt" rep="norepeat">
        -d
      </arg>
      <arg choice="opt" rep="norepeat">
        <replaceable>target_user</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 xml:id="pam_timestamp_check-description">

    <title>DESCRIPTION</title>

    <para>
      With no arguments <command>pam_timestamp_check</command> will check to
see if the default timestamp is valid, or optionally remove it.
    </para>
  </refsect1>

  <refsect1 xml:id="pam_timestamp_check-options">

    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
         <term>
            -k
         </term>
         <listitem>
            <para>
               Instead of checking the validity of a timestamp, remove it.
               This is analogous to sudo's <emphasis>-k</emphasis> option.
            </para>
         </listitem>
      </varlistentry>
      <varlistentry>
         <term>
            -d
         </term>
         <listitem>
            <para>
               Instead of returning validity using an exit status,
               loop indefinitely, polling regularly and printing the status on
               standard output.
            </para>
         </listitem>
      </varlistentry>
      <varlistentry>
         <term>
            target_user
         </term>
         <listitem>
            <para>
               By default <command>pam_timestamp_check</command> checks or removes
               timestamps generated by <emphasis>pam_timestamp</emphasis> when
               the user authenticates as herself. When the user authenticates as a
               different user, the name of the timestamp file changes to
               accommodate this. <replaceable>target_user</replaceable> allows
               one to specify this user name.
            </para>
         </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 xml:id="pam_timestamp_check-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>0</term>
        <listitem>
          <para>
            The timestamp is valid.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>2</term>
        <listitem>
          <para>
            The binary is not setuid root.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>3</term>
        <listitem>
          <para>
            Invalid invocation.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>4</term>
        <listitem>
          <para>
            User is unknown.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>5</term>
        <listitem>
          <para>
            Permissions error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>6</term>
        <listitem>
          <para>
            Invalid controlling tty.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>7</term>
        <listitem>
          <para>
            Timestamp is not valid.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 xml:id="pam_timestamp-notes">
    <title>NOTES</title>
    <para>
      Users can get confused when they are not always asked for passwords when
running a given program. Some users reflexively begin typing information before
noticing that it is not being asked for.
    </para>
  </refsect1>

  <refsect1 xml:id="pam_timestamp-examples">
    <title>EXAMPLES</title>
    <programlisting>
auth sufficient pam_timestamp.so verbose
auth required   pam_unix.so

session required pam_unix.so
session optional pam_timestamp.so
    </programlisting>
  </refsect1>

  <refsect1 xml:id="pam_timestamp-files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term>/var/run/sudo/...</term>
        <listitem>
          <para>timestamp files and directories</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 xml:id="pam_timestamp-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
	<refentrytitle>pam_timestamp_check</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

  <refsect1 xml:id="pam_timestamp-author">
    <title>AUTHOR</title>
      <para>
        pam_timestamp was written by Nalin Dahyabhai.
      </para>
  </refsect1>

</refentry>