EnterFile

     _________________________________________________________________

     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