winsup/doc: Convert cygwin-api function documentation to refentry elements

Convert cygwin-api from using a sect2 element to using a refentry element for
each function.  This makes it possible to generate manpage-style output for
those elements.

Note that the chunked html now generates a page for each function, rather than
one containing all functions.

Also:

Remove pointless and incorrect date

Move introductory paragraph from the first section to the start of the chapter

Add a funcsynopsisinfo element with the header file to be included to each
function prototype

Remove extern "C" which doesn't process into all formats successfully

2015-06-17  Jon Turney  <jon.turney@dronecode.org.uk>

	* cygwin-api.xml: Move introductory paragraph here.
	* logon-funcs.xml: Convert from using a sect2 element to using a
	refentry element for each function.
	* misc-funcs.xml: Ditto.
	* path.xml: Ditto.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
This commit is contained in:
Jon TURNEY 2015-06-16 18:52:37 +01:00
parent a197d1d504
commit cf1c6cd395
5 changed files with 244 additions and 54 deletions

View File

@ -1,3 +1,11 @@
2015-06-17 Jon Turney <jon.turney@dronecode.org.uk>
* cygwin-api.xml: Move introductory paragraph here.
* logon-funcs.xml: Convert from using a sect2 element to using a
refentry element for each function.
* misc-funcs.xml: Ditto.
* path.xml: Ditto.
2015-06-17 Jon Turney <jon.turney@dronecode.org.uk> 2015-06-17 Jon Turney <jon.turney@dronecode.org.uk>
* fo.xsl: Render funcsynopsis elements as ANSI style function * fo.xsl: Render funcsynopsis elements as ANSI style function

View File

@ -5,7 +5,6 @@
<book id="cygwin-api" xmlns:xi="http://www.w3.org/2001/XInclude"> <book id="cygwin-api" xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo> <bookinfo>
<date>1998-08-31</date>
<title>Cygwin API Reference</title> <title>Cygwin API Reference</title>
<xi:include href="legal.xml"/> <xi:include href="legal.xml"/>
</bookinfo> </bookinfo>
@ -17,6 +16,11 @@
<chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude"> <chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Cygwin Functions</title> <title>Cygwin Functions</title>
<para>
These functions are specific to Cygwin itself, and probably won't be
found anywhere else.
</para>
<xi:include href="path.xml"/> <xi:include href="path.xml"/>
<xi:include href="logon-funcs.xml"/> <xi:include href="logon-funcs.xml"/>
<xi:include href="misc-funcs.xml"/> <xi:include href="misc-funcs.xml"/>

View File

