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