Tcl_GetFile(3) Tcl Library Procedures Tcl_GetFile(3)_________________________________________________________________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-spe-
cific file
handle to be
associated
with the
generic file
handle.
int type (in) The type of
platform-spe-
cific file
handle asso-
ciated with
the generic
file handle.
See below for
a list of
valid types.
Tcl_File handle (in) Generic file
handle asso-
ciated with
platform-spe-
cific file
information.
int *typePtr (in/out) If *typePtr
is not NULL,
then the
specified
word is set
Tcl 7.5 1
Tcl_GetFile(3) Tcl Library Procedures Tcl_GetFile(3)
to contain
the type
associated
with handle.
Tcl_FileFreeProc *freeProc (in) Procedure to
call when
handle is
deleted.
Tcl_FileFreeProc **freeProcPtr (in/out) Pointer to
location in
which to
store address
of current
free proce-
dure for file
handle.
Ignored if
NULL.
ClientData clientData (in) Arbitrary
one-word
value associ-
ated 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_Create-
FileHandler. 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-spe-
cific 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 7.5 2
Tcl_GetFile(3) Tcl Library Procedures Tcl_GetFile(3)
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
particular 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 deal-
located with a call to Tcl_FreeFile. A call to this func-
tion 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 osHan-
dle.
Tcl_GetFileInfo may be used to retrieve the platform-spe-
cific 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
function is the associated platform-specific osHandle.
Note that this function may be used to extract the plat-
form-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
associate 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 proce-
dure 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_Set-
NotifierData.
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.
Tcl 7.5 3
Tcl_GetFile(3) Tcl Library Procedures Tcl_GetFile(3)KEYWORDS
generic file handle, file type, file descriptor, notifier
Tcl 7.5 4