@ -5,52 +5,91 @@
<sect1 id="func-cygwin-login"> <sect1 id="func-cygwin-login">
<title>Helper functions to change user context</title> <title>Helper functions to change user context</title>
<sect2 id="func-cygwin-logon_user"> <refentry id="func-cygwin-logon_user">
<title>cygwin_logon_user</title> <refmeta>
<refentrytitle>cygwin_logon_user</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<funcsynopsis><funcprototype> <refnamediv>
<funcdef>extern "C" HANDLE <refname>cygwin_logon_user</refname>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>HANDLE
<function>cygwin_logon_user</function></funcdef> <function>cygwin_logon_user</function></funcdef>
<paramdef>const struct passwd *<parameter>passwd_entry</parameter></paramdef> <paramdef>const struct passwd *<parameter>passwd_entry</parameter></paramdef>
<paramdef>const char *<parameter>password</parameter></paramdef> <paramdef>const char *<parameter>password</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Given a pointer to a passwd entry of a user and a cleartext password, <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 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> in a subsequent call to <function>cygwin_set_impersonation_token</function>
to impersonate that user. This function can only be called from a process 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> which has the required NT user rights to perform a logon.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>See also the chapter <para>See also the chapter
<ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink> <ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
in the Cygwin User's guide.</para> in the Cygwin User's guide.</para>
<para>See also <link linkend="func-cygwin-set-impersonation-token">cygwin_set_impersonation_token</link></para> <para>See also <link linkend="func-cygwin-set-impersonation-token">cygwin_set_impersonation_token</link></para>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-set-impersonation-token">
<refmeta>
<refentrytitle>cygwin_set_impersonation_token</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-set-impersonation-token"> <refnamediv>
<title>cygwin_set_impersonation_token</title> <refname>cygwin_set_impersonation_token</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" void <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void
<function>cygwin_set_impersonation_token</function></funcdef> <function>cygwin_set_impersonation_token</function></funcdef>
<paramdef>const HANDLE <parameter>token</parameter></paramdef> <paramdef>const HANDLE <parameter>token</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Use this function to enable the token given as parameter as <para>Use this function to enable the token given as parameter as
impersonation token for the next call to <function>setuid</function> or impersonation token for the next call to <function>setuid</function> or
<function>seteuid</function>. Use <function>seteuid</function>. Use
<function>cygwin_set_impersonation_token</function> together with <function>cygwin_set_impersonation_token</function> together with
<function>cygwin_logon_user</function> to impersonate users using <function>cygwin_logon_user</function> to impersonate users using
password authentication.</para> password authentication.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>See also the chapter <para>See also the chapter
<ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink> <ulink url="../cygwin-ug-net/ntsec.html#ntsec-setuid-overview">Switching the user context</ulink>
in the Cygwin User's guide.</para> in the Cygwin User's guide.</para>
<para>See also <link linkend="func-cygwin-logon_user">cygwin_logon_user</link></para> <para>See also <link linkend="func-cygwin-logon_user">cygwin_logon_user</link></para>
</refsect1>
</sect2> </refentry>
</sect1> </sect1>

View File

@ -5,11 +5,24 @@
<sect1 id="func-cygwin-misc"> <sect1 id="func-cygwin-misc">
<title>Miscellaneous functions</title> <title>Miscellaneous functions</title>
<sect2 id="func-cygwin-attach-handle-to-fd"> <refentry id="func-cygwin-attach-handle-to-fd">
<title>cygwin_attach_handle_to_fd</title> <refmeta>
<refentrytitle>cygwin_attach_handle_to_fd</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<funcsynopsis><funcprototype> <refnamediv>
<funcdef>extern "C" int <refname>cygwin_attach_handle_to_fd</refname>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int
<function>cygwin_attach_handle_to_fd</function></funcdef> <function>cygwin_attach_handle_to_fd</function></funcdef>
<paramdef>char *<parameter>name</parameter></paramdef> <paramdef>char *<parameter>name</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>fd</parameter></paramdef>
@ -17,7 +30,10 @@
<paramdef>int <parameter>bin</parameter></paramdef> <paramdef>int <parameter>bin</parameter></paramdef>
<paramdef>int <parameter>access</parameter></paramdef> <paramdef>int <parameter>access</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function can be used to turn a Win32 "handle" into a <para>This function can be used to turn a Win32 "handle" into a
posix-style file handle. <parameter>fd</parameter> may be -1 to posix-style file handle. <parameter>fd</parameter> may be -1 to
make cygwin allocate a handle; the actual handle is returned make cygwin allocate a handle; the actual handle is returned
@ -27,38 +43,71 @@ in all cases.</para>
underlying file or device. It just tries to supply the typical file underlying file or device. It just tries to supply the typical file
functions on a "best-effort" basis. Use with care. Don't expect too functions on a "best-effort" basis. Use with care. Don't expect too
much.</para> much.</para>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-internal">
<refmeta>
<refentrytitle>cygwin_internal</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-internal"> <refnamediv>
<title>cygwin_internal</title> <refname>cygwin_internal</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" uintptr_t <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>uintptr_t
<function>cygwin_internal</function></funcdef> <function>cygwin_internal</function></funcdef>
<paramdef>cygwin_getinfo_types <parameter>t</parameter></paramdef> <paramdef>cygwin_getinfo_types <parameter>t</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef> <paramdef><parameter>...</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function gives you access to various internal data and functions. <para>This function gives you access to various internal data and functions.
It takes two arguments. The first argument is a type from the 'cygwin_getinfo_types' It takes two arguments. The first argument is a type from the 'cygwin_getinfo_types'
enum. The second is an optional pointer.</para> enum. The second is an optional pointer.</para>
<para>Stay away unless you know what you're doing.</para> <para>Stay away unless you know what you're doing.</para>
</refsect1>
</refentry>
</sect2>
<sect2 id="func-cygwin-stackdump"> <refentry id="func-cygwin-stackdump">
<title>cygwin_stackdump</title> <refmeta>
<refentrytitle>cygwin_stackdump</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<funcsynopsis><funcprototype> <refnamediv>
<funcdef>extern "C" void <refname>cygwin_stackdump</refname>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void
<function>cygwin_stackdump</function></funcdef> <function>cygwin_stackdump</function></funcdef>
<void /> <void />
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para> Outputs a stackdump to stderr from the called location. <para> Outputs a stackdump to stderr from the called location.
</para> </para>
</refsect1>
</sect2> </refentry>
</sect1> </sect1>

