1 | '\" |
---|
2 | '\" Copyright (c) 1990-1994 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: CrtFileHdlr.3,v 1.8 2007/12/13 15:22:30 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only) |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | \fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR) |
---|
20 | .sp |
---|
21 | \fBTcl_DeleteFileHandler\fR(\fIfd\fR) |
---|
22 | .SH ARGUMENTS |
---|
23 | .AS Tcl_FileProc clientData |
---|
24 | .AP int fd in |
---|
25 | Unix file descriptor for an open file or device. |
---|
26 | .AP int mask in |
---|
27 | Conditions under which \fIproc\fR should be called: |
---|
28 | OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, |
---|
29 | and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable |
---|
30 | a handler. |
---|
31 | .AP Tcl_FileProc *proc in |
---|
32 | Procedure to invoke whenever the file or device indicated |
---|
33 | by \fIfile\fR meets the conditions specified by \fImask\fR. |
---|
34 | .AP ClientData clientData in |
---|
35 | Arbitrary one-word value to pass to \fIproc\fR. |
---|
36 | .BE |
---|
37 | |
---|
38 | .SH DESCRIPTION |
---|
39 | .PP |
---|
40 | \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be |
---|
41 | invoked in the future whenever I/O becomes possible on a file |
---|
42 | or an exceptional condition exists for the file. The file |
---|
43 | is indicated by \fIfd\fR, and the conditions of interest |
---|
44 | are indicated by \fImask\fR. For example, if \fImask\fR |
---|
45 | is \fBTCL_READABLE\fR, \fIproc\fR will be called when |
---|
46 | the file is readable. |
---|
47 | The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so |
---|
48 | \fBTcl_CreateFileHandler\fR is only useful in programs that dispatch |
---|
49 | events through \fBTcl_DoOneEvent\fR or through Tcl commands such |
---|
50 | as \fBvwait\fR. |
---|
51 | .PP |
---|
52 | \fIProc\fR should have arguments and result that match the |
---|
53 | type \fBTcl_FileProc\fR: |
---|
54 | .CS |
---|
55 | typedef void Tcl_FileProc( |
---|
56 | ClientData \fIclientData\fR, |
---|
57 | int \fImask\fR); |
---|
58 | .CE |
---|
59 | The \fIclientData\fR parameter to \fIproc\fR is a copy |
---|
60 | of the \fIclientData\fR |
---|
61 | argument given to \fBTcl_CreateFileHandler\fR when the callback |
---|
62 | was created. Typically, \fIclientData\fR points to a data |
---|
63 | structure containing application-specific information about |
---|
64 | the file. \fIMask\fR is an integer mask indicating which |
---|
65 | of the requested conditions actually exists for the file; it |
---|
66 | will contain a subset of the bits in the \fImask\fR argument |
---|
67 | to \fBTcl_CreateFileHandler\fR. |
---|
68 | .PP |
---|
69 | .PP |
---|
70 | There may exist only one handler for a given file at a given time. |
---|
71 | If \fBTcl_CreateFileHandler\fR is called when a handler already |
---|
72 | exists for \fIfd\fR, then the new callback replaces the information |
---|
73 | that was previously recorded. |
---|
74 | .PP |
---|
75 | \fBTcl_DeleteFileHandler\fR may be called to delete the |
---|
76 | file handler for \fIfd\fR; if no handler exists for the |
---|
77 | file given by \fIfd\fR then the procedure has no effect. |
---|
78 | .PP |
---|
79 | The purpose of file handlers is to enable an application to respond to |
---|
80 | events while waiting for files to become ready for I/O. For this to work |
---|
81 | correctly, the application may need to use non-blocking I/O operations on |
---|
82 | the files for which handlers are declared. Otherwise the application may |
---|
83 | block if it reads or writes too much data; while waiting for the I/O to |
---|
84 | complete the application will not be able to service other events. Use |
---|
85 | \fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into |
---|
86 | blocking or nonblocking mode as required. |
---|
87 | .PP |
---|
88 | Note that these interfaces are only supported by the Unix |
---|
89 | implementation of the Tcl notifier. |
---|
90 | |
---|
91 | .SH KEYWORDS |
---|
92 | callback, file, handler |
---|