newlib/winsup/doc/path.xml

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="cygwin-functions" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Cygwin Functions</title>

<para>These functions are specific to Cygwin itself, and probably
won't be found anywhere else.  </para>

<sect1 id="func-cygwin-conv-path">
<title>cygwin_conv_path</title>

<funcsynopsis><funcprototype>
<funcdef>extern "C" ssize_t
<function>cygwin_conv_path</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef>
<paramdef>void * <parameter>to</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype></funcsynopsis>

<para>Use this function to convert POSIX paths in
<parameter>from</parameter> to Win32 paths in <parameter>to</parameter>
or, vice versa, Win32 paths in <parameter>from</parameter> to POSIX paths
in <parameter>to</parameter>.  <parameter>what</parameter>
defines the direction of this conversion and can be any of the below
values.</para>

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

<para>You can additionally or the following values to
<parameter>what</parameter>, to define whether you want the resulting
path in <parameter>to</parameter> to be absolute or if you want to keep
relative paths in relative notation.  Creating absolute paths is the
default.</para>

<programlisting>
  CCP_ABSOLUTE = 0,       /* Request absolute path (default).             */
  CCP_RELATIVE = 0x100    /* Request to keep path relative.               */
</programlisting>

<para><parameter>size</parameter> is the size of the buffer pointed to
by <parameter>to</parameter> in bytes.  If <parameter>size</parameter>
is 0, <function>cygwin_conv_path</function> 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.</para>

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

<example>
<title>Example use of cygwin_conv_path</title>
<programlisting>
<![CDATA[
#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");
  }
]]>
</programlisting>
</example>

</sect1>

<sect1 id="func-cygwin-conv-path-list">
<title>cygwin_conv_path_list</title>

<funcsynopsis><funcprototype>
<funcdef>extern "C" ssize_t
<function>cygwin_conv_path_list</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef>
<paramdef>void * <parameter>to</parameter></paramdef>
<paramdef>size_t <parameter>size</parameter></paramdef>
</funcprototype></funcsynopsis>

<para>This is the same as <function>cygwin_conv_path</function>, but the
input is treated as a path list in $PATH or %PATH% notation.</para>
<para>If <parameter>what</parameter> 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).</para>
<para>If <parameter>what</parameter> 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).</para>
<para><parameter>size</parameter> is the size of the buffer pointed to by
<parameter>to</parameter> in bytes.</para>

<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>

</sect1>

<sect1 id="func-cygwin-create-path">
<title>cygwin_create_path</title>

<funcsynopsis><funcprototype>
<funcdef>extern "C" void *
<function>cygwin_create_path</function></funcdef>
<paramdef>cygwin_conv_path_t <parameter>what</parameter></paramdef>
<paramdef>const void * <parameter>from</parameter></paramdef>
</funcprototype></funcsynopsis>

<para>This is equivalent to the <function>cygwin_conv_path</function>, except
that <function>cygwin_create_path</function> does not take a buffer pointer
for the result of the conversion as input.  Rather it allocates the buffer
itself using <function>malloc</function>(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 <function>cygwin_conv_path</function>.  Additionally
errno can be set to the below value.</para>

<programlisting>
    ENOMEM        Insufficient memory was available.
</programlisting>

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

<para>See also <link linkend="func-cygwin-conv-path">cygwin_conv_path</link></para>

</sect1>

<sect1 id="func-cygwin-posix-path-list-p">
<title>cygwin_posix_path_list_p</title>

<funcsynopsis><funcprototype>
<funcdef>extern "C" int
<function>cygwin_posix_path_list_p</function></funcdef>
<paramdef>const char *<parameter>path</parameter></paramdef>
</funcprototype></funcsynopsis>

<para>This function tells you if the supplied
<parameter>path</parameter> 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.</para>

</sect1>

<sect1 id="func-cygwin-split-path">
<title>cygwin_split_path</title>

<funcsynopsis><funcprototype>
<funcdef>extern "C" void
<function>cygwin_split_path</function>
</funcdef>
<paramdef>const char * <parameter>path</parameter></paramdef>
<paramdef>char * <parameter>dir</parameter></paramdef>
<paramdef>char * <parameter>file</parameter></paramdef>
</funcprototype></funcsynopsis>

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

<example>
<title>Example use of cygwin_split_path</title>
<programlisting>
char dir[200], file[100];
cygwin_split_path("c:/foo/bar.c", dir, file);
printf("dir=%s, file=%s\n", dir, file);
</programlisting>
</example>
</sect1>

</chapter>