diff options
| -rw-r--r-- | winsup/cygwin/ChangeLog | 12 | ||||
| -rw-r--r-- | winsup/cygwin/include/sys/cygwin.h | 11 | ||||
| -rw-r--r-- | winsup/cygwin/path.sgml | 228 | ||||
| -rw-r--r-- | winsup/cygwin/security.sgml | 45 | ||||
| -rw-r--r-- | winsup/cygwin/shared.sgml | 17 |
5 files changed, 160 insertions, 153 deletions
diff --git a/winsup/cygwin/ChangeLog b/winsup/cygwin/ChangeLog index f36a179..01408f2 100644 --- a/winsup/cygwin/ChangeLog +++ b/winsup/cygwin/ChangeLog @@ -1,3 +1,15 @@ +2008-03-13 Corinna Vinschen <corinna@vinschen.de> + + * path.sgml: Remove documentation for old path API. Add documentation + for new path API. + * security.sgml: New file to document cygwin_set_impersonation_token + and cygwin_logon_user with only eight years of delay. + * shared.sgml: Remove file. + * include/sys/cygwin.h (cygwin32_attach_handle_to_fd): Move declaration + into fully deprecated function block. + (cygwin_logon_user): Move declaration down to declaration of + cygwin_set_impersonation_token. + 2008-03-12 Corinna Vinschen <corinna@vinschen.de> * syscalls.cc (rename): Just return with 0 if filenames are identical, diff --git a/winsup/cygwin/include/sys/cygwin.h b/winsup/cygwin/include/sys/cygwin.h index 26daf0f..5a7c14d 100644 --- a/winsup/cygwin/include/sys/cygwin.h +++ b/winsup/cygwin/include/sys/cygwin.h @@ -32,6 +32,7 @@ extern void cygwin32_conv_to_posix_path (const char *, char *); extern void cygwin32_conv_to_full_posix_path (const char *, char *); extern int cygwin32_posix_path_list_p (const char *); extern void cygwin32_split_path (const char *, char *, char *); +extern int cygwin32_attach_handle_to_fd (char *, int, HANDLE, mode_t, DWORD); #endif /* DEPRECATED INTERFACES. These are restricted to MAX_PATH length. @@ -168,11 +169,6 @@ enum PID_EXITED = 0x80000000 /* Free entry. */ }; -#ifdef WINVER -#ifdef _PATH_PASSWD -extern HANDLE cygwin_logon_user (const struct passwd *, const char *); -#endif - /* This lives in the app and is initialized before jumping into the DLL. It should only contain stuff which the user's process needs to see, or which is needed before the user pointer is initialized, or is needed to @@ -263,10 +259,13 @@ extern void cygwin_premain1 (int argc, char **argv, struct per_process *); extern void cygwin_premain2 (int argc, char **argv, struct per_process *); extern void cygwin_premain3 (int argc, char **argv, struct per_process *); +#ifdef WINVER +#ifdef _PATH_PASSWD +extern HANDLE cygwin_logon_user (const struct passwd *, const char *); +#endif extern void cygwin_set_impersonation_token (const HANDLE); /* included if <windows.h> is included */ -extern int cygwin32_attach_handle_to_fd (char *, int, HANDLE, mode_t, DWORD); extern int cygwin_attach_handle_to_fd (char *, int, HANDLE, mode_t, DWORD); #ifdef __CYGWIN__ diff --git a/winsup/cygwin/path.sgml b/winsup/cygwin/path.sgml index 05e01d8..249f48d 100644 --- a/winsup/cygwin/path.sgml +++ b/winsup/cygwin/path.sgml @@ -1,163 +1,131 @@ -<sect1 id="func-cygwin-posix-to-win32-path-list"> -<title>cygwin_posix_to_win32_path_list</title> +<sect1 id="func-cygwin-conv-path"> +<title>cygwin_conv_path</title> <funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_posix_to_win32_path_list</function></funcdef> -<paramdef>const char *<parameter>posix</parameter></paramdef> -<paramdef>char *<parameter>win32</parameter></paramdef> +<funcdef>extern "C" 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> -<para>Given a POSIX path-style string (i.e. /foo:/bar) convert it to -the equivalent Win32 path-style string (i.e. d:\;e:\bar). -<parameter>win32</parameter> must point to a sufficiently large -buffer.</para> +<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 +in <parameter>to</parameter>. <parameter>what</parameter> +defines the direction of this conversion and can be any of the below +values.</para> -<example> -<title>Example use of cygwin_posix_to_win32_path_list</title> <programlisting> -<![CDATA[ -char *_epath; -char *_win32epath; -_epath = _win32epath = getenv (NAME); -/* If we have a POSIX path list, convert to win32 path list */ -if (_epath != NULL && *_epath != 0 - && cygwin_posix_path_list_p (_epath)) - { - _win32epath = (char *) xmalloc - (cygwin_posix_to_win32_path_list_buf_size (_epath)); - cygwin_posix_to_win32_path_list (_epath, _win32epath); - } -]]> + CCP_POSIX_TO_WIN_A /* from is char *posix, to is char *win32 */ + CCP_POSIX_TO_WIN_W, /* from is char *posix, to is wchar_t *win32 */ + CCP_WIN_A_TO_POSIX, /* from is char *win32, to is char *posix */ + CCP_WIN_W_TO_POSIX, /* from is wchar_t *win32, to is char *posix */ </programlisting> -</example> - -<para>See also <link linkend="func-cygwin-posix-to-win32-path-list-buf-size"> -cygwin_posix_to_win32_path_list_buf_size</link></para> - -</sect1> - -<sect1 id="func-cygwin-win32-to-posix-path-list"> -<title>cygwin_win32_to_posix_path_list</title> - -<funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_win32_to_posix_path_list</function></funcdef> -<paramdef>const char *<parameter>win32</parameter></paramdef> -<paramdef>char *<parameter>posix</parameter></paramdef> -</funcprototype></funcsynopsis> -<para>Given a Win32 path-style string (i.e. d:\;e:\bar) convert it to -the equivalent POSIX path-style string (i.e. /foo:/bar). -<parameter>posix</parameter> must point to a sufficiently large -buffer. See also <link -linkend="func-cygwin-win32-to-posix-path-list-buf-size"> -cygwin_win32_to_posix_path_list_buf_size</link></para> +<para>You can additionally or the following values to +<parameter>what</parameter>, to define whether you want the resulting +path in <parameter>to</parameter> to be absolute or if you want to keep +relative paths in relative notation. Creating absolute paths is the +default.</para> -</sect1> +<programlisting> + CCP_ABSOLUTE = 0, /* Request absolute path (default). */ + CCP_RELATIVE = 0x100 /* Request to keep path relative. */ +</programlisting> -<sect1 id="func-cygwin-posix-to-win32-path-list-buf-size"> -<title>cygwin_posix_to_win32_path_list_buf_size</title> +<para>If <parameter>size</parameter> is 0, +<function>cygwin_conv_path</function> just returns the required buffer +size in bytes. Otherwise, it returns 0 on success, or -1 on error and +errno is set to one of the below values.</para> -<funcsynopsis><funcprototype> -<funcdef>extern "C" int -<function>cygwin_posix_to_win32_path_list_buf_size</function></funcdef> -<paramdef>const char *<parameter>path_list</parameter></paramdef> -</funcprototype></funcsynopsis> +<programlisting> + EINVAL what has an invalid value. + EFAULT from or to point into nirvana. + ENAMETOOLONG the resulting path is longer than 32K, or, in case + of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH. + ENOSPC size is less than required for the conversion. +</programlisting> -<para>Returns the number of bytes needed to hold the result of calling -<link linkend="func-cygwin-posix-to-win32-path-list"> -cygwin_posix_to_win32_path_list</link>.</para> +<example> +<title>Example use of cygwin_conv_path</title> +<programlisting> +<![CDATA[ +#include <sys/cygwin.h> + +/* Conversion from incoming Win32 path given as wchar_t *win32 to POSIX path. + If incoming path is a relative path, stick to it. First ask how big + the output buffer has to be and allocate space dynamically. */ +ssize_t size; +char *posix; +size = cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, NULL, 0); +if (size < 0) + perror ("cygwin_conv_path"); +else + { + posix = (char *) malloc (size); + if (cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, + posix, size)) + perror ("cygwin_conv_path"); + } +]]> +</programlisting> +</example> </sect1> -<sect1 id="func-cygwin-win32-to-posix-path-list-buf-size"> -<title>cygwin_win32_to_posix_path_list_buf_size</title> +<sect1 id="func-cygwin-conv-path-list"> +<title>cygwin_conv_path_list</title> <funcsynopsis><funcprototype> -<funcdef>extern "C" int -<function>cygwin_win32_to_posix_path_list_buf_size</function></funcdef> -<paramdef>const char *<parameter>path_list</parameter></paramdef> +<funcdef>extern "C" 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> -<para>Tells you how many bytes are needed for the results of <link -linkend="func-cygwin-win32-to-posix-path-list"> -cygwin_win32_to_posix_path_list</link>.</para> - -</sect1> - -<sect1 id="func-cygwin-conv-to-posix-path"> -<title>cygwin_conv_to_posix_path</title> - -<funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_conv_to_posix_path</function></funcdef> -<paramdef>const char *<parameter>path</parameter></paramdef> -<paramdef>char *<parameter>posix_path</parameter></paramdef> -</funcprototype></funcsynopsis> +<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 +CCP_POSIX_TO_WIN_W, given a POSIX $PATH-style string (i.e. /foo:/bar) +convert it to the equivalent Win32 %PATH%-style string (i.e. d:\;e:\bar).</para> +<para>If <parameter>what</parameter> is CCP_WIN_A_TO_POSIX or +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>Converts a Win32 path to a POSIX path. If -<parameter>path</parameter> is already a POSIX path, leaves it alone. -If <parameter>path</parameter> is relative, then -<parameter>posix_path</parameter> will also be relative. Note that -<parameter>posix_path</parameter> must point to a buffer of sufficient -size; use MAX_PATH if needed.</para> +<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para> </sect1> -<sect1 id="func-cygwin-conv-to-win32-path"> -<title>cygwin_conv_to_win32_path</title> - -<funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_conv_to_win32_path</function></funcdef> -<paramdef>const char *<parameter>path</parameter></paramdef> -<paramdef>char *<parameter>win32_path</parameter></paramdef> -</funcprototype></funcsynopsis> - -<para>Converts a POSIX path to a Win32 path. If -<parameter>path</parameter> is already a Win32 path, leaves it alone. -If <parameter>path</parameter> is relative, then -<parameter>win32_path</parameter> will also be relative. Note that -<parameter>win32_path</parameter> must point to a buffer of sufficient -size; use MAX_PATH if needed.</para> - -</sect1> -<sect1 id="func-cygwin-conv-to-full-posix-path"> -<title>cygwin_conv_to_full_posix_path</title> +<sect1 id="func-cygwin-create-path"> +<title>cygwin_create_path</title> <funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_conv_to_full_posix_path</function></funcdef> -<paramdef>const char *<parameter>path</parameter></paramdef> -<paramdef>char *<parameter>posix_path</parameter></paramdef> +<funcdef>extern "C" 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> -<para>Converts a Win32 path to a POSIX path. If -<parameter>path</parameter> is already a POSIX path, leaves it alone. -If <parameter>path</parameter> is relative, then -<parameter>posix_path</parameter> will be converted to an absolute -path. Note that <parameter>posix_path</parameter> must point to a -buffer of sufficient size; use MAX_PATH if needed.</para> - -</sect1> +<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 +itself using <function>malloc</function>(3) and returns a pointer to this +buffer. In case of error it returns NULL and sets errno to one of the +values defined for <function>cygwin_conv_path</function>. Additionally +errno can be set to the below value.</para> -<sect1 id="func-cygwin-conv-to-full-win32-path"> -<title>cygwin_conv_to_full_win32_path</title> +<programlisting> + ENOMEM Insufficient memory was available. +</programlisting> -<funcsynopsis><funcprototype> -<funcdef>extern "C" void -<function>cygwin_conv_to_full_win32_path</function></funcdef> -<paramdef>const char *<parameter>path</parameter></paramdef> -<paramdef>char *<parameter>win32_path</parameter></paramdef> -</funcprototype></funcsynopsis> +<para>When you don't need the returned buffer anymore, use +<function>free</function>(3) to deallocate it.</para> -<para>Converts a POSIX path to a Win32 path. If -<parameter>path</parameter> is already a Win32 path, leaves it alone. -If <parameter>path</parameter> is relative, then -<parameter>win32_path</parameter> will be converted to an absolute -path. Note that <parameter>win32_path</parameter> must point to a -buffer of sufficient size; use MAX_PATH if needed.</para> +<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para> </sect1> diff --git a/winsup/cygwin/security.sgml b/winsup/cygwin/security.sgml new file mode 100644 index 0000000..b286ef5 --- /dev/null +++ b/winsup/cygwin/security.sgml @@ -0,0 +1,45 @@ +<sect1 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 ot 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 "New setuid concept" in the Cygwin user's guide. +</para> + +<para>See also <link linkend="func-cygwin-set-impersonation-token">cygwin_set_impersonation_token</link></para> + +</sect1> + +<sect1 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 "New setuid concept" in the Cygwin user's guide. +</para> + +<para>See also <link linkend="func-cygwin-logon_user">cygwin_logon_user</link></para> + +</sect1> diff --git a/winsup/cygwin/shared.sgml b/winsup/cygwin/shared.sgml deleted file mode 100644 index b8d111a..0000000 --- a/winsup/cygwin/shared.sgml +++ /dev/null @@ -1,17 +0,0 @@ - -<sect1 id="func-cygwin-getshared"> -<title>cygwin_getshared</title> - -<funcsynopsis><funcprototype> -<funcdef>shared_info * -<function>cygwin_getshared</function></funcdef> -<void /> -</funcprototype></funcsynopsis> - -<para>Returns a pointer to an internal Cygwin memory structure -containing shared information used by cooperating cygwin processes. -This function is intended for use only by "system" programs like -<filename>mount</filename> and <filename>ps</filename>. -</para> - -</sect1> |