enterfile(3Tcl)

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