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 *path (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 superseded by the Tcl-value-aware 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