1 files changed, 130 insertions, 0 deletions
diff --git a/contrib/tcl/doc/GetFile.3 b/contrib/tcl/doc/GetFile.3
new file mode 100644
index 0000000..68ffd21
--- /dev/null
+++ b/contrib/tcl/doc/GetFile.3
@@ -0,0 +1,130 @@
+'\"
+'\" 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