2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
11 Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths
14 \fB#include <tcl.h>\fR
16 \fBTcl_SplitPath\fR(\fIpath, argcPtr, argvPtr\fR)
19 \fBTcl_JoinPath\fR(\fIargc, argv, resultPtr\fR)
22 \fBTcl_GetPathType\fR(\fIpath\fR)
24 .AS "const char *const" ***argvPtr in/out
25 .AP "const char" *path in
26 File path in a form appropriate for the current platform (see the
27 \fBfilename\fR manual entry for acceptable forms for path names).
29 Filled in with number of path elements in \fIpath\fR.
30 .AP "const char" ***argvPtr out
31 \fI*argvPtr\fR will be filled in with the address of an array of
32 pointers to the strings that are the extracted elements of \fIpath\fR.
33 There will be \fI*argcPtr\fR valid entries in the array, followed by
36 Number of elements in \fIargv\fR.
37 .AP "const char *const" *argv in
38 Array of path elements to merge together into a single path.
39 .AP Tcl_DString *resultPtr in/out
40 A pointer to an initialized \fBTcl_DString\fR to which the result of
41 \fBTcl_JoinPath\fR will be appended.
46 These procedures have been superseded by the Tcl-value-aware procedures in
47 the \fBFileSystem\fR man page, which are more efficient.
49 These procedures may be used to disassemble and reassemble file
50 paths in a platform independent manner: they provide C-level access to
51 the same functionality as the \fBfile split\fR, \fBfile join\fR, and
52 \fBfile pathtype\fR commands.
54 \fBTcl_SplitPath\fR breaks a path into its constituent elements,
55 returning an array of pointers to the elements using \fIargcPtr\fR and
56 \fIargvPtr\fR. The area of memory pointed to by \fI*argvPtr\fR is
57 dynamically allocated; in addition to the array of pointers, it also
58 holds copies of all the path elements. It is the caller's
59 responsibility to free all of this storage.
60 For example, suppose that you have called \fBTcl_SplitPath\fR with the
68 Tcl_SplitPath(string, &argc, &argv);
71 Then you should eventually free the storage with a call like the
75 Tcl_Free((char *) argv);
78 \fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a
79 collection of path elements given by \fIargc\fR and \fIargv\fR and
80 generates a result string that is a properly constructed path. The
81 result string is appended to \fIresultPtr\fR. \fIResultPtr\fR must
82 refer to an initialized \fBTcl_DString\fR.
84 If the result of \fBTcl_SplitPath\fR is passed to \fBTcl_JoinPath\fR,
85 the result will refer to the same location, but may not be in the same
86 form. This is because \fBTcl_SplitPath\fR and \fBTcl_JoinPath\fR
87 eliminate duplicate path separators and return a normalized form for
90 \fBTcl_GetPathType\fR returns the type of the specified \fIpath\fR,
91 where \fBTcl_PathType\fR is one of \fBTCL_PATH_ABSOLUTE\fR,
92 \fBTCL_PATH_RELATIVE\fR, or \fBTCL_PATH_VOLUME_RELATIVE\fR. See the
93 \fBfilename\fR manual entry for a description of the path types for
97 file, filename, join, path, split, type