View File

@ -5,21 +5,34 @@
<sect1 id="func-cygwin-path"> <sect1 id="func-cygwin-path">
<title>Path conversion functions</title> <title>Path conversion functions</title>
<para>These functions are specific to Cygwin itself, and probably <refentry id="func-cygwin-conv-path">
won't be found anywhere else. </para> <refmeta>
<refentrytitle>cygwin_conv_path</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-conv-path"> <refnamediv>
<title>cygwin_conv_path</title> <refname>cygwin_conv_path</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" ssize_t <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t
<function>cygwin_conv_path</function></funcdef> <function>cygwin_conv_path</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef> <paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef> <paramdef>const void * <parameter>from</parameter></paramdef>
<paramdef>void * <parameter>to</parameter></paramdef> <paramdef>void * <parameter>to</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Use this function to convert POSIX paths in <para>Use this function to convert POSIX paths in
<parameter>from</parameter> to Win32 paths in <parameter>to</parameter> <parameter>from</parameter> to Win32 paths in <parameter>to</parameter>
or, vice versa, Win32 paths in <parameter>from</parameter> to POSIX paths or, vice versa, Win32 paths in <parameter>from</parameter> to POSIX paths
@ -58,7 +71,10 @@ error and errno is set to one of the below values.</para>
of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH. of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH.
ENOSPC size is less than required for the conversion. ENOSPC size is less than required for the conversion.
</programlisting> </programlisting>
</refsect1>
<refsect1>
<title>Example</title>
<example> <example>
<title>Example use of cygwin_conv_path</title> <title>Example use of cygwin_conv_path</title>
<programlisting> <programlisting>
@ -83,21 +99,37 @@ else
]]> ]]>
</programlisting> </programlisting>
</example> </example>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-conv-path-list">
<refmeta>
<refentrytitle>cygwin_conv_path_list</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-conv-path-list"> <refnamediv>
<title>cygwin_conv_path_list</title> <refname>cygwin_conv_path_list</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" ssize_t <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>ssize_t
<function>cygwin_conv_path_list</function></funcdef> <function>cygwin_conv_path_list</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef> <paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef> <paramdef>const void * <parameter>from</parameter></paramdef>
<paramdef>void * <parameter>to</parameter></paramdef> <paramdef>void * <parameter>to</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This is the same as <function>cygwin_conv_path</function>, but the <para>This is the same as <function>cygwin_conv_path</function>, but the
input is treated as a path list in $PATH or %PATH% notation.</para> input is treated as a path list in $PATH or %PATH% notation.</para>
<para>If <parameter>what</parameter> is CCP_POSIX_TO_WIN_A or <para>If <parameter>what</parameter> is CCP_POSIX_TO_WIN_A or
@ -108,21 +140,40 @@ CCP_WIN_W_TO_POSIX, given a Win32 %PATH%-style string (i.e. d:\;e:\bar)
convert it to the equivalent POSIX $PATH-style string (i.e. /foo:/bar).</para> convert it to the equivalent POSIX $PATH-style string (i.e. /foo:/bar).</para>
<para><parameter>size</parameter> is the size of the buffer pointed to by <para><parameter>size</parameter> is the size of the buffer pointed to by
<parameter>to</parameter> in bytes.</para> <parameter>to</parameter> in bytes.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para> <para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-create-path">
<refmeta>
<refentrytitle>cygwin_create_path</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-create-path"> <refnamediv>
<title>cygwin_create_path</title> <refname>cygwin_create_path</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" void * <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void *
<function>cygwin_create_path</function></funcdef> <function>cygwin_create_path</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef> <paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef> <paramdef>const void * <parameter>from</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This is equivalent to the <function>cygwin_conv_path</function>, except <para>This is equivalent to the <function>cygwin_conv_path</function>, except
that <function>cygwin_create_path</function> does not take a buffer pointer that <function>cygwin_create_path</function> does not take a buffer pointer
for the result of the conversion as input. Rather it allocates the buffer for the result of the conversion as input. Rather it allocates the buffer
@ -137,20 +188,39 @@ errno can be set to the below value.</para>
<para>When you don't need the returned buffer anymore, use <para>When you don't need the returned buffer anymore, use
<function>free</function>(3) to deallocate it.</para> <function>free</function>(3) to deallocate it.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para> <para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-posix-path-list-p">
<refmeta>
<refentrytitle>cygwin_posix_path_list_p</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-posix-path-list-p"> <refnamediv>
<title>cygwin_posix_path_list_p</title> <refname>cygwin_posix_path_list_p</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" int <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int
<function>cygwin_posix_path_list_p</function></funcdef> <function>cygwin_posix_path_list_p</function></funcdef>
<paramdef>const char *<parameter>path</parameter></paramdef> <paramdef>const char *<parameter>path</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>This function tells you if the supplied <para>This function tells you if the supplied
<parameter>path</parameter> is a POSIX-style path (i.e. posix names, <parameter>path</parameter> is a POSIX-style path (i.e. posix names,
forward slashes, colon delimiters) or a Win32-style path (drive forward slashes, colon delimiters) or a Win32-style path (drive
@ -158,25 +228,44 @@ letters, reverse slashes, semicolon delimiters. The return value is
true if the path is a POSIX path. Note that "_p" means "predicate", a 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 lisp term meaning that the function tells you something about the
parameter.</para> parameter.</para>
</refsect1>
</refentry>
</sect2> <refentry id="func-cygwin-split-path">
<refmeta>
<refentrytitle>cygwin_split_path</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
</refmeta>
<sect2 id="func-cygwin-split-path"> <refnamediv>
<title>cygwin_split_path</title> <refname>cygwin_split_path</refname>
</refnamediv>
<funcsynopsis><funcprototype> <refsynopsisdiv>
<funcdef>extern "C" void <funcsynopsis>
<funcsynopsisinfo>
#include &lt;sys/cygwin.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void
<function>cygwin_split_path</function> <function>cygwin_split_path</function>
</funcdef> </funcdef>
<paramdef>const char * <parameter>path</parameter></paramdef> <paramdef>const char * <parameter>path</parameter></paramdef>
<paramdef>char * <parameter>dir</parameter></paramdef> <paramdef>char * <parameter>dir</parameter></paramdef>
<paramdef>char * <parameter>file</parameter></paramdef> <paramdef>char * <parameter>file</parameter></paramdef>
</funcprototype></funcsynopsis> </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Split a path into the directory and the file portions. Both <para>Split a path into the directory and the file portions. Both
<parameter>dir</parameter> and <parameter>file</parameter> are <parameter>dir</parameter> and <parameter>file</parameter> are
expected to point to buffers of sufficient size. </para> expected to point to buffers of sufficient size. </para>
</refsect1>
<refsect1>
<title>Example</title>
<example> <example>
<title>Example use of cygwin_split_path</title> <title>Example use of cygwin_split_path</title>
<programlisting> <programlisting>
@ -185,6 +274,7 @@ cygwin_split_path("c:/foo/bar.c", dir, file);
printf("dir=%s, file=%s\n", dir, file); printf("dir=%s, file=%s\n", dir, file);
</programlisting> </programlisting>
</example> </example>
</sect2> </refsect1>
</refentry>
</sect1> </sect1>