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
parent
a197d1d504
commit
cf1c6cd395
|
|
@ -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>
|
||||
|
||||
* fo.xsl: Render funcsynopsis elements as ANSI style function
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@
|
|||
<book id="cygwin-api" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<bookinfo>
|
||||
<date>1998-08-31</date>
|
||||
<title>Cygwin API Reference</title>
|
||||
<xi:include href="legal.xml"/>
|
||||
</bookinfo>
|
||||
|
|
@ -17,6 +16,11 @@
|
|||
<chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<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="logon-funcs.xml"/>
|
||||
<xi:include href="misc-funcs.xml"/>
|
||||
|
|
|
|||
|
|
@ -5,52 +5,91 @@
|
|||
<sect1 id="func-cygwin-login">
|
||||
<title>Helper functions to change user context</title>
|
||||
|
||||
<sect2 id="func-cygwin-logon_user">
|
||||
<title>cygwin_logon_user</title>
|
||||
<refentry id="func-cygwin-logon_user">
|
||||
<refmeta>
|
||||
<refentrytitle>cygwin_logon_user</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" HANDLE
|
||||
<refnamediv>
|
||||
<refname>cygwin_logon_user</refname>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>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>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<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>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See also</title>
|
||||
<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>
|
||||
</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">
|
||||
<title>cygwin_set_impersonation_token</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_set_impersonation_token</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" void
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>void
|
||||
<function>cygwin_set_impersonation_token</function></funcdef>
|
||||
<paramdef>const HANDLE <parameter>token</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<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>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See also</title>
|
||||
<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>
|
||||
</refsect1>
|
||||
|
||||
</sect2>
|
||||
</refentry>
|
||||
|
||||
</sect1>
|
||||
|
|
|
|||
|
|
@ -5,11 +5,24 @@
|
|||
<sect1 id="func-cygwin-misc">
|
||||
<title>Miscellaneous functions</title>
|
||||
|
||||
<sect2 id="func-cygwin-attach-handle-to-fd">
|
||||
<title>cygwin_attach_handle_to_fd</title>
|
||||
<refentry id="func-cygwin-attach-handle-to-fd">
|
||||
<refmeta>
|
||||
<refentrytitle>cygwin_attach_handle_to_fd</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" int
|
||||
<refnamediv>
|
||||
<refname>cygwin_attach_handle_to_fd</refname>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>int
|
||||
<function>cygwin_attach_handle_to_fd</function></funcdef>
|
||||
<paramdef>char *<parameter>name</parameter></paramdef>
|
||||
<paramdef>int <parameter>fd</parameter></paramdef>
|
||||
|
|
@ -17,7 +30,10 @@
|
|||
<paramdef>int <parameter>bin</parameter></paramdef>
|
||||
<paramdef>int <parameter>access</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>This function can be used to turn a Win32 "handle" into a
|
||||
posix-style file handle. <parameter>fd</parameter> may be -1 to
|
||||
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
|
||||
functions on a "best-effort" basis. Use with care. Don't expect too
|
||||
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">
|
||||
<title>cygwin_internal</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_internal</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" uintptr_t
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>uintptr_t
|
||||
<function>cygwin_internal</function></funcdef>
|
||||
<paramdef>cygwin_getinfo_types <parameter>t</parameter></paramdef>
|
||||
<paramdef><parameter>...</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<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'
|
||||
enum. The second is an optional pointer.</para>
|
||||
<para>Stay away unless you know what you're doing.</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="func-cygwin-stackdump">
|
||||
<title>cygwin_stackdump</title>
|
||||
<refentry id="func-cygwin-stackdump">
|
||||
<refmeta>
|
||||
<refentrytitle>cygwin_stackdump</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" void
|
||||
<refnamediv>
|
||||
<refname>cygwin_stackdump</refname>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>void
|
||||
<function>cygwin_stackdump</function></funcdef>
|
||||
<void />
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para> Outputs a stackdump to stderr from the called location.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
</sect1>
|
||||
|
|
|
|||
|
|
@ -5,21 +5,34 @@
|
|||
<sect1 id="func-cygwin-path">
|
||||
<title>Path conversion functions</title>
|
||||
|
||||
<para>These functions are specific to Cygwin itself, and probably
|
||||
won't be found anywhere else. </para>
|
||||
<refentry id="func-cygwin-conv-path">
|
||||
<refmeta>
|
||||
<refentrytitle>cygwin_conv_path</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo class="manual">Cygwin API Reference</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<sect2 id="func-cygwin-conv-path">
|
||||
<title>cygwin_conv_path</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_conv_path</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" ssize_t
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>ssize_t
|
||||
<function>cygwin_conv_path</function></funcdef>
|
||||
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
|
||||
<paramdef>const void * <parameter>from</parameter></paramdef>
|
||||
<paramdef>void * <parameter>to</parameter></paramdef>
|
||||
<paramdef>size_t <parameter>size</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>Use this function to convert POSIX paths in
|
||||
<parameter>from</parameter> to Win32 paths in <parameter>to</parameter>
|
||||
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.
|
||||
ENOSPC size is less than required for the conversion.
|
||||
</programlisting>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Example</title>
|
||||
<example>
|
||||
<title>Example use of cygwin_conv_path</title>
|
||||
<programlisting>
|
||||
|
|
@ -83,21 +99,37 @@ else
|
|||
]]>
|
||||
</programlisting>
|
||||
</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">
|
||||
<title>cygwin_conv_path_list</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_conv_path_list</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" ssize_t
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>ssize_t
|
||||
<function>cygwin_conv_path_list</function></funcdef>
|
||||
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
|
||||
<paramdef>const void * <parameter>from</parameter></paramdef>
|
||||
<paramdef>void * <parameter>to</parameter></paramdef>
|
||||
<paramdef>size_t <parameter>size</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<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>
|
||||
<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>
|
||||
<para><parameter>size</parameter> is the size of the buffer pointed to by
|
||||
<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>
|
||||
</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">
|
||||
<title>cygwin_create_path</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_create_path</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" void *
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>void *
|
||||
<function>cygwin_create_path</function></funcdef>
|
||||
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
|
||||
<paramdef>const void * <parameter>from</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>This is equivalent to the <function>cygwin_conv_path</function>, except
|
||||
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
|
||||
|
|
@ -137,20 +188,39 @@ errno can be set to the below value.</para>
|
|||
|
||||
<para>When you don't need the returned buffer anymore, use
|
||||
<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>
|
||||
</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">
|
||||
<title>cygwin_posix_path_list_p</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_posix_path_list_p</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" int
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>int
|
||||
<function>cygwin_posix_path_list_p</function></funcdef>
|
||||
<paramdef>const char *<parameter>path</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>This function tells you if the supplied
|
||||
<parameter>path</parameter> is a POSIX-style path (i.e. posix names,
|
||||
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
|
||||
lisp term meaning that the function tells you something about the
|
||||
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">
|
||||
<title>cygwin_split_path</title>
|
||||
<refnamediv>
|
||||
<refname>cygwin_split_path</refname>
|
||||
</refnamediv>
|
||||
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>extern "C" void
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <sys/cygwin.h>
|
||||
</funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>void
|
||||
<function>cygwin_split_path</function>
|
||||
</funcdef>
|
||||
<paramdef>const char * <parameter>path</parameter></paramdef>
|
||||
<paramdef>char * <parameter>dir</parameter></paramdef>
|
||||
<paramdef>char * <parameter>file</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>Split a path into the directory and the file portions. Both
|
||||
<parameter>dir</parameter> and <parameter>file</parameter> are
|
||||
expected to point to buffers of sufficient size. </para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Example</title>
|
||||
<example>
|
||||
<title>Example use of cygwin_split_path</title>
|
||||
<programlisting>
|
||||
|
|
@ -185,6 +274,7 @@ cygwin_split_path("c:/foo/bar.c", dir, file);
|
|||
printf("dir=%s, file=%s\n", dir, file);
|
||||
</programlisting>
|
||||
</example>
|
||||
</sect2>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
</sect1>
|
||||
|
|
|
|||
Loading…
Reference in New Issue