util/src/TclTk/tcl8.6.12/doc/Translate.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 char *
  18 \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
  19 .SH ARGUMENTS
  20 .AS Tcl_DString *bufferPtr in/out
  21 .AP Tcl_Interp *interp in
  22 Interpreter in which to report an error, if any.
  23 .AP "const char" *name in
  24 File name, which may start with a
  25 .QW ~ .
  26 .AP Tcl_DString *bufferPtr in/out
  27 If needed, this dynamic string is used to store the new file name.
  28 At the time of the call it should be uninitialized or free.  The
  29 caller must eventually call \fBTcl_DStringFree\fR to free up
  30 anything stored here.
  31 .BE
  32 .SH DESCRIPTION
  33 .PP
  34 This utility procedure translates a file name to a platform-specific form
  35 which, after being converted to the appropriate encoding, is suitable for
  36 passing to the local operating system.  In particular, it converts
  37 network names into native form and does tilde substitution.
  38 .PP
  39 However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
  40 \fBTcl_FSGetNativePath\fR, there is no longer any need to use this
  41 procedure.  In particular, \fBTcl_FSGetNativePath\fR performs all the
  42 necessary translation and encoding conversion, is virtual-filesystem
  43 aware, and caches the native result for faster repeated calls.
  44 Finally \fBTcl_FSGetNativePath\fR does not require you to free anything
  45 afterwards.
  46 .PP
  47 If
  48 \fBTcl_TranslateFileName\fR has to do tilde substitution or translate
  49 the name then it uses
  50 the dynamic string at \fI*bufferPtr\fR to hold the new string it
  51 generates.
  52 After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
  53 eventually invoke \fBTcl_DStringFree\fR to free any information
  54 placed in \fI*bufferPtr\fR.  The caller need not know whether or
  55 not \fBTcl_TranslateFileName\fR actually used the string;  \fBTcl_TranslateFileName\fR
  56 initializes \fI*bufferPtr\fR even if it does not use it, so the call to
  57 \fBTcl_DStringFree\fR will be safe in either case.
  58 .PP
  59 If an error occurs (e.g. because there was no user by the given
  60 name) then NULL is returned and an error message will be left
  61 in the interpreter's result.
  62 When an error occurs, \fBTcl_TranslateFileName\fR
  63 frees the dynamic string itself so that the caller need not call
  64 \fBTcl_DStringFree\fR.
  65 .PP
  66 The caller is responsible for making sure that the interpreter's result
  67 has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
  68 .SH "SEE ALSO"
  69 filename(n)
  70 .SH KEYWORDS
  71 file name, home directory, tilde, translate, user