* cygwin-api.xml: Move chapter tags from path.xml back here.

	Include logon-funcs.xml.
	* logon-funcs.xml: Moved from ../cygwin here and converted to XML.
	* path.xml: Drop chapter tags.  Create subsections.

1 files changed, 56 insertions, 0 deletions

diff --git a/winsup/doc/logon-funcs.xml b/winsup/doc/logon-funcs.xml
new file mode 100644
index 000000000..9e32ad626
--- /dev/null
+++ b/winsup/doc/logon-funcs.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="func-cygwin-login">
+<title>Helper functions to change user context</title>
+
+<sect2 id="func-cygwin-logon_user">
+<title>cygwin_logon_user</title>
+
+<funcsynopsis><funcprototype>
+<funcdef>extern "C" HANDLE
+<function>cygwin_logon_user</function></funcdef>
+<paramdef>const struct passwd *<parameter>passwd_entry</parameter></paramdef>
+<paramdef>const char *<parameter>password</parameter></paramdef>
+</funcprototype></funcsynopsis>
+
+<para>Given a pointer to a passwd entry of a user and a cleartext password,
+returns a HANDLE to an impersonation token for this user which can be used
+in a subsequent call to <function>cygwin_set_impersonation_token</function>
+to impersonate that user.  This function can only be called from a process
+which has the required NT user rights to perform a logon.</para>
+
+<para>See also the chapter
+<ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
+in the Cygwin User's guide.</para>
+
+<para>See also <link linkend="func-cygwin-set-impersonation-token">cygwin_set_impersonation_token</link></para>
+
+</sect2>
+
+<sect2 id="func-cygwin-set-impersonation-token">
+<title>cygwin_set_impersonation_token</title>
+
+<funcsynopsis><funcprototype>
+<funcdef>extern "C" void
+<function>cygwin_set_impersonation_token</function></funcdef>
+<paramdef>const HANDLE <parameter>token</parameter></paramdef>
+</funcprototype></funcsynopsis>
+
+<para>Use this function to enable the token given as parameter as
+impersonation token for the next call to <function>setuid</function> or
+<function>seteuid</function>.  Use
+<function>cygwin_set_impersonation_token</function> together with
+<function>cygwin_logon_user</function> to impersonate users using
+password authentication.</para>
+
+<para>See also the chapter
+<ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
+in the Cygwin User's guide.</para>
+
+<para>See also <link linkend="func-cygwin-logon_user">cygwin_logon_user</link></para>
+
+</sect2>
+
+</sect1>