_________________________________________________________________

     NAME
          Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions -
          manipulate the table of open files

     SYNOPSIS
          #include <tcl.h>

          Tcl_EnterFile(interp, file, permissions)

          int
          Tcl_GetOpenFile(interp, string, write, checkUsage, filePtr)

          int
          Tcl_FilePermissions(file)

     ARGUMENTS
          Tcl_Interp   *interp      (in)      Tcl interpreter from
                                              which file is to be
                                              accessed.

          FILE         *file        (in)      Handle for file that is
                                              to become accessible in
                                              interp.

          int          permissions  (in)      OR-ed combination of
                                              TCL_FILE_READABLE and
                                              TCL_FILE_WRITABLE;
                                              indicates whether file
                                              was opened for reading
                                              or writing or both.

          char         *string      (in)      String identifying file,
                                              such as stdin or file4.

          int          write        (in)      Non-zero means the file
                                              will be used for
                                              writing, zero means it
                                              will be used for
                                              reading.

          int          checkUsage   (in)      If non-zero, then an
                                              error will be generated
                                              if the file wasn't
                                              opened for the access
                                              indicated by write.

          FILE         **filePtr    (out)     Points to word in which
                                              to store pointer to FILE
                                              structure for the file
                                              given by string.

     _________________________________________________________________


     DESCRIPTION
          These procedures provide access to Tcl's file naming
          mechanism.  Tcl_EnterFile enters an open file into Tcl's
          file table so that it can be accessed using Tcl commands
          like gets, puts, seek, and close.  It returns in interp-
          >result an identifier such as file4 that can be used to
          refer to the file in subsequent Tcl commands.  Tcl_EnterFile
          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.

          Tcl_GetOpenFile takes as argument a file identifier of the
          form returned by the open command or Tcl_EnterFile and
          returns at *filePtr a pointer to the FILE structure for the
          file.  The write 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.  Tcl_GetOpenFile normally returns TCL_OK.  If an
          error occurs in Tcl_GetOpenFile (e.g. string didn't make any
          sense or checkUsage was set and the file wasn't opened for
          the access specified by write) then TCL_ERROR is returned
          and interp->result will contain an error message.  If
          checkUsage is zero and the file wasn't opened for the access
          specified by write, then the FILE pointer returned at
          *filePtr may not correspond to write.

          Tcl_FilePermissions 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 file does not refer to a file in Tcl's file table
          then -1 is returned.


     KEYWORDS
          file table, permissions, pipeline, read, write