diff options
Diffstat (limited to 'doc/Translate.3')
| -rw-r--r-- | doc/Translate.3 | 41 |
1 files changed, 23 insertions, 18 deletions
diff --git a/doc/Translate.3 b/doc/Translate.3 index 6330ee9..0f223e4 100644 --- a/doc/Translate.3 +++ b/doc/Translate.3 @@ -1,14 +1,12 @@ '\" '\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) Translate.3 1.22 96/08/26 12:59:51 -'\" +.TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures" .so man.macros -.TH Tcl_TranslateFileName 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory @@ -19,23 +17,32 @@ Tcl_TranslateFileName \- convert file name to native form and replace tilde with char * \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR) .SH ARGUMENTS -.AS Tcl_DString *bufferPtr +.AS Tcl_DString *bufferPtr in/out .AP Tcl_Interp *interp in Interpreter in which to report an error, if any. -.AP char *name in -File name, which may start with a ``~''. +.AP "const char" *name in +File name, which may start with a +.QW ~ . .AP 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 empty. The +At the time of the call it should be uninitialized or free. The caller must eventually call \fBTcl_DStringFree\fR to free up anything stored here. .BE - .SH DESCRIPTION .PP -This utility procedure translates a file name to a form suitable for -passing to the local operating system. It converts network names into -native form and does tilde substitution. +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. +.PP +However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and +\fBTcl_FSGetNativePath\fR, there is no longer any need to use this +procedure. In particular, \fBTcl_FSGetNativePath\fR performs all the +necessary translation and encoding conversion, is virtual-filesystem +aware, and caches the native result for faster repeated calls. +Finally \fBTcl_FSGetNativePath\fR does not require you to free anything +afterwards. .PP If \fBTcl_TranslateFileName\fR has to do tilde substitution or translate @@ -46,21 +53,19 @@ After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must eventually invoke \fBTcl_DStringFree\fR to free any information placed in \fI*bufferPtr\fR. The caller need not know whether or not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR -initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to +initializes \fI*bufferPtr\fR even if it does not use it, so the call to \fBTcl_DStringFree\fR will be safe in either case. .PP 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 -at \fIinterp->result\fR. +in the interpreter's result. When an error occurs, \fBTcl_TranslateFileName\fR frees the dynamic string itself so that the caller need not call \fBTcl_DStringFree\fR. .PP -The caller is responsible for making sure that \fIinterp->result\fR +The caller is responsible for making sure that the interpreter's result has its default empty value when \fBTcl_TranslateFileName\fR is invoked. - .SH "SEE ALSO" -filename - +filename(n) .SH KEYWORDS file name, home directory, tilde, translate, user |