Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
Tcl_TranslateFileName(3)     Tcl Library Procedures	Tcl_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  er-
					  ror, 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  unini-
					  tialized  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_FS-
     GetNativePath,  there is no longer any need to use this procedure.  In par-
     ticular, Tcl_FSGetNativePath performs all the necessary translation and en-
     coding conversion, is virtual-filesystem aware, and caches the  native  re-
     sult  for	faster repeated calls.	Finally Tcl_FSGetNativePath does not re-
     quire you to free anything afterwards.

     If Tcl_TranslateFileName has to do tilde substitution or translate the name
     then it uses the dynamic string at *bufferPtr 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  information
     placed  in  *bufferPtr.  The caller need not know whether or not Tcl_Trans-
     lateFileName 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 re-
     sult.  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(n)

KEYWORDS
     file name, home directory, tilde, translate, user

Tcl				       8.1		Tcl_TranslateFileName(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_TranslateFileName.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help