OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tcl/] [doc/] [CrtFileHdlr.3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
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.1.1.1 2002-01-16 10:25:23 markom 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 \fR
18
.VS
19
.sp
20
\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
21
.sp
22
\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
23
.VE
24
.SH ARGUMENTS
25
.AS Tcl_FileProc clientData
26
.VS
27
.AP int fd in
28
Unix file descriptor for an open file or device.
29
.VE
30
.AP int mask in
31
Conditions under which \fIproc\fR should be called:
32
OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
33
and \fBTCL_EXCEPTION\fR.  May be set to 0 to temporarily disable
34
a handler.
35
.AP Tcl_FileProc *proc in
36
Procedure to invoke whenever the file or device indicated
37
by \fIfile\fR meets the conditions specified by \fImask\fR.
38
.AP ClientData clientData in
39
Arbitrary one-word value to pass to \fIproc\fR.
40
.BE
41
 
42
.SH DESCRIPTION
43
.PP
44
.VS
45
\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
46
invoked in the future whenever I/O becomes possible on a file
47
or an exceptional condition exists for the file.  The file
48
is indicated by \fIfd\fR, and the conditions of interest
49
.VE
50
are indicated by \fImask\fR.  For example, if \fImask\fR
51
is \fBTCL_READABLE\fR, \fIproc\fR will be called when
52
the file is readable.
53
The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so
54
\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch
55
events through \fBTcl_DoOneEvent\fR or through Tcl commands such
56
as \fBvwait\fR.
57
.PP
58
\fIProc\fR should have arguments and result that match the
59
type \fBTcl_FileProc\fR:
60
.CS
61
typedef void Tcl_FileProc(
62
        ClientData \fIclientData\fR,
63
        int \fImask\fR);
64
.CE
65
The \fIclientData\fR parameter to \fIproc\fR is a copy
66
of the \fIclientData\fR
67
argument given to \fBTcl_CreateFileHandler\fR when the callback
68
was created.  Typically, \fIclientData\fR points to a data
69
structure containing application-specific information about
70
the file.  \fIMask\fR is an integer mask indicating which
71
of the requested conditions actually exists for the file;  it
72
will contain a subset of the bits in the \fImask\fR argument
73
to \fBTcl_CreateFileHandler\fR.
74
.PP
75
.PP
76
There may exist only one handler for a given file at a given time.
77
If \fBTcl_CreateFileHandler\fR is called when a handler already
78
exists for \fIfd\fR, then the new callback replaces the information
79
that was previously recorded.
80
.PP
81
\fBTcl_DeleteFileHandler\fR may be called to delete the
82
file handler for \fIfd\fR;  if no handler exists for the
83
file given by \fIfd\fR then the procedure has no effect.
84
.PP
85
The purpose of file handlers is to enable an application to respond to
86
events while waiting for files to become ready for I/O.  For this to work
87
correctly, the application may need to use non-blocking I/O operations on
88
the files for which handlers are declared.  Otherwise the application may
89
block if it reads or writes too much data; while waiting for the I/O to
90
complete the application won't be able to service other events. Use
91
\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
92
blocking or nonblocking mode as required.
93
.PP
94
.VS
95
Note that these interfaces are only supported by the Unix
96
implementation of the Tcl notifier.
97
.VE
98
 
99
.SH KEYWORDS
100
callback, file, handler

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.