[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1996 Sun Microsystems, Inc. |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: SplitPath.3,v 1.9 2004/10/07 15:15:48 dkf Exp $ |
---|
| 8 | '\" |
---|
| 9 | .so man.macros |
---|
| 10 | .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures" |
---|
| 11 | .BS |
---|
| 12 | .SH NAME |
---|
| 13 | Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths |
---|
| 14 | .SH SYNOPSIS |
---|
| 15 | .nf |
---|
| 16 | \fB#include <tcl.h>\fR |
---|
| 17 | .sp |
---|
| 18 | \fBTcl_SplitPath\fR(\fIpath, argcPtr, argvPtr\fR) |
---|
| 19 | .sp |
---|
| 20 | char * |
---|
| 21 | \fBTcl_JoinPath\fR(\fIargc, argv, resultPtr\fR) |
---|
| 22 | .sp |
---|
| 23 | Tcl_PathType |
---|
| 24 | \fBTcl_GetPathType\fR(\fIpath\fR) |
---|
| 25 | .SH ARGUMENTS |
---|
| 26 | .AS "const char *const" ***argvPtr in/out |
---|
| 27 | .AP "const char" *path in |
---|
| 28 | File path in a form appropriate for the current platform (see the |
---|
| 29 | \fBfilename\fR manual entry for acceptable forms for path names). |
---|
| 30 | .AP int *argcPtr out |
---|
| 31 | Filled in with number of path elements in \fIpath\fR. |
---|
| 32 | .AP "const char" ***argvPtr out |
---|
| 33 | \fI*argvPtr\fR will be filled in with the address of an array of |
---|
| 34 | pointers to the strings that are the extracted elements of \fIpath\fR. |
---|
| 35 | There will be \fI*argcPtr\fR valid entries in the array, followed by |
---|
| 36 | a NULL entry. |
---|
| 37 | .AP int argc in |
---|
| 38 | Number of elements in \fIargv\fR. |
---|
| 39 | .AP "const char *const" *argv in |
---|
| 40 | Array of path elements to merge together into a single path. |
---|
| 41 | .AP Tcl_DString *resultPtr in/out |
---|
| 42 | A pointer to an initialized \fBTcl_DString\fR to which the result of |
---|
| 43 | \fBTcl_JoinPath\fR will be appended. |
---|
| 44 | .BE |
---|
| 45 | |
---|
| 46 | .SH DESCRIPTION |
---|
| 47 | .PP |
---|
| 48 | These procedures have been superceded by the objectified procedures in |
---|
| 49 | the \fBFileSystem\fR man page, which are more efficient. |
---|
| 50 | .PP |
---|
| 51 | These procedures may be used to disassemble and reassemble file |
---|
| 52 | paths in a platform independent manner: they provide C-level access to |
---|
| 53 | the same functionality as the \fBfile split\fR, \fBfile join\fR, and |
---|
| 54 | \fBfile pathtype\fR commands. |
---|
| 55 | .PP |
---|
| 56 | \fBTcl_SplitPath\fR breaks a path into its constituent elements, |
---|
| 57 | returning an array of pointers to the elements using \fIargcPtr\fR and |
---|
| 58 | \fIargvPtr\fR. The area of memory pointed to by \fI*argvPtr\fR is |
---|
| 59 | dynamically allocated; in addition to the array of pointers, it also |
---|
| 60 | holds copies of all the path elements. It is the caller's |
---|
| 61 | responsibility to free all of this storage. |
---|
| 62 | For example, suppose that you have called \fBTcl_SplitPath\fR with the |
---|
| 63 | following code: |
---|
| 64 | .CS |
---|
| 65 | int argc; |
---|
| 66 | char *path; |
---|
| 67 | char **argv; |
---|
| 68 | \&... |
---|
| 69 | Tcl_SplitPath(string, &argc, &argv); |
---|
| 70 | .CE |
---|
| 71 | Then you should eventually free the storage with a call like the |
---|
| 72 | following: |
---|
| 73 | .CS |
---|
| 74 | Tcl_Free((char *) argv); |
---|
| 75 | .CE |
---|
| 76 | .PP |
---|
| 77 | \fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a |
---|
| 78 | collection of path elements given by \fIargc\fR and \fIargv\fR and |
---|
| 79 | generates a result string that is a properly constructed path. The |
---|
| 80 | result string is appended to \fIresultPtr\fR. \fIResultPtr\fR must |
---|
| 81 | refer to an initialized \fBTcl_DString\fR. |
---|
| 82 | .PP |
---|
| 83 | If the result of \fBTcl_SplitPath\fR is passed to \fBTcl_JoinPath\fR, |
---|
| 84 | the result will refer to the same location, but may not be in the same |
---|
| 85 | form. This is because \fBTcl_SplitPath\fR and \fBTcl_JoinPath\fR |
---|
| 86 | eliminate duplicate path separators and return a normalized form for |
---|
| 87 | each platform. |
---|
| 88 | .PP |
---|
| 89 | \fBTcl_GetPathType\fR returns the type of the specified \fIpath\fR, |
---|
| 90 | where \fBTcl_PathType\fR is one of \fBTCL_PATH_ABSOLUTE\fR, |
---|
| 91 | \fBTCL_PATH_RELATIVE\fR, or \fBTCL_PATH_VOLUME_RELATIVE\fR. See the |
---|
| 92 | \fBfilename\fR manual entry for a description of the path types for |
---|
| 93 | each platform. |
---|
| 94 | |
---|
| 95 | .SH KEYWORDS |
---|
| 96 | file, filename, join, path, split, type |
---|