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

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

Tcl 7.5 Tcl_SplitPath(3)