86 lines
3.4 KiB
Groff
86 lines
3.4 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/TildeSubst.3,v 1.10 93/04/08 14:00:43 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_TildeSubst tclc 7.0
|
|
.BS
|
|
.SH NAME
|
|
Tcl_TildeSubst \- replace tilde with home directory in a file name
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
char *
|
|
.VS
|
|
\fBTcl_TildeSubst\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr)
|
|
.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
|
|
.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
|
|
This utility procedure does tilde substition. If \fIname\fR doesn't
|
|
start with a ``~'' character, then the procedure returns \fIname\fR.
|
|
If \fIname\fR does start with a tilde, then \fBTcl_TildeSubst\fR
|
|
returns a new string identical to \fIname\fR except that the first
|
|
element of \fIname\fR is replaced with the location of the home
|
|
directory for the given user. The substitution is carried out in
|
|
the same way that it would be done by \fIcsh\fR. If the tilde is
|
|
followed immediately by a slash, then the \fB$HOME\fR environment
|
|
variable is substituted. Otherwise the characters between the
|
|
tilde and the next slash are taken as a user name, which is
|
|
looked up in the password file; the user's home directory is
|
|
retrieved from the password file and substituted.
|
|
.PP
|
|
If
|
|
.VS
|
|
\fBTcl_TildeSubst\fR has to do tilde substitution then it uses
|
|
the dynamic string at \fI*bufferPtr\fR to hold the new string it
|
|
generates. After \fBTcl_TildeSubst\fR returns, the caller must
|
|
eventually invoke \fBTcl_DStringFree\fR to free up any information
|
|
placed in \fI*bufferPtr\fR. The caller need not know whether or
|
|
not \fBTcl_TildeSubst\fR actually used the string; \fBTcl_TildeSubst\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. It is assumed that \fIinterp->result\fR
|
|
has been initialized in the standard way when \fBTcl_TildeSubst\fR
|
|
is invoked.
|
|
|
|
.SH KEYWORDS
|
|
file name, home directory, tilde, user
|