diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/misc_conv.3.xml | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/man/misc_conv.3.xml b/doc/man/misc_conv.3.xml new file mode 100644 index 0000000..d902ba8 --- /dev/null +++ b/doc/man/misc_conv.3.xml @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="misc_conv"> + + <refmeta> + <refentrytitle>misc_conv</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo> + </refmeta> + + <refnamediv id="misc_conv-name"> + <refname>misc_conv</refname> + <refpurpose>text based conversation function</refpurpose> + </refnamediv> + +<!-- body begins here --> + + <refsynopsisdiv> + <funcsynopsis id="misc_conv-synopsis"> + <funcsynopsisinfo>#include <security/pam_misc.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>misc_conv</function></funcdef> + <paramdef>int <parameter>num_msg</parameter></paramdef> + <paramdef>const struct pam_message **<parameter>msgm</parameter></paramdef> + <paramdef>struct pam_response **<parameter>response</parameter></paramdef> + <paramdef>void *<parameter>appdata_ptr</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1 id='misc_conv-description'> + <title>DESCRIPTION</title> + <para> + The <function>misc_conv</function> function is part of + <command>libpam_misc</command> and not of the standard + <command>libpam</command> library. This function will prompt + the user with the appropriate comments and obtain the appropriate + inputs as directed by authentication modules. + </para> + <para> + In addition to simply slotting into the appropriate <citerefentry> + <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, this function provides some time-out facilities. + The function exports five variables that can be used by an + application programmer to limit the amount of time this conversation + function will spend waiting for the user to type something. The + five variables are as follows: + </para> + <variablelist> + <varlistentry> + <term><type>time_t</type> <varname>pam_misc_conv_warn_time</varname>;</term> + <listitem> + <para> + This variable contains the <emphasis>time</emphasis> (as + returned by <citerefentry> + <refentrytitle>time</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>) that the user should be first warned that + the clock is ticking. By default it has the value + <returnvalue>0</returnvalue>, which indicates that no such + warning will be given. The application may set its value to + sometime in the future, but this should be done prior to + passing control to the <emphasis>Linux-PAM</emphasis> library. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><type>const char *</type><varname>pam_misc_conv_warn_line</varname>;</term> + <listitem> + <para> + Used in conjunction with + <varname>pam_misc_conv_warn_time</varname>, this variable is + a pointer to the string that will be displayed when it becomes + time to warn the user that the timeout is approaching. Its + default value is a translated version of + <quote>...Time is running out...</quote>, but this can be + changed by the application prior to passing control to + <emphasis>Linux-PAM</emphasis>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><type>time_t</type> <varname>pam_misc_conv_die_time</varname>;</term> + <listitem> + <para> + This variable contains the <emphasis>time</emphasis> (as + returned by <citerefentry> + <refentrytitle>time</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>) that the will time out. By default it has + the value <returnvalue>0</returnvalue>, which indicates that + the conversation function will not timeout. The application + may set its value to sometime in the future, but this should + be done prior to passing control to the + <emphasis>Linux-PAM</emphasis> library. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><type>const char *</type><varname>pam_misc_conv_die_line</varname>;</term> + <listitem> + <para> + Used in conjunction with + <varname>pam_misc_conv_die_time</varname>, this variable is + a pointer to the string that will be displayed when the + conversation times out. Its default value is a translated + version of + <quote>...Sorry, your time is up!</quote>, but this can be + changed by the application prior to passing control to + <emphasis>Linux-PAM</emphasis>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><type>int</type> <varname>pam_misc_conv_died</varname>;</term> + <listitem> + <para> + Following a return from the <emphasis>Linux-PAM</emphasis> + library, the value of this variable indicates whether the + conversation has timed out. A value of + <returnvalue>1</returnvalue> indicates the time-out occurred. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The following two function pointers are available for supporting + binary prompts in the conversation function. They are optimized + for the current incarnation of the <command>libpamc</command> + library and are subject to change. + </para> + <variablelist> + <varlistentry> + <term> + <type>int</type> <varname>(*pam_binary_handler_fn)</varname>(<type>void *</type><varname>appdata</varname>, <type>pamc_bp_t *</type><varname>prompt_p</varname>); + </term> + <listitem> + <para> + This function pointer is initialized to + <returnvalue>NULL</returnvalue> but can be filled with a + function that provides machine-machine (hidden) message + exchange. It is intended for use with hidden authentication + protocols such as RSA or Diffie-Hellman key exchanges. + (This is still under development.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <type>int</type> <varname>(*pam_binary_handler_free)</varname>(<type>void *</type><varname>appdata</varname>, <type>pamc_bp_t *</type><varname>delete_me</varname>); + </term> + <listitem> + <para> + This function pointer is initialized to + <function>PAM_BP_RENEW(delete_me, 0, 0)</function>, but can be + redefined as desired by the application. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='misc_conv-see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> + + <refsect1 id='misc_conv-standards'> + <title>STANDARDS</title> + <para> + The <function>misc_conv</function> function is part of the + <command>libpam_misc</command> Library and not defined in any + standard. + </para> + </refsect1> + +</refentry> |