Tcl_EnterFile(3Tcl)					   Tcl_EnterFile(3Tcl)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <tcl.h>

     Tcl_EnterFile(interp, file, permissions)

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

     int
     Tcl_FilePermissions(file)

ARGUMENTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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.



									Page 1






Tcl_EnterFile(3Tcl)					   Tcl_EnterFile(3Tcl)



     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    [Toc]    [Back]

     file table, permissions, pipeline,	read, write


									PPPPaaaaggggeeee 2222