home | help 
Tcl_SplitPath(3)	     Tcl Library Procedures		Tcl_SplitPath(3)

________________________________________________________________________________

NAME
     Tcl_SplitPath,  Tcl_JoinPath,  Tcl_GetPathType - manipulate platform-depen-
     dent 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).

     Tcl_Size | int *argcPtr (out)		Filled in with	number	of  path
						elements   in	path.	 May  be
						(Tcl_Size *)NULL when not  used.
						If it points to a variable which
						type is not Tcl_Size, a compiler
						warning  will  be generated.  If
						your extensions is compiled with
						-DTCL_8_API,  argcPtr  will   be
						filled	with  -1  for paths with
						more   than   INT_MAX	elements
						(which should trigger proper er-
						ror-handling),	otherwise expect
						it to crash.

     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 en-
						tries  in the array, followed by
						a NULL entry.

     Tcl_Size 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  ap-
						pended.
________________________________________________________________________________

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  func-
     tionality as the file split, file join, and file pathtype commands.

     Tcl_SplitPath breaks a path into its constituent elements, returning an ar-
     ray  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, sup-
     pose that you have called Tcl_SplitPath with the following code:

	    Tcl_Size 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(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.  Re-
     sultPtr 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  be-
     cause  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_RELA-
     TIVE.  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)
home | help