home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / TildeSubst.3 < prev    next >
Text File  |  1993-04-08  |  4KB  |  86 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/TildeSubst.3,v 1.10 93/04/08 14:00:43 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_TildeSubst tclc 7.0
  25. .BS
  26. .SH NAME
  27. Tcl_TildeSubst \- replace tilde with home directory in a file name
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. char *
  33. .VS
  34. \fBTcl_TildeSubst\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr)
  35. .VE
  36. .SH ARGUMENTS
  37. .AS Tcl_DString *bufferPtr
  38. .AP Tcl_Interp *interp in
  39. Interpreter in which to report an error, if any.
  40. .AP char *name in
  41. File name, which may start with a ``~''.
  42. .AP Tcl_DString *bufferPtr
  43. .VS
  44. If needed, this dynamic string is used to store the new file name.
  45. At the time of the call it should be uninitialized or empty.  The
  46. caller must eventually call \fBTcl_DStringFree\fR to free up
  47. anything stored here.
  48. .VE
  49. .BE
  50.  
  51. .SH DESCRIPTION
  52. .PP
  53. This utility procedure does tilde substition.  If \fIname\fR doesn't
  54. start with a ``~'' character, then the procedure returns \fIname\fR.
  55. If \fIname\fR does start with a tilde, then \fBTcl_TildeSubst\fR
  56. returns a new string identical to \fIname\fR except that the first
  57. element of \fIname\fR is replaced with the location of the home
  58. directory for the given user.  The substitution is carried out in
  59. the same way that it would be done by \fIcsh\fR.  If the tilde is
  60. followed immediately by a slash, then the \fB$HOME\fR environment
  61. variable is substituted.  Otherwise the characters between the
  62. tilde and the next slash are taken as a user name, which is
  63. looked up in the password file;  the user's home directory is
  64. retrieved from the password file and substituted.
  65. .PP
  66. If
  67. .VS
  68. \fBTcl_TildeSubst\fR has to do tilde substitution then it uses
  69. the dynamic string at \fI*bufferPtr\fR to hold the new string it
  70. generates.  After \fBTcl_TildeSubst\fR returns, the caller must
  71. eventually invoke \fBTcl_DStringFree\fR to free up any information
  72. placed in \fI*bufferPtr\fR.  The caller need not know whether or
  73. not \fBTcl_TildeSubst\fR actually used the string;  \fBTcl_TildeSubst\fR
  74. initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
  75. \fBTcl_DStringFree\fR will be safe in either case.
  76. .VE
  77. .PP
  78. If an error occurs (e.g. because there was no user by the given
  79. name) then NULL is returned and an error message will be left
  80. at \fIinterp->result\fR.  It is assumed that \fIinterp->result\fR
  81. has been initialized in the standard way when \fBTcl_TildeSubst\fR
  82. is invoked.
  83.  
  84. .SH KEYWORDS
  85. file name, home directory, tilde, user
  86.