TildeSubst

     _________________________________________________________________

     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  substition.   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,  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.   It  is  assumed  that  interp-
          >result  has  been  initialized  in  the  standard  way when
          Tcl_TildeSubst is invoked.


     KEYWORDS
          file name, home directory, tilde, user