SplitPath

Tcl_SplitPath(3)            Tcl Library Procedures            Tcl_SplitPath(3)



______________________________________________________________________________

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
       char          *path        (in)      File path in  a  form  appropriate
                                            for  the current platform (see the
                                            filename manual entry for  accept-
                                            able forms for path names).

       int           *argcPtr     (out)     Filled in with number of path ele-
                                            ments in path.

       char          ***argvPtr   (out)     *argvPtr will be  filled  in  with
                                            the  address of an array of point-
                                            ers 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.

       char          **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  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 com-
       mands.

       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 ele-
       ments.  It is the caller's responsibility to free all of this  storage.
       For  example,  suppose that you have called Tcl_SplitPath with the fol-
       lowing code:
              int argc;
              char *path;
              char **argv;
              ...
              Tcl_SplitPath(string, &argc, &argv);
       Then you should eventually free the storage with a call like  the  fol-
       lowing:
              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 sep-
       arators 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 descrip-
       tion of the path types for each platform.


KEYWORDS
       file, filename, join, path, split, type



Tcl                                   7.5                     Tcl_SplitPath(3)