Tcl_TildeSubst(3Tcl)Tcl_TildeSubst(3Tcl)NAME
Tcl_TildeSubst - replace tilde with home directory in a file name
SYNOPSIS
#include <tcl.h>
char *
Tcl_TildeSubst(interp, name, bufferPtr) |
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to report an
error, if any.
char *name (in) File name, which may start with a
``~''.
Tcl_DString *bufferPtr If needed, this dynamic string is |
used to store the new file name. At|
the time of the call it should be |
uninitialized or empty. The caller |
must eventually call Tcl_DStringFree|
to free up anything stored here.
DESCRIPTION
This utility procedure does tilde substitution. If name doesn't start
with a ``~'' character, then the procedure returns name. If name does
start with a tilde, then Tcl_TildeSubst returns a new string identical to
name except that the first element of name is replaced with the location
of the home directory for the given user. The substitution is carried
out in the same way that it would be done by csh. If the tilde is
followed immediately by a slash, then the $HOME environment variable is
substituted. Otherwise the characters between the tilde and the next
slash are taken as a user name, which is looked up in the password file;
the user's home directory is retrieved from the password file and
substituted.
If Tcl_TildeSubst has to do tilde substitution then it uses the dynamic |
string at *bufferPtr to hold the new string it generates. After |
Tcl_TildeSubst returns a non-NULL result, the caller must eventually |
invoke Tcl_DStringFree to free up any information placed in *bufferPtr. |
The caller need not know whether or not Tcl_TildeSubst actually used the |
string; Tcl_TildeSubst initializes *bufferPtr even if it doesn't 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 at interp-
>result. When an error occurs, Tcl_TildeSubst frees the dynamic string |
itself so that the caller need not call Tcl_DStringFree.
Page 1
Tcl_TildeSubst(3Tcl)Tcl_TildeSubst(3Tcl)
The caller is responsible for making sure that interp->result has its
default empty value when Tcl_TildeSubst is invoked.
KEYWORDS
file name, home directory, tilde, user
Page 2
