Tcl_TranslateFileName(3tcl)

Tcl_TranslateFileName(3Tcl Library ProcedureTcl_TranslateFileName(3)

_________________________________________________________________

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.

     const 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  free.   The  caller
                                          must  eventually   call
                                          Tcl_DStringFree to free
                                          up   anything    stored
                                          here.
_________________________________________________________________

DESCRIPTION

     This  utility  procedure  translates  a  file  name   to   a
     platform-specific  form  which, after being converted to the
     appropriate encoding, is suitable for passing to  the  local
     operating  system.  In particular, it converts network names
     into native form and does tilde substitution.

     However,    with     the     advent     of     the     newer
     Tcl_FSGetNormalizedPath  and  Tcl_GetNativePath, there is no
     longer any need  to  use  this  procedure.   In  particular,
     Tcl_GetNativePath performs all the necessary translation and
     encoding conversion, is virtual-filesystem aware, and caches
     the  native  result  for  faster  repeated  calls.   Finally
     Tcl_GetNativePath does not  require  you  to  free  anything
     afterwards.

     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                     Last change: 8.1                        1

Tcl_TranslateFileName(3Tcl Library ProcedureTcl_TranslateFileName(3)

     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 does
     not 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 in the interpreter's 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   the
     interpreter's  result  has  its  default  empty  value  when
     Tcl_TranslateFileName is invoked.

SEE ALSO

     filename

KEYWORDS

     file name, home directory, tilde, translate, user

Tcl                     Last change: 8.1                        2