* 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.

winsup/doc/ChangeLog

@@ -1,3 +1,10 @@
+2014-08-14  Corinna Vinschen  <corinna@vinschen.de>
+
+	* 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.
+
 2014-08-14  Corinna Vinschen  <corinna@vinschen.de>
 
 	* Makefile.in: Throughout use parenthesis instead of braces where

winsup/doc/cygwin-api.xml

@@ -13,6 +13,13 @@
   <toc></toc>
 
   <xi:include href="posix.xml"/>
-  <xi:include href="path.xml"/>
+
+  <chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <title>Cygwin Functions</title>
+
+    <xi:include href="path.xml"/>
+    <xi:include href="logon-funcs.xml"/>
+
+  </chapter>
 
 </book>

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>

winsup/doc/path.xml

@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
     "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 
-<chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+<sect1 id="func-cygwin-path">
-<title>Cygwin Functions</title>
+<title>Path conversion functions</title>
 
 <para>These functions are specific to Cygwin itself, and probably
 won't be found anywhere else.  </para>
 
-<sect1 id="func-cygwin-conv-path">
+<sect2 id="func-cygwin-conv-path">
 <title>cygwin_conv_path</title>
 
 <funcsynopsis><funcprototype>
@@ -84,9 +84,9 @@ else
 </programlisting>
 </example>
 
-</sect1>
+</sect2>
 
-<sect1 id="func-cygwin-conv-path-list">
+<sect2 id="func-cygwin-conv-path-list">
 <title>cygwin_conv_path_list</title>
 
 <funcsynopsis><funcprototype>
@@ -111,9 +111,9 @@ convert it to the equivalent POSIX $PATH-style string (i.e. /foo:/bar).</para>
 
 <para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>
 
-</sect1>
+</sect2>
 
-<sect1 id="func-cygwin-create-path">
+<sect2 id="func-cygwin-create-path">
 <title>cygwin_create_path</title>
 
 <funcsynopsis><funcprototype>
@@ -140,9 +140,9 @@ errno can be set to the below value.</para>
 
 <para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>
 
-</sect1>
+</sect2>
 
-<sect1 id="func-cygwin-posix-path-list-p">
+<sect2 id="func-cygwin-posix-path-list-p">
 <title>cygwin_posix_path_list_p</title>
 
 <funcsynopsis><funcprototype>
@@ -159,9 +159,9 @@ true if the path is a POSIX path.  Note that "_p" means "predicate", a
 lisp term meaning that the function tells you something about the
 parameter.</para>
 
-</sect1>
+</sect2>
 
-<sect1 id="func-cygwin-split-path">
+<sect2 id="func-cygwin-split-path">
 <title>cygwin_split_path</title>
 
 <funcsynopsis><funcprototype>
@@ -185,6 +185,6 @@ cygwin_split_path("c:/foo/bar.c", dir, file);
 printf("dir=%s, file=%s\n", dir, file);
 </programlisting>
 </example>
-</sect1>
+</sect2>
 
-</chapter>
+</sect1>