131 lines
4.9 KiB
Groff
131 lines
4.9 KiB
Groff
'\"
|
|
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) GetFile.3 1.8 96/03/25 20:03:31
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_GetFile 3 7.5 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_GetFile, Tcl_FreeFile, Tcl_GetFileInfo \- procedures to manipulate generic file handles
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
Tcl_File
|
|
\fBTcl_GetFile\fR(\fIosHandle, type\fR)
|
|
.sp
|
|
\fBTcl_FreeFile\fR(\fIhandle\fR)
|
|
.sp
|
|
ClientData
|
|
\fBTcl_GetFileInfo\fR(\fIhandle, typePtr\fR)
|
|
.sp
|
|
ClientData
|
|
\fBTcl_GetNotifierData\fR(\fIhandle, freeProcPtr\fR)
|
|
.sp
|
|
\fBTcl_SetNotifierData\fR(\fIhandle, freeProc, clientData\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_FileFreeProc **freeProcPtr
|
|
.AP ClientData osHandle in
|
|
Platform-specific file handle to be associated with the generic file handle.
|
|
.AP int type in
|
|
The type of platform-specific file handle associated with the generic file
|
|
handle. See below for a list of valid types.
|
|
.AP Tcl_File handle in
|
|
Generic file handle associated with platform-specific file information.
|
|
.AP int *typePtr in/out
|
|
If \fI*typePtr\fR is not NULL, then the specified word is set to
|
|
contain the type associated with \fIhandle\fR.
|
|
.AP Tcl_FileFreeProc *freeProc in
|
|
Procedure to call when \fIhandle\fR is deleted.
|
|
.AP Tcl_FileFreeProc **freeProcPtr in/out
|
|
Pointer to location in which to store address of current free procedure
|
|
for file handle. Ignored if NULL.
|
|
.AP ClientData clientData in
|
|
Arbitrary one-word value associated with the given file handle. This
|
|
data is owned by the caller.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
A \fBTcl_File\fR is an opaque handle used to refer to files in a
|
|
platform independent way in Tcl routines like
|
|
\fBTcl_CreateFileHandler\fR. A file handle has an associated
|
|
platform-dependent \fIosHandle\fR, a \fItype\fR 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 \fIosHandle\fR. The types that are defined by the core
|
|
are:
|
|
.TP 22
|
|
\fBTCL_UNIX_FD\fR
|
|
The \fIosHandle\fR is a Unix file descriptor.
|
|
.TP 22
|
|
\fBTCL_MAC_FILE\fR
|
|
The file is a Macintosh file handle.
|
|
.TP 22
|
|
\fBTCL_WIN_FILE\fR
|
|
The \fIosHandle\fR is a Windows normal file \fBHANDLE\fR.
|
|
.TP 22
|
|
\fBTCL_WIN_PIPE\fR
|
|
The \fIosHandle\fR is a Windows anonymous pipe \fBHANDLE\fR.
|
|
.TP 22
|
|
\fBTCL_WIN_SOCKET\fR
|
|
The \fIosHandle\fR is a Windows \fBSOCKET\fR.
|
|
.TP 22
|
|
\fBTCL_WIN_CONSOLE\fR
|
|
The \fIosHandle\fR is a Windows console buffer \fBHANDLE\fR.
|
|
.PP
|
|
\fBTcl_GetFile\fR locates the file handle corresponding to a particular
|
|
\fIosHandle\fR and a \fItype\fR. 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.
|
|
.PP
|
|
When a file handle is no longer in use, it should be deallocated with
|
|
a call to \fBTcl_FreeFile\fR. A call to this function will invoke the
|
|
notifier free procedure \fIproc\fR, if there is one. After the
|
|
notifier has cleaned up, any resources used by the file handle will be
|
|
deallocated. \fBTcl_FreeFile\fR will not close the platform-specific
|
|
\fIosHandle\fR.
|
|
.PP
|
|
\fBTcl_GetFileInfo\fR may be used to retrieve the platform-specific
|
|
\fIosHandle\fR and type associated with a file handle. If
|
|
\fItypePtr\fR is not NULL, then the word at \fI*typePtr\fR is set to
|
|
the type of the file handle. The return value of the function is the
|
|
associated platform-specific \fIosHandle\fR. Note that this function
|
|
may be used to extract the platform-specific file handle from a
|
|
\fBTcl_File\fR so that it may be used in external interfaces.
|
|
However, programs written using this interface will be
|
|
platform-specific.
|
|
.PP
|
|
The \fBTcl_SetNotifierData\fR and \fBTcl_GetNotifierData\fR procedures are
|
|
intended to be used only by notifier writers. See the
|
|
\fITcl_CreateEventSource(3)\fR manual entry for more information on
|
|
the notifier.
|
|
.PP
|
|
\fBTcl_SetNotifierData\fR may be used by notifier writers to associate
|
|
notifier-specific information with a \fBTcl_File\fR. The \fIdata\fR
|
|
argument specifies a word that may be retrieved with a later call to
|
|
\fBTcl_GetNotifierData\fR. If the \fIfreeProc\fR argument is non-NULL
|
|
it specifies the address of a procedure to invoke when the
|
|
\fBTcl_File\fR is deleted. \fIfreeProc\fR should have arguments and
|
|
result that match the type \fBTcl_FileFreeProc\fR:
|
|
.CS
|
|
typedef void Tcl_FileFreeProc(
|
|
ClientData \fIclientData\fR);
|
|
.CE
|
|
When \fIfreeProc\fR is invoked the \fIclientData\fR argument will be
|
|
the same as the corresponding argument passed to
|
|
\fBTcl_SetNotifierData\fR.
|
|
.PP
|
|
\fBTcl_GetNotifierData\fR returns the \fIclientData\fR associated with
|
|
the given \fBTcl_File\fR, and if the \fIfreeProcPtr\fR field is
|
|
non-\fBNULL\fR, the address indicated by it gets the address of the
|
|
free procedure stored with this file.
|
|
|
|
.SH KEYWORDS
|
|
generic file handle, file type, file descriptor, notifier
|