| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 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.1.1.1 2002-01-16 10:25:24 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH Tcl_TranslateFileName 3 7.5 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 \fR
|
| 18 |
|
|
.sp
|
| 19 |
|
|
char *
|
| 20 |
|
|
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
|
| 21 |
|
|
.SH ARGUMENTS
|
| 22 |
|
|
.AS Tcl_DString *bufferPtr
|
| 23 |
|
|
.AP Tcl_Interp *interp in
|
| 24 |
|
|
Interpreter in which to report an error, if any.
|
| 25 |
|
|
.AP char *name in
|
| 26 |
|
|
File name, which may start with a ``~''.
|
| 27 |
|
|
.AP Tcl_DString *bufferPtr in/out
|
| 28 |
|
|
If needed, this dynamic string is used to store the new file name.
|
| 29 |
|
|
At the time of the call it should be uninitialized or empty. The
|
| 30 |
|
|
caller must eventually call \fBTcl_DStringFree\fR to free up
|
| 31 |
|
|
anything stored here.
|
| 32 |
|
|
.BE
|
| 33 |
|
|
|
| 34 |
|
|
.SH DESCRIPTION
|
| 35 |
|
|
.PP
|
| 36 |
|
|
This utility procedure translates a file name to a form suitable for
|
| 37 |
|
|
passing to the local operating system. It converts network names into
|
| 38 |
|
|
native form and does tilde substitution.
|
| 39 |
|
|
.PP
|
| 40 |
|
|
If
|
| 41 |
|
|
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate
|
| 42 |
|
|
the name then it uses
|
| 43 |
|
|
the dynamic string at \fI*bufferPtr\fR to hold the new string it
|
| 44 |
|
|
generates.
|
| 45 |
|
|
After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
|
| 46 |
|
|
eventually invoke \fBTcl_DStringFree\fR to free any information
|
| 47 |
|
|
placed in \fI*bufferPtr\fR. The caller need not know whether or
|
| 48 |
|
|
not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR
|
| 49 |
|
|
initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
|
| 50 |
|
|
\fBTcl_DStringFree\fR will be safe in either case.
|
| 51 |
|
|
.PP
|
| 52 |
|
|
If an error occurs (e.g. because there was no user by the given
|
| 53 |
|
|
name) then NULL is returned and an error message will be left
|
| 54 |
|
|
at \fIinterp->result\fR.
|
| 55 |
|
|
When an error occurs, \fBTcl_TranslateFileName\fR
|
| 56 |
|
|
frees the dynamic string itself so that the caller need not call
|
| 57 |
|
|
\fBTcl_DStringFree\fR.
|
| 58 |
|
|
.PP
|
| 59 |
|
|
The caller is responsible for making sure that \fIinterp->result\fR
|
| 60 |
|
|
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
|
| 61 |
|
|
|
| 62 |
|
|
.SH "SEE ALSO"
|
| 63 |
|
|
filename
|
| 64 |
|
|
|
| 65 |
|
|
.SH KEYWORDS
|
| 66 |
|
|
file name, home directory, tilde, translate, user
|
