From 7d5d232b50f9f0910d10cb6635d5132f774674f5 Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Thu, 13 Mar 2008 15:18:10 +0000 Subject: * 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/path.sgml | 228 +++++++++++++++++++++--------------------------- 1 file changed, 98 insertions(+), 130 deletions(-) (limited to 'winsup/cygwin/path.sgml') 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. - -Example use of cygwin_posix_to_win32_path_list - + 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 */ - - -See also -cygwin_posix_to_win32_path_list_buf_size - - - - -cygwin_win32_to_posix_path_list - - -extern "C" void -cygwin_win32_to_posix_path_list -const char *win32 -char *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). -posix must point to a sufficiently large -buffer. See also -cygwin_win32_to_posix_path_list_buf_size +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. */ + - -cygwin_posix_to_win32_path_list_buf_size +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. - -extern "C" int -cygwin_posix_to_win32_path_list_buf_size -const char *path_list - + + 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. + -Returns the number of bytes needed to hold the result of calling - -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 + { + posix = (char *) malloc (size); + if (cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, + posix, size)) + perror ("cygwin_conv_path"); + } +]]> + + - -cygwin_win32_to_posix_path_list_buf_size + +cygwin_conv_path_list -extern "C" int -cygwin_win32_to_posix_path_list_buf_size -const char *path_list +extern "C" ssize_t +cygwin_conv_path +cygwin_conv_path_t what +const void * from +void * to +size_t size -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 - +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). -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. +See also cygwin_conv_path - -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 + +cygwin_create_path -extern "C" void -cygwin_conv_to_full_posix_path -const char *path -char *posix_path +extern "C" void * +cygwin_create_path +cygwin_conv_path_t what +const void * from -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. - - +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. - -cygwin_conv_to_full_win32_path + + ENOMEM Insufficient memory was available. + - -extern "C" void -cygwin_conv_to_full_win32_path -const char *path -char *win32_path - +When you don't need the returned buffer anymore, use +free(3) to deallocate it. -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 -- cgit v1.2.3