This utility procedure translates a file name to a platform-specific form
which, after being converted to the appropriate encoding, is suitable for
passing to the local operating system. In particular, it converts
network names into native form and does tilde substitution.
However, with the advent of the newer Tcl_FSGetNormalizedPath and
Tcl_GetNativePath, there is no longer any need to use this
procedure. In particular, Tcl_GetNativePath performs all the
necessary translation and encoding conversion, is virtual-filesystem
aware, and caches the native result for faster repeated calls.
Finally Tcl_GetNativePath does not require you to free anything
Tcl_TranslateFileName has to do tilde substitution or translate
the name then it uses
the dynamic string at *bufferPtr to hold the new string it
After Tcl_TranslateFileName returns a non-NULL result, the caller must
eventually invoke Tcl_DStringFree to free any information
placed in *bufferPtr. The caller need not know whether or
not Tcl_TranslateFileName actually used the string; Tcl_TranslateFileName
initializes *bufferPtr even if it does not use it, so the call to
Tcl_DStringFree will be safe in either case.
If an error occurs (e.g. because there was no user by the given
name) then NULL is returned and an error message will be left
in the interpreters result.
When an error occurs, Tcl_TranslateFileName
frees the dynamic string itself so that the caller need not call
The caller is responsible for making sure that the interpreters result
has its default empty value when Tcl_TranslateFileName is invoked.