tcl7.6 C API - GetFile
NAME
Tcl_GetFile, Tcl_FreeFile, Tcl_GetFileInfo - procedures to
manipulate generic file handles
SYNOPSIS
#include <tcl.h>
Tcl_File
Tcl_GetFile(osHandle, type)
Tcl_FreeFile(handle)
ClientData
Tcl_GetFileInfo(handle, typePtr)
ClientData
Tcl_GetNotifierData(handle, freeProcPtr)
Tcl_SetNotifierData(handle, freeProc, clientData)
ARGUMENTS
ClientData osHandle (in) Platform-
specific file
handle to be
associated with
the generic
file handle.
int type (in) The type of
platform-
specific file
handle associ-
ated with the
generic file
handle. See
below for a
list of valid
types.
Tcl_File handle (in) Generic file
handle associ-
ated with
platform-
specific file
information.
int *typePtr (in/out) If *typePtr is
not NULL, then
the specified
word is set to
contain the
type associated
with handle.
Tcl_FileFreeProc *freeProc (in) Procedure to
call when han-
dle is deleted.
Tcl_FileFreeProc **freeProcPtr (in/out) Pointer to
location in
which to store
address of
current free
procedure for
file handle.
Ignored if
NULL.
ClientData clientData (in) Arbitrary one-
word value
associated with
the given file
handle. This
data is owned
by the caller.
DESCRIPTION
A Tcl_File is an opaque handle used to refer to files in a
platform independent way in Tcl routines like
Tcl_CreateFileHandler. A file handle has an associated
platform-dependent osHandle, a type and additional private
data used by the notifier to generate events for the file.
The type is an integer that determines how the platform-
specific drivers will interpret the osHandle. The types
that are defined by the core are:
TCL_UNIX_FD The osHandle is a Unix file descrip-
tor.
TCL_MAC_FILE The file is a Macintosh file handle.
TCL_WIN_FILE The osHandle is a Windows normal file
HANDLE.
TCL_WIN_PIPE The osHandle is a Windows anonymous
pipe HANDLE.
TCL_WIN_SOCKET The osHandle is a Windows SOCKET.
TCL_WIN_CONSOLE The osHandle is a Windows console
buffer HANDLE.
Tcl_GetFile locates the file handle corresponding to a par-
ticular osHandle and a type. If a file handle already
existed for the given file, then that handle will be
returned. If this is the first time that the file handle
for a particular file is being retrieved, then a new file
handle will be allocated and returned.
When a file handle is no longer in use, it should be deallo-
cated with a call to Tcl_FreeFile. A call to this function
will invoke the notifier free procedure proc, if there is
one. After the notifier has cleaned up, any resources used
by the file handle will be deallocated. Tcl_FreeFile will
not close the platform-specific osHandle.
Tcl_GetFileInfo may be used to retrieve the platform-
specific osHandle and type associated with a file handle.
If typePtr is not NULL, then the word at *typePtr is set to
the type of the file handle. The return value of the func-
tion is the associated platform-specific osHandle. Note
that this function may be used to extract the platform-
specific file handle from a Tcl_File so that it may be used
in external interfaces. However, programs written using
this interface will be platform-specific.
The Tcl_SetNotifierData and Tcl_GetNotifierData procedures
are intended to be used only by notifier writers. See the
Tcl_CreateEventSource(3) manual entry for more information
on the notifier.
Tcl_SetNotifierData may be used by notifier writers to asso-
ciate notifier-specific information with a Tcl_File. The
data argument specifies a word that may be retrieved with a
later call to Tcl_GetNotifierData. If the freeProc argument
is non-NULL it specifies the address of a procedure to
invoke when the Tcl_File is deleted. freeProc should have
arguments and result that match the type Tcl_FileFreeProc:
typedef void Tcl_FileFreeProc(
ClientData clientData);
When freeProc is invoked the clientData argument will be the
same as the corresponding argument passed to
Tcl_SetNotifierData.
Tcl_GetNotifierData returns the clientData associated with
the given Tcl_File, and if the freeProcPtr field is non-
NULL, the address indicated by it gets the address of the
free procedure stored with this file.
KEYWORDS
generic file handle, file type, file descriptor, notifier