Initial revision

FossilOrigin-Name: cacdd0f329872d67973970d74c6978730bc24baa

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/Translate.3 b/doc/Translate.3
new file mode 100644
index 0000000..6330ee9
--- /dev/null
+++ b/doc/Translate.3
@@ -0,0 +1,66 @@
+'\"
+'\" 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.22 96/08/26 12:59:51
+'\" 
+.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