Tcl_TranslateFileName(3)

💫 Tcl_TranslateFileName — a Tcl Library Procedures moment 💫

okay bestie, welcome to the manual page for Tcl_TranslateFileName(3), straight out of the Tcl Library Procedures collection. this one's a little vintage, a little deprecated, and honestly kind of a vibe. let's get into it 🎀

---

✨ NAME ✨

Tcl_TranslateFileName — converts a file name to its native form. literally just glow-up-ing your filename for the local OS 💅

---

🦋 SYNOPSIS 🦋

#include <tcl.h>

char *
Tcl_TranslateFileName(interp, name, bufferPtr)

---

🌸 ARGUMENTS 🌸

• Tcl_Interp *interp (in) — the interpreter where we spill the tea if anything goes wrong, i.e. where errors get reported, if any.
• const char *name (in) — the file name in question. the main character, if you will 👑
• Tcl_DString *bufferPtr (in/out) — if it's needed, this dynamic string is where the new file name gets stored. when you call this, it should be uninitialized or free — like, don't hand it a whole situation. and the caller must eventually call Tcl_DStringFree to free up anything stored here. no leaving mess behind, we're not that girl 🙈

---

💖 DESCRIPTION 💖

so this utility procedure translates a file name into a platform-specific form. after it's been converted to the appropriate encoding, that form is suitable for passing to the local operating system. specifically: it converts network names into native form. very demure, very mindful, very platform-aware ✨

but — and this is the part where we all collectively gasp — with the advent of the newer Tcl_FSGetNormalizedPath and Tcl_FSGetNativePath, there is no longer any need to use this procedure. like, at all. no cap. 🫶

and here's why the new girls are eating:

• Tcl_FSGetNativePath performs all the necessary translation and encoding conversion
• it's virtual-filesystem aware 👑
• it caches the native result so repeated calls are faster
• and finally, Tcl_FSGetNativePath does not require you to free anything afterwards. nothing. zero cleanup. iconic.

if Tcl_TranslateFileName does have to translate the name, then it uses the dynamic string at *bufferPtr to hold the new string it generates. after Tcl_TranslateFileName returns a non-NULL result, the caller must eventually invoke Tcl_DStringFree to free any information placed in *bufferPtr. and listen — the caller does not need to know whether or not Tcl_TranslateFileName actually used the string, because Tcl_TranslateFileName initializes *bufferPtr even if it doesn't use it, so the call to Tcl_DStringFree will be safe in either case. bestie really said "don't worry about it, I handled it" 💅

if an error occurs (like, say, because there was no user by the given name) then NULL is returned and an error message will be left in the interpreter's result. and when an error occurs, Tcl_TranslateFileName frees the dynamic string itself, so that the caller need not call Tcl_DStringFree. self-cleaning. we love a low-maintenance icon 🌈

⚠️ okay important one: the caller is responsible for making sure that the interpreter's result has its default empty value when Tcl_TranslateFileName is invoked. yes, that's on you. that's your job. don't make it weird 😭

---

🔥 SEE ALSO 🔥

• filename(n)

---

💜 KEYWORDS 💜

file name, home directory, translate, user

---

and that's the whole page, bestie. this one came to you from Tcl 8.1, dated the same, with Tcl_TranslateFileName(3) stamped on the bottom like a little signature. go forth and use Tcl_FSGetNativePath instead, fr fr 🧚✨