| 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 |
|---|
