Chapter 2. Cygwin Functions

Table of Contents

Path conversion functions
cygwin_conv_path
cygwin_conv_path_list
cygwin_create_path
cygwin_posix_path_list_p
cygwin_split_path
Helper functions to change user context
cygwin_logon_user
cygwin_set_impersonation_token
Miscellaneous functions
cygwin_attach_handle_to_fd
cygwin_internal
cygwin_stackdump

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(what,  
 from,  
 to,  
 size); 
cygwin_conv_path_t what;
const void * from;
void * to;
size_t size;
 

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.               */

size is the size of the buffer pointed to by to in bytes. 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 or from is NULL.
    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 2.1. Example use of cygwin_conv_path


#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");
  }


cygwin_conv_path_list

extern "C" ssize_t cygwin_conv_path_list(what,  
 from,  
 to,  
 size); 
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).

size is the size of the buffer pointed to by to in bytes.

See also cygwin_conv_path

cygwin_create_path

extern "C" void * cygwin_create_path(what,  
 from); 
cygwin_conv_path_t what;
const void * from;
 

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.

When you don't need the returned buffer anymore, use free(3) to deallocate it.

See also cygwin_conv_path

cygwin_posix_path_list_p

extern "C" int cygwin_posix_path_list_p(path); 
const char *path;
 

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 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 (path,  
 dir,  
 file); 
const char * path;
char * dir;
char * file;
 

Split a path into the directory and the file portions. Both dir and file are expected to point to buffers of sufficient size.

Example 2.2. Example use of cygwin_split_path

char dir[200], file[100];
cygwin_split_path("c:/foo/bar.c", dir, file);
printf("dir=%s, file=%s\n", dir, file);