summaryrefslogtreecommitdiffstats
path: root/doc/man/pam_set_item.3.xml
blob: 30ab92b90c573e87984baaf647e127230276f1f8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
<?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"
[
<!--
<!ENTITY accessconf SYSTEM "pam_item_types_std.inc.xml">
<!ENTITY accessconf SYSTEM "pam_item_types_ext.inc.xml">
-->
]>

<refentry id='pam_set_item'>

  <refmeta>
    <refentrytitle>pam_set_item</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id='pam_set_item-name'>
    <refname>pam_set_item</refname>
    <refpurpose>
       set and update PAM information
    </refpurpose>
  </refnamediv>


<!-- body begins here -->

  <refsynopsisdiv>

   <funcsynopsis id="pam_set_item-synopsis">
     <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
     <funcprototype>
       <funcdef>int <function>pam_set_item</function></funcdef>
       <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
       <paramdef>int <parameter>item_type</parameter></paramdef>
       <paramdef>const void *<parameter>item</parameter></paramdef>
     </funcprototype>
   </funcsynopsis>

  </refsynopsisdiv>


  <refsect1 id="pam_set_item-description">
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_set_item</function> function allows applications
      and PAM service modules to access and to update PAM information
      of <emphasis>item_type</emphasis>. For this a copy
      of the object pointed to by the <emphasis>item</emphasis> argument
      is created. The following <emphasis>item_type</emphasis>s are
      supported:
   </para>

   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="pam_item_types_std.inc.xml"/>

   <para>
     The following additional items are specific to Linux-PAM and should not be used in
     portable applications:
   </para>

   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="pam_item_types_ext.inc.xml"/>

    <para>
      For all <emphasis>item_type</emphasis>s, other than PAM_CONV and
      PAM_FAIL_DELAY, <emphasis>item</emphasis> is a pointer to a &lt;NUL&gt;
      terminated character string. In the case of PAM_CONV,
      <emphasis>item</emphasis> points to an initialized
      <emphasis>pam_conv</emphasis> structure. In the case of
      PAM_FAIL_DELAY, <emphasis>item</emphasis> is a function pointer:
      <function>void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)</function>
    </para>

    <para>
      Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before
      returning to the application. Which means an application is not
      able to access the authentication tokens.
    </para>

  </refsect1>

  <refsect1 id="pam_set_item-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_BAD_ITEM</term>
        <listitem>
           <para>
             The application attempted to set an undefined or inaccessible
             item.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
           <para>
              Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             Data was successful updated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SYSTEM_ERR</term>
        <listitem>
           <para>
             The <emphasis>pam_handle_t</emphasis> passed as first
             argument was invalid.
          </para>
        </listitem>
       </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_set_item-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

</refentry>