77 lines
2.4 KiB
Groff
77 lines
2.4 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 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.21 96/03/25 20:08:58
|
|
'\"
|
|
.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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
char *
|
|
.VS
|
|
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
|
|
.VE
|
|
.SH ARGUMENTS
|
|
.AS Tcl_DString *bufferPtr
|
|
.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 Tcl_DString *bufferPtr in/out
|
|
.VS
|
|
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
|
|
caller must eventually call \fBTcl_DStringFree\fR to free up
|
|
anything stored here.
|
|
.VE
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
.VS
|
|
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.
|
|
.PP
|
|
If
|
|
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate
|
|
the name then it uses
|
|
the dynamic string at \fI*bufferPtr\fR to hold the new string it
|
|
generates.
|
|
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
|
|
\fBTcl_DStringFree\fR will be safe in either case.
|
|
.VE
|
|
.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.
|
|
.VS
|
|
When an error occurs, \fBTcl_TranslateFileName\fR
|
|
frees the dynamic string itself so that the caller need not call
|
|
\fBTcl_DStringFree\fR.
|
|
.VE
|
|
.PP
|
|
The caller is responsible for making sure that \fIinterp->result\fR
|
|
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
|
|
|
|
.VS
|
|
.SH "SEE ALSO"
|
|
filename
|
|
.VE
|
|
|
|
.SH KEYWORDS
|
|
file name, home directory, tilde, translate, user
|