NAME

       Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType - manipulate platform-dependent file paths

SYNOPSIS

       #include <tcl.h>

       Tcl_SplitPath(path, argcPtr, argvPtr)

       char *
       Tcl_JoinPath(argc, argv, resultPtr)

       Tcl_PathType
       Tcl_GetPathType(path)

ARGUMENTS

       CONST char * CONST         *argvPtr(in)
                                            File  path  in  a  form  appropriate  for the current
                                            platform  (see  the   filename   manual   entry   for
                                            acceptable forms for path names).

       int           *argcPtr     (out)     Filled in with number of path elements in path.

       CONST char    ***argvPtr   (out)     *argvPtr  will  be  filled  in with the address of an
                                            array  of  pointers  to  the  strings  that  are  the
                                            extracted  elements  of path.  There will be *argcPtr
                                            valid entries in the array, followed by a NULL entry.

       int           argc         (in)      Number of elements in argv.

       CONST char * CONST         *argv(in) Array of path  elements  to  merge  together  into  a
                                            single path.

       Tcl_DString   *resultPtr   (in/out)  A  pointer to an initialized Tcl_DString to which the
                                            result of Tcl_JoinPath will be appended.
_________________________________________________________________

DESCRIPTION

       These procedures have been superceded by the objectified procedures in the FileSystem  man
       page, which are more efficient.

       These  procedures  may  be  used  to  disassemble  and reassemble file paths in a platform
       independent manner: they provide C-level access to the  same  functionality  as  the  file
       split, file join, and file pathtype commands.

       Tcl_SplitPath  breaks a path into its constituent elements, returning an array of pointers
       to the elements using argcPtr and argvPtr.  The area of memory pointed to by  *argvPtr  is
       dynamically  allocated;  in addition to the array of pointers, it also holds copies of all
       the path elements.  It is the caller's responsibility to free all of  this  storage.   For
       example, suppose that you have called Tcl_SplitPath with the following code:
              int argc;
              char *path;
              char **argv;
              ...
              Tcl_SplitPath(string, &argc, &argv);
       Then you should eventually free the storage with a call like the following:
              Tcl_Free((char *) argv);

       Tcl_JoinPath is the inverse of Tcl_SplitPath: it takes a collection of path elements given
       by argc and argv and generates a result string that is a properly  constructed  path.  The
       result  string  is  appended  to  resultPtr.   ResultPtr  must  refer  to  an  initialized
       Tcl_DString.

       If the result of Tcl_SplitPath is passed to Tcl_JoinPath, the result  will  refer  to  the
       same  location,  but  may  not  be  in  the  same form.  This is because Tcl_SplitPath and
       Tcl_JoinPath eliminate duplicate path separators and return a  normalized  form  for  each
       platform.

       Tcl_GetPathType  returns  the  type  of  the  specified path, where Tcl_PathType is one of
       TCL_PATH_ABSOLUTE,  TCL_PATH_RELATIVE,  or  TCL_PATH_VOLUME_RELATIVE.   See  the  filename
       manual entry for a description of the path types for each platform.

KEYWORDS

       file, filename, join, path, split, type