granicus.if.org Git - linux-pam/blob - doc/man/pam_getenvlist.3.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id='pam_getenvlist'>
   5   <refmeta>
   6     <refentrytitle>pam_getenvlist</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_getenvlist-name">
  12     <refname>pam_getenvlist</refname>
  13     <refpurpose>getting the PAM environment</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv id='pam_getenvlist-synopsis'>
  19     <funcsynopsis>
  20       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  21       <funcprototype>
  22         <funcdef>char **<function>pam_getenvlist</function></funcdef>
  23         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  24       </funcprototype>
  25     </funcsynopsis>
  26   </refsynopsisdiv>
  27
  28
  29   <refsect1 id='pam_getenvlist-description'>
  30     <title>DESCRIPTION</title>
  31     <para>
  32       The <function>pam_getenvlist</function> function returns a complete
  33       copy of the PAM environment as associated with the handle
  34       <emphasis>pamh</emphasis>. The PAM environment variables
  35       represent the contents of the regular environment variables of the
  36       authenticated user when service is granted.
  37     </para>
  38     <para>
  39       The format of the memory is a malloc()'d array of char pointers,
  40       the last element of which is set to NULL. Each of the non-NULL
  41       entries in this array point to a NUL terminated and malloc()'d
  42       char string of the form: "<emphasis>name=value</emphasis>".
  43     </para>
  44     <para>
  45       It should be noted that this memory will never be free()'d by
  46       libpam. Once obtained by a call to
  47       <function>pam_getenvlist</function>, it is the responsibility of
  48       the calling application to free() this memory.
  49     </para>
  50     <para>
  51       It is by design, and not a coincidence, that the format and contents
  52       of the returned array matches that required for the third argument of
  53       the
  54       <citerefentry>
  55         <refentrytitle>execle</refentrytitle><manvolnum>3</manvolnum>
  56       </citerefentry> function call.
  57     </para>
  58   </refsect1>
  59
  60   <refsect1 id="pam_getenvlist-return_values">
  61     <title>RETURN VALUES</title>
  62     <para>
  63       The <function>pam_getenvlist</function> function returns NULL
  64       on failure.
  65     </para>
  66   </refsect1>
  67
  68   <refsect1 id='pam_getenvlist-see_also'>
  69     <title>SEE ALSO</title>
  70     <para>
  71       <citerefentry>
  72         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
  73       </citerefentry>,
  74       <citerefentry>
  75         <refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
  76       </citerefentry>,
  77       <citerefentry>
  78         <refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
  79       </citerefentry>,
  80       <citerefentry>
  81         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
  82       </citerefentry>
  83     </para>
  84   </refsect1>
  85 </refentry>