Tcl_TildeSubst(3Tcl)					  Tcl_TildeSubst(3Tcl)

NAME    [Toc]    [Back]

     Tcl_TildeSubst - replace tilde with home directory	in a file name

SYNOPSIS    [Toc]    [Back]

     #include <tcl.h>

     char *
     Tcl_TildeSubst(interp, name, bufferPtr)				      |

ARGUMENTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     file name,	home directory,	tilde, user


									PPPPaaaaggggeeee 2222