'\" '\" 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. '\" '\" RCS: @(#) $Id: Translate.3,v 1.2 2001/09/14 01:42:16 zlaski Exp $ '\" .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 * \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR) .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 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. .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. .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. .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. 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 has its default empty value when \fBTcl_TranslateFileName\fR is invoked. .SH "SEE ALSO" filename .SH KEYWORDS file name, home directory, tilde, translate, user