_________________________________________________________________

     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.

          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