'\"
'\" 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/EnterFile.3,v 1.4 93/08/27 13:20:42 ouster Exp $ SPRITE (Berkeley)
'\" 
.so man.macros
.HS Tcl_EnterFile tclc 7.0
.BS
.SH NAME
Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions \- manipulate the table of open files
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_EnterFile\fR(\fIinterp, file, permissions\fR)
.sp
int
\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
.sp
int
\fBTcl_FilePermissions(\fIfile\fR)
.SH ARGUMENTS
.AS Tcl_Interp checkUsage
.AP Tcl_Interp *interp in
Tcl interpreter from which file is to be accessed.
.AP FILE *file in
Handle for file that is to become accessible in \fIinterp\fR.
.AP int permissions in
OR-ed combination of TCL_FILE_READABLE and TCL_FILE_WRITABLE; 
indicates whether \fIfile\fR was opened for reading or writing or both.
.AP char *string in
String identifying file, such as \fBstdin\fR or \fBfile4\fR.
.AP int write in
Non-zero means the file will be used for writing, zero means it will
be used for reading.
.AP int checkUsage in
If non-zero, then an error will be generated if the file wasn't opened
for the access indicated by \fIwrite\fR.
.AP FILE **filePtr out
Points to word in which to store pointer to FILE structure for
the file given by \fIstring\fR.
.BE

.SH DESCRIPTION
.PP
These procedures provide access to Tcl's file naming mechanism.
\fBTcl_EnterFile\fR enters an open file into Tcl's file table so
that it can be accessed using Tcl commands like \fBgets\fR,
\fBputs\fR, \fBseek\fR, and \fBclose\fR.
It returns in \fIinterp->result\fR an identifier such as \fBfile4\fR
that can be used to refer to the file in subsequent Tcl commands.
\fBTcl_EnterFile\fR is typically used to implement new Tcl commands
that open sockets, pipes, or other kinds of files not already supported
by the built-in commands.
.PP
\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
returned by the \fBopen\fR command or \fBTcl_EnterFile\fR and
returns at \fI*filePtr\fR a pointer to the FILE structure for
the file.
The \fIwrite\fR argument indicates whether the FILE pointer will
be used for reading or writing.
In some cases, such as a file that connects to a pipeline of
subprocesses, different FILE pointers will be returned for reading
and writing.
\fBTcl_GetOpenFile\fR normally returns TCL_OK.
If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
make any sense or \fIcheckUsage\fR was set and the file wasn't opened
for the access specified by \fIwrite\fR) then TCL_ERROR is returned
and \fIinterp->result\fR will contain an error message.
If \fIcheckUsage\fR is zero and the file wasn't opened for the
access specified by \fIwrite\fR, then the FILE pointer returned
at \fI*filePtr\fR may not correspond to \fIwrite\fR.
.PP
\fBTcl_FilePermissions\fR returns an OR-ed combination of the
mask bits TCL_FILE_READABLE and TCL_FILE_WRITABLE; these indicate
whether the given file was opened for reading or writing or both.
If \fIfile\fR does not refer to a file in Tcl's file table then
\-1 is returned.

.SH KEYWORDS
file table, permissions, pipeline, read, write