home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / FileHndlr.3 < prev    next >
Encoding:
Text File  |  1993-04-01  |  4.3 KB  |  111 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/FileHndlr.3,v 1.7 93/04/01 09:41:21 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_CreateFileHandler tkc
  25. .BS
  26. .SH NAME
  27. Tk_CreateFileHandler, Tk_DeleteFileHandler \- associate procedure callback with a file or device
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tk.h>\fR
  31. .sp
  32. \fBTk_CreateFileHandler\fR(\fIid, mask, proc, clientData\fR)
  33. .sp
  34. \fBTk_DeleteFileHandler\fR(\fIid\fR)
  35. .SH ARGUMENTS
  36. .AS Tk_FileProc clientData
  37. .AP int id in
  38. Integer identifier for an open file or device (such as returned by
  39. \fBopen\fR system call).
  40. .AP int mask in
  41. Conditions under which \fIproc\fR should be called:
  42. OR-ed combination of \fBTK_READABLE\fR, \fBTK_WRITABLE\fR,
  43. and \fBTK_EXCEPTION\fR.
  44. .AP Tk_FileProc *proc in
  45. Procedure to invoke whenever the file or device indicated
  46. by \fIid\fR meets the conditions specified by \fImask\fR.
  47. .AP ClientData clientData in
  48. Arbitrary one-word value to pass to \fIproc\fR.
  49. .BE
  50.  
  51. .SH DESCRIPTION
  52. .PP
  53. \fBTk_CreateFileHandler\fR arranges for \fIproc\fR to be
  54. invoked in the future whenever I/O becomes possible on a file
  55. or an exceptional condition exists for the file.  The file
  56. is indicated by \fIid\fR, and the conditions of interest
  57. are indicated by \fImask\fR.  For example, if \fImask\fR
  58. is \fBTK_READABLE\fR, then \fIproc\fR will be called when
  59. the file is readable.
  60. The callback to \fIproc\fR is made by \fBTk_DoOneEvent\fR, so
  61. \fBTk_CreateFileHandler\fR is only useful
  62. in programs that dispatch events
  63. through \fBTk_DoOneEvent\fR or through other Tk procedures that
  64. call \fBTk_DoOneEvent\fR, such as \fBTk_MainLoop\fR.
  65. .PP
  66. \fIProc\fP should have arguments and result that match the
  67. type \fBTk_FileProc\fR:
  68. .nf
  69. .RS
  70. typedef void Tk_FileProc(
  71. .RS
  72. ClientData \fIclientData\fR,
  73. int \fImask\fR);
  74. .RE
  75. .RE
  76. .fi
  77. The \fIclientData\fP parameter to \fIproc\fR is a copy
  78. of the \fIclientData\fP
  79. argument given to \fBTcl_CreateFileHandler\fR when the callback
  80. was created.  Typically, \fIclientData\fR points to a data
  81. structure containing application-specific information about
  82. the file.  \fIMask\fR is an integer mask indicating which
  83. of the requested conditions actually exists for the file;  it
  84. will contain a subset of the bits in the \fImask\fR argument
  85. to \fBTcl_CreateFileHandler\fR.
  86. .PP
  87. There may exist only one handler for a given file at a given
  88. time.  If \fBTk_CreateEventHandler\fR is called when a handler
  89. already exists for \fIid\fR, then the \fImask\fR, \fIproc\fR,
  90. and \fIclientData\fR for the new call to
  91. \fBTk_CreateEventHandler\fR replace the information that was
  92. previously recorded.
  93. .PP
  94. \fBTk_DeleteFileHandler\fR may be called to delete the
  95. file handler for \fIid\fR;  if no handler exists for the
  96. file given by \fIid\fR then the procedure has no effect.
  97. .PP
  98. The purpose of file handlers is to enable an application to
  99. respond to X events and other events while waiting for files
  100. to become ready for I/O.  For this to work correctly, the
  101. application must use non-blocking I/O operations on the
  102. files for which handlers are declared.  Otherwise the application
  103. may be put to sleep if it specifies too large an input or
  104. output buffer; while waiting for the I/O to complete the
  105. application won't be able to service other events.  In BSD-based
  106. UNIX systems, non-blocking I/O can be specified for a file using
  107. the \fBfcntl\fR kernel call with the \fBFNDELAY\fR flag.
  108.  
  109. .SH KEYWORDS
  110. callback, file, handler
  111.