diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index bde9d7217..a693b18c8 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,11 @@ +2015-06-17 Jon Turney + + * 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 * fo.xsl: Render funcsynopsis elements as ANSI style function diff --git a/winsup/doc/cygwin-api.xml b/winsup/doc/cygwin-api.xml index ac98c0033..7b831d9f4 100644 --- a/winsup/doc/cygwin-api.xml +++ b/winsup/doc/cygwin-api.xml @@ -5,7 +5,6 @@ - 1998-08-31 Cygwin API Reference @@ -17,6 +16,11 @@ Cygwin Functions + + These functions are specific to Cygwin itself, and probably won't be + found anywhere else. + + diff --git a/winsup/doc/logon-funcs.xml b/winsup/doc/logon-funcs.xml index 9e32ad626..084b0c798 100644 --- a/winsup/doc/logon-funcs.xml +++ b/winsup/doc/logon-funcs.xml @@ -5,52 +5,91 @@ Helper functions to change user context - -cygwin_logon_user + + + cygwin_logon_user + 3 + Cygwin API Reference + - -extern "C" HANDLE + + cygwin_logon_user + + + + + +#include <sys/cygwin.h> + + +HANDLE cygwin_logon_user const struct passwd *passwd_entry const char *password + + + Description 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 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 See also the chapter Switching the user context in the Cygwin User's guide. See also cygwin_set_impersonation_token + + - + + + cygwin_set_impersonation_token + 3 + Cygwin API Reference + - -cygwin_set_impersonation_token + + cygwin_set_impersonation_token + - -extern "C" void + + + +#include <sys/cygwin.h> + + +void cygwin_set_impersonation_token const HANDLE token + + + Description 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 See also the chapter Switching the user context in the Cygwin User's guide. See also cygwin_logon_user + - + diff --git a/winsup/doc/misc-funcs.xml b/winsup/doc/misc-funcs.xml index b16434152..16b3d61eb 100644 --- a/winsup/doc/misc-funcs.xml +++ b/winsup/doc/misc-funcs.xml @@ -5,11 +5,24 @@ Miscellaneous functions - -cygwin_attach_handle_to_fd + + + cygwin_attach_handle_to_fd + 3 + Cygwin API Reference + - -extern "C" int + + cygwin_attach_handle_to_fd + + + + + +#include <sys/cygwin.h> + + +int cygwin_attach_handle_to_fd char *name int fd @@ -17,7 +30,10 @@ int bin int access + + + Description This function can be used to turn a Win32 "handle" into a posix-style file handle. fd may be -1 to make cygwin allocate a handle; the actual handle is returned @@ -27,38 +43,71 @@ in all cases. 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. + + - + + + cygwin_internal + 3 + Cygwin API Reference + - -cygwin_internal + + cygwin_internal + - -extern "C" uintptr_t + + + +#include <sys/cygwin.h> + + +uintptr_t cygwin_internal cygwin_getinfo_types t ... + + + Description 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. Stay away unless you know what you're doing. + + - - -cygwin_stackdump + + + cygwin_stackdump + 3 + Cygwin API Reference + - -extern "C" void + + cygwin_stackdump + + + + + +#include <sys/cygwin.h> + + +void cygwin_stackdump + + + Description Outputs a stackdump to stderr from the called location. - - + + diff --git a/winsup/doc/path.xml b/winsup/doc/path.xml index 06a252bb0..bea67980a 100644 --- a/winsup/doc/path.xml +++ b/winsup/doc/path.xml @@ -5,21 +5,34 @@ Path conversion functions -These functions are specific to Cygwin itself, and probably -won't be found anywhere else. + + + cygwin_conv_path + 3 + Cygwin API Reference + - -cygwin_conv_path + + cygwin_conv_path + - -extern "C" ssize_t + + + +#include <sys/cygwin.h> + + +ssize_t cygwin_conv_path cygwin_conv_path_t what const void * from void * to size_t size + + + Description Use this function to convert POSIX paths in from to Win32 paths in to or, vice versa, Win32 paths in from to POSIX paths @@ -58,7 +71,10 @@ error and errno is set to one of the below values. of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH. ENOSPC size is less than required for the conversion. + + + Example Example use of cygwin_conv_path @@ -83,21 +99,37 @@ else ]]> + + - + + + cygwin_conv_path_list + 3 + Cygwin API Reference + - -cygwin_conv_path_list + + cygwin_conv_path_list + - -extern "C" ssize_t + + + +#include <sys/cygwin.h> + + +ssize_t cygwin_conv_path_list cygwin_conv_path_t what const void * from void * to size_t size + + + Description 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 @@ -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). size is the size of the buffer pointed to by to in bytes. + + + See also See also cygwin_conv_path + + - + + + cygwin_create_path + 3 + Cygwin API Reference + - -cygwin_create_path + + cygwin_create_path + - -extern "C" void * + + + +#include <sys/cygwin.h> + + +void * cygwin_create_path cygwin_conv_path_t what const void * from + + + Description 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 @@ -137,20 +188,39 @@ errno can be set to the below value. When you don't need the returned buffer anymore, use free(3) to deallocate it. + + + See also See also cygwin_conv_path + + - + + + cygwin_posix_path_list_p + 3 + Cygwin API Reference + - -cygwin_posix_path_list_p + + cygwin_posix_path_list_p + - -extern "C" int + + + +#include <sys/cygwin.h> + + +int cygwin_posix_path_list_p const char *path + + + Description This function tells you if the supplied path 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. + + - + + + cygwin_split_path + 3 + Cygwin API Reference + - -cygwin_split_path + + cygwin_split_path + - -extern "C" void + + + +#include <sys/cygwin.h> + + +void cygwin_split_path const char * path char * dir char * file + + + Description Split a path into the directory and the file portions. Both dir and file are expected to point to buffers of sufficient size. + + + Example Example use of cygwin_split_path @@ -185,6 +274,7 @@ cygwin_split_path("c:/foo/bar.c", dir, file); printf("dir=%s, file=%s\n", dir, file); - + +