man page(1) manual page
Table of Contents

_________________________________________________________________

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


Table of Contents