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