[25] | 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 |
---|