home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / EnterFile.3 < prev    next >
Text File  |  1993-08-27  |  4KB  |  99 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/EnterFile.3,v 1.4 93/08/27 13:20:42 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_EnterFile tclc 7.0
  25. .BS
  26. .SH NAME
  27. Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions \- manipulate the table of open files
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. \fBTcl_EnterFile\fR(\fIinterp, file, permissions\fR)
  33. .sp
  34. int
  35. \fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
  36. .sp
  37. int
  38. \fBTcl_FilePermissions(\fIfile\fR)
  39. .SH ARGUMENTS
  40. .AS Tcl_Interp checkUsage
  41. .AP Tcl_Interp *interp in
  42. Tcl interpreter from which file is to be accessed.
  43. .AP FILE *file in
  44. Handle for file that is to become accessible in \fIinterp\fR.
  45. .AP int permissions in
  46. OR-ed combination of TCL_FILE_READABLE and TCL_FILE_WRITABLE; 
  47. indicates whether \fIfile\fR was opened for reading or writing or both.
  48. .AP char *string in
  49. String identifying file, such as \fBstdin\fR or \fBfile4\fR.
  50. .AP int write in
  51. Non-zero means the file will be used for writing, zero means it will
  52. be used for reading.
  53. .AP int checkUsage in
  54. If non-zero, then an error will be generated if the file wasn't opened
  55. for the access indicated by \fIwrite\fR.
  56. .AP FILE **filePtr out
  57. Points to word in which to store pointer to FILE structure for
  58. the file given by \fIstring\fR.
  59. .BE
  60.  
  61. .SH DESCRIPTION
  62. .PP
  63. These procedures provide access to Tcl's file naming mechanism.
  64. \fBTcl_EnterFile\fR enters an open file into Tcl's file table so
  65. that it can be accessed using Tcl commands like \fBgets\fR,
  66. \fBputs\fR, \fBseek\fR, and \fBclose\fR.
  67. It returns in \fIinterp->result\fR an identifier such as \fBfile4\fR
  68. that can be used to refer to the file in subsequent Tcl commands.
  69. \fBTcl_EnterFile\fR is typically used to implement new Tcl commands
  70. that open sockets, pipes, or other kinds of files not already supported
  71. by the built-in commands.
  72. .PP
  73. \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
  74. returned by the \fBopen\fR command or \fBTcl_EnterFile\fR and
  75. returns at \fI*filePtr\fR a pointer to the FILE structure for
  76. the file.
  77. The \fIwrite\fR argument indicates whether the FILE pointer will
  78. be used for reading or writing.
  79. In some cases, such as a file that connects to a pipeline of
  80. subprocesses, different FILE pointers will be returned for reading
  81. and writing.
  82. \fBTcl_GetOpenFile\fR normally returns TCL_OK.
  83. If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
  84. make any sense or \fIcheckUsage\fR was set and the file wasn't opened
  85. for the access specified by \fIwrite\fR) then TCL_ERROR is returned
  86. and \fIinterp->result\fR will contain an error message.
  87. If \fIcheckUsage\fR is zero and the file wasn't opened for the
  88. access specified by \fIwrite\fR, then the FILE pointer returned
  89. at \fI*filePtr\fR may not correspond to \fIwrite\fR.
  90. .PP
  91. \fBTcl_FilePermissions\fR returns an OR-ed combination of the
  92. mask bits TCL_FILE_READABLE and TCL_FILE_WRITABLE; these indicate
  93. whether the given file was opened for reading or writing or both.
  94. If \fIfile\fR does not refer to a file in Tcl's file table then
  95. \-1 is returned.
  96.  
  97. .SH KEYWORDS
  98. file table, permissions, pipeline, read, write
  99.