From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13306 invoked by alias); 17 Jun 2015 12:37:48 -0000 Mailing-List: contact cygwin-patches-help@cygwin.com; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Archive: List-Help: , Sender: cygwin-patches-owner@cygwin.com Mail-Followup-To: cygwin-patches@cygwin.com Received: (qmail 13203 invoked by uid 89); 17 Jun 2015 12:37:47 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.4 required=5.0 tests=AWL,BAYES_50,KAM_LAZY_DOMAIN_SECURITY,RCVD_IN_DNSWL_NONE autolearn=no version=3.3.2 X-HELO: rgout05.bt.lon5.cpcloud.co.uk Received: from rgout05.bt.lon5.cpcloud.co.uk (HELO rgout05.bt.lon5.cpcloud.co.uk) (65.20.0.182) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 17 Jun 2015 12:37:37 +0000 X-OWM-Source-IP: 86.141.128.210(GB) X-OWM-Env-Sender: jonturney@btinternet.com X-CTCH-RefID: str=0001.0A090204.55816A0F.029E,ss=1,re=0.000,recu=0.000,reip=0.000,cl=1,cld=1,fgs=0 X-Junkmail-Premium-Raw: score=27/50,refid=2.7.2:2015.6.17.94516:17:27.888,ip=86.141.128.210,rules=__HAS_FROM, __TO_MALFORMED_2, __TO_NO_NAME, __SUBJ_ALPHA_END, __HAS_MSGID, __SANE_MSGID, __HAS_X_MAILER, __IN_REP_TO, __REFERENCES, __ANY_URI, __MAL_TELEKOM_URI, __CP_URI_IN_BODY, BODY_SIZE_10000_PLUS, __MIME_TEXT_ONLY, RDNS_GENERIC_POOLED, __URI_NS, SXL_IP_DYNAMIC[210.128.141.86.fur], HTML_00_01, HTML_00_10, RDNS_SUSP_GENERIC, RDNS_SUSP, REFERENCES X-CTCH-Spam: Unknown Received: from localhost.localdomain (86.141.128.210) by rgout05.bt.lon5.cpcloud.co.uk (8.6.122.06) (authenticated as jonturney@btinternet.com) id 55814C5E00039B52; Wed, 17 Jun 2015 13:37:28 +0100 From: Jon TURNEY To: cygwin-patches@cygwin.com Cc: Jon TURNEY Subject: [PATCH 3/5] winsup/doc: Convert cygwin-api function documentation to refentry elements Date: Wed, 17 Jun 2015 12:37:00 -0000 Message-Id: <1434544626-2516-4-git-send-email-jon.turney@dronecode.org.uk> In-Reply-To: <1434544626-2516-1-git-send-email-jon.turney@dronecode.org.uk> References: <1434544626-2516-1-git-send-email-jon.turney@dronecode.org.uk> X-SW-Source: 2015-q2/txt/msg00089.txt.bz2 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 funcsynopsisino 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 * 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 --- winsup/doc/ChangeLog | 8 +++ winsup/doc/cygwin-api.xml | 6 +- winsup/doc/logon-funcs.xml | 59 +++++++++++++--- winsup/doc/misc-funcs.xml | 81 ++++++++++++++++----- winsup/doc/path.xml | 172 ++++++++++++++++++++++++++++++++++----------- 5 files changed, 258 insertions(+), 68 deletions(-) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 347adcb..ddee4e9 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,5 +1,13 @@ 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 prototypes. * html.xsl: Ditto. diff --git a/winsup/doc/cygwin-api.xml b/winsup/doc/cygwin-api.xml index ac98c00..7b831d9 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 9e32ad6..084b0c7 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 b164341..16b3d61 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 + 3 + Cygwin API Reference + - -cygwin_stackdump + + cygwin_stackdump + - -extern "C" void + + + +#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 06a252b..bea6798 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 - - -extern "C" ssize_t + + + cygwin_conv_path + 3 + Cygwin API Reference + + + + cygwin_conv_path + + + + + +#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 - - -extern "C" ssize_t + + + + + + cygwin_conv_path_list + 3 + Cygwin API Reference + + + + cygwin_conv_path_list + + + + + +#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 - - -extern "C" void * + + + + + + cygwin_create_path + 3 + Cygwin API Reference + + + + cygwin_create_path + + + + + +#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 - - -extern "C" int + + + + + + cygwin_posix_path_list_p + 3 + Cygwin API Reference + + + + cygwin_posix_path_list_p + + + + + +#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 - - -extern "C" void + + + + + + cygwin_split_path + 3 + Cygwin API Reference + + + + cygwin_split_path + + + + + +#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); - + + -- 2.1.4