From 7d5d232b50f9f0910d10cb6635d5132f774674f5 Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Thu, 13 Mar 2008 15:18:10 +0000 Subject: [PATCH] * 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. --- winsup/cygwin/ChangeLog | 12 ++ winsup/cygwin/include/sys/cygwin.h | 11 +- winsup/cygwin/path.sgml | 242 +++++++++++++---------------- winsup/cygwin/security.sgml | 45 ++++++ winsup/cygwin/shared.sgml | 17 -- 5 files changed, 167 insertions(+), 160 deletions(-) create mode 100644 winsup/cygwin/security.sgml delete mode 100644 winsup/cygwin/shared.sgml diff --git a/winsup/cygwin/ChangeLog b/winsup/cygwin/ChangeLog index f36a1797d..01408f2f5 100644 --- a/winsup/cygwin/ChangeLog +++ b/winsup/cygwin/ChangeLog @@ -1,3 +1,15 @@ +2008-03-13 Corinna Vinschen + + * 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 * 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 26daf0f7c..5a7c14df0 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 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 05e01d86b..249f48de7 100644 --- a/winsup/cygwin/path.sgml +++ b/winsup/cygwin/path.sgml @@ -1,163 +1,131 @@ - -cygwin_posix_to_win32_path_list + +cygwin_conv_path -extern "C" void -cygwin_posix_to_win32_path_list -const char *posix -char *win32 +extern "C" ssize_t +cygwin_conv_path +cygwin_conv_path_t what +const void * from +void * to +size_t size -Given a POSIX path-style string (i.e. /foo:/bar) convert it to -the equivalent Win32 path-style string (i.e. d:\;e:\bar). -win32 must point to a sufficiently large -buffer. +Use this function to convert POSIX paths in +from to Win32 paths in to +or, vice versa, Win32 paths in from to POSIX paths +in to. what +defines the direction of this conversion and can be any of the below +values. + + + 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 */ + + +You can additionally or the following values to +what, to define whether you want the resulting +path in to to be absolute or if you want to keep +relative paths in relative notation. Creating absolute paths is the +default. + + + CCP_ABSOLUTE = 0, /* Request absolute path (default). */ + CCP_RELATIVE = 0x100 /* Request to keep path relative. */ + + +If size is 0, +cygwin_conv_path 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. + + + 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. + -Example use of cygwin_posix_to_win32_path_list +Example use of cygwin_conv_path + +/* 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 { - _win32epath = (char *) xmalloc - (cygwin_posix_to_win32_path_list_buf_size (_epath)); - cygwin_posix_to_win32_path_list (_epath, _win32epath); - } + posix = (char *) malloc (size); + if (cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, + posix, size)) + perror ("cygwin_conv_path"); + } ]]> -See also -cygwin_posix_to_win32_path_list_buf_size + + + +cygwin_conv_path_list + + +extern "C" ssize_t +cygwin_conv_path +cygwin_conv_path_t what +const void * from +void * to +size_t size + + +This is the same as cygwin_conv_path, but the +input is treated as a path list in $PATH or %PATH% notation. +If what 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). +If what 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). + +See also cygwin_conv_path - -cygwin_win32_to_posix_path_list + +cygwin_create_path -extern "C" void -cygwin_win32_to_posix_path_list -const char *win32 -char *posix +extern "C" void * +cygwin_create_path +cygwin_conv_path_t what +const void * from -Given a Win32 path-style string (i.e. d:\;e:\bar) convert it to -the equivalent POSIX path-style string (i.e. /foo:/bar). -posix must point to a sufficiently large -buffer. See also -cygwin_win32_to_posix_path_list_buf_size +This is equivalent to the cygwin_conv_path, except +that cygwin_create_path does not take a buffer pointer +for the result of the conversion as input. Rather it allocates the buffer +itself using malloc(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 cygwin_conv_path. Additionally +errno can be set to the below value. - + + ENOMEM Insufficient memory was available. + - -cygwin_posix_to_win32_path_list_buf_size +When you don't need the returned buffer anymore, use +free(3) to deallocate it. - -extern "C" int -cygwin_posix_to_win32_path_list_buf_size -const char *path_list - - -Returns the number of bytes needed to hold the result of calling - -cygwin_posix_to_win32_path_list. - - - - -cygwin_win32_to_posix_path_list_buf_size - - -extern "C" int -cygwin_win32_to_posix_path_list_buf_size -const char *path_list - - -Tells you how many bytes are needed for the results of -cygwin_win32_to_posix_path_list. - - - - -cygwin_conv_to_posix_path - - -extern "C" void -cygwin_conv_to_posix_path -const char *path -char *posix_path - - -Converts a Win32 path to a POSIX path. If -path is already a POSIX path, leaves it alone. -If path is relative, then -posix_path will also be relative. Note that -posix_path must point to a buffer of sufficient -size; use MAX_PATH if needed. - - - - -cygwin_conv_to_win32_path - - -extern "C" void -cygwin_conv_to_win32_path -const char *path -char *win32_path - - -Converts a POSIX path to a Win32 path. If -path is already a Win32 path, leaves it alone. -If path is relative, then -win32_path will also be relative. Note that -win32_path must point to a buffer of sufficient -size; use MAX_PATH if needed. - - - -cygwin_conv_to_full_posix_path - - -extern "C" void -cygwin_conv_to_full_posix_path -const char *path -char *posix_path - - -Converts a Win32 path to a POSIX path. If -path is already a POSIX path, leaves it alone. -If path is relative, then -posix_path will be converted to an absolute -path. Note that posix_path must point to a -buffer of sufficient size; use MAX_PATH if needed. - - - - -cygwin_conv_to_full_win32_path - - -extern "C" void -cygwin_conv_to_full_win32_path -const char *path -char *win32_path - - -Converts a POSIX path to a Win32 path. If -path is already a Win32 path, leaves it alone. -If path is relative, then -win32_path will be converted to an absolute -path. Note that win32_path must point to a -buffer of sufficient size; use MAX_PATH if needed. +See also cygwin_conv_path diff --git a/winsup/cygwin/security.sgml b/winsup/cygwin/security.sgml new file mode 100644 index 000000000..b286ef540 --- /dev/null +++ b/winsup/cygwin/security.sgml @@ -0,0 +1,45 @@ + +cygwin_logon_user + + +extern "C" HANDLE +cygwin_logon_user +const struct passwd *passwd_entry +const char *password + + +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 cygwin_set_impersonation_token +to impersonate that user. This function can only be called from a process +which has the required NT user rights to perform a logon. + +See also the chapter "New setuid concept" in the Cygwin user's guide. + + +See also cygwin_set_impersonation_token + + + + +cygwin_set_impersonation_token + + +extern "C" void +cygwin_set_impersonation_token +const HANDLE token + + +Use this function to enable the token given as parameter as +impersonation token for the next call to setuid or +seteuid. Use +cygwin_set_impersonation_token together with +cygwin_logon_user to impersonate users using +password authentication. + +See also the chapter "New setuid concept" in the Cygwin user's guide. + + +See also cygwin_logon_user + + diff --git a/winsup/cygwin/shared.sgml b/winsup/cygwin/shared.sgml deleted file mode 100644 index b8d111a55..000000000 --- a/winsup/cygwin/shared.sgml +++ /dev/null @@ -1,17 +0,0 @@ - - -cygwin_getshared - - -shared_info * -cygwin_getshared - - - -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 -mount and ps. - - -