Tcl_SplitPath(3tcl)

💖 Tcl_SplitPath — bestie's guide to path surgery ✨

okay so this is the page for Tcl_SplitPath, Tcl_JoinPath, and Tcl_GetPathType — three lil functions from the Tcl Library Procedures that manipulate platform-dependent file paths 🦋 and honestly? they're giving C-level file-handling realness.

---

🌸 NAME 🌸

Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType — they manipulate platform-dependent file paths. that's the whole job. slay. 💅

---

✨ 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) — a file path, in whatever form the current platform thinks is normal. (see the filename manual entry for acceptable forms for path names — it's got the lore iykyk.)
• Tcl_Size | int *argcPtr (out) — gets filled in with the number of path elements in path. you can pass (Tcl_Size *)NULL when you're not using it. ⚠️ important tea: if it points to a variable whose type is not Tcl_Size, a compiler warning will be generated. and 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 error-handling), otherwise expect it to crash 😭 so like. be normal about it.
• 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. 👑
• Tcl_Size argc (in) — the number of elements in argv.
• const char *const *argv (in) — an 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 💅

so first things first, and bestie i need you to hear me: these procedures have been superseded by the Tcl-value-aware procedures in the FileSystem man page, which are more efficient. 👀 they still work, but the new ones ate.

now, these procedures may be used to disassemble and reassemble file paths in a platform independent manner: they give you C-level access to the exact same functionality as the file split, file join, and file pathtype commands. same vibes, lower level. 💀

✂️ Tcl_SplitPath

breaks a path into its constituent elements, returning an array of pointers to the elements using argcPtr and argvPtr. the memory pointed to by *argvPtr is dynamically allocated — and not just the array of pointers, it also holds copies of all the path elements. so it's all on one blob of memory, cute, but guess what:

🚨 it is the caller's responsibility to free all of this storage. Tcl is NOT doing it for you. periodt.

for example, suppose you called Tcl_SplitPath with this:

Tcl_Size argc;
char *path;
char **argv;
...
Tcl_SplitPath(string, &argc, &argv);

then you should eventually free the storage with a call like this:

Tcl_Free(argv);

that's it. that's the cleanup. don't forget it. 🙈

🔗 Tcl_JoinPath

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, and resultPtr must refer to an initialized Tcl_DString.

🌀 the round trip

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. why? because Tcl_SplitPath and Tcl_JoinPath eliminate duplicate path separators and return a normalized form for each platform. it's a glow-up, not a move. ✨

🧐 Tcl_GetPathType

returns the type of the specified path, where Tcl_PathType is one of:

• TCL_PATH_ABSOLUTE
• TCL_PATH_RELATIVE
• TCL_PATH_VOLUME_RELATIVE

(see the filename manual entry for a description of the path types for each platform — every OS does its own thing, no cap.) 🌈

---

🔑 KEYWORDS 🔑

file, filename, join, path, split, type

---

okay that's the whole page bestie!! 🎀 this was Tcl Library Procedures, version 7.5, Tcl_SplitPath(3tcl), and it's been a whole journey. go free your argv and live your truth. mwah 💖✨🦋