tcl7.6 C API - Translate






NAME

     Tcl_TranslateFileName - convert file name to native form and
     replace tilde with home directory


SYNOPSIS

     #include <tcl.h>

     char *
     Tcl_TranslateFileName(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   (in/out)  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 translates a  file  name  to  a  form
     suitable for passing to the local operating system.  It con-
     verts network names into native form and does tilde  substi-
     tution.

     If Tcl_TranslateFileName has to  do  tilde  substitution  or
     translate  the name then it uses the dynamic string at *buf-
     ferPtr  to  hold  the  new  string  it   generates.    After
     Tcl_TranslateFileName  returns a non-NULL result, the caller
     must eventually invoke Tcl_DStringFree to free any  informa-
     tion placed in *bufferPtr.  The caller need not know whether
     or  not  Tcl_TranslateFileName  actually  used  the  string;
     Tcl_TranslateFileName  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_TranslateFileName  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_TranslateFileName is invoked.



SEE ALSO

     filename



KEYWORDS

     file name, home directory, tilde, translate, user