CELLLINUX64/util/CELLLINUX64/man/man3/Tcl_DeleteFileHandler.3

   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.2 1998/09/14 18:39:47 stanton Exp $
   9 '\"
  10 '\" The definitions below are for supplemental macros used in Tcl/Tk
  11 '\" manual entries.
  12 '\"
  13 '\" .AP type name in/out ?indent?
  14 '\"     Start paragraph describing an argument to a library procedure.
  15 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 '\"     needed;  use .AS below instead)
  19 '\"
  20 '\" .AS ?type? ?name?
  21 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 '\"     name are examples of largest possible arguments that will be passed
  23 '\"     to .AP later.  If args are omitted, default tab stops are used.
  24 '\"
  25 '\" .BS
  26 '\"     Start box enclosure.  From here until next .BE, everything will be
  27 '\"     enclosed in one large box.
  28 '\"
  29 '\" .BE
  30 '\"     End of box enclosure.
  31 '\"
  32 '\" .CS
  33 '\"     Begin code excerpt.
  34 '\"
  35 '\" .CE
  36 '\"     End code excerpt.
  37 '\"
  38 '\" .VS ?version? ?br?
  39 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 '\"     of man pages.  The first argument is ignored and used for recording
  41 '\"     the version when the .VS was added, so that the sidebars can be
  42 '\"     found and removed when they reach a certain age.  If another argument
  43 '\"     is present, then a line break is forced before starting the sidebar.
  44 '\"
  45 '\" .VE
  46 '\"     End of vertical sidebar.
  47 '\"
  48 '\" .DS
  49 '\"     Begin an indented unfilled display.
  50 '\"
  51 '\" .DE
  52 '\"     End of indented unfilled display.
  53 '\"
  54 '\" .SO
  55 '\"     Start of list of standard options for a Tk widget.  The
  56 '\"     options follow on successive lines, in four columns separated
  57 '\"     by tabs.
  58 '\"
  59 '\" .SE
  60 '\"     End of list of standard options for a Tk widget.
  61 '\"
  62 '\" .OP cmdName dbName dbClass
  63 '\"     Start of description of a specific option.  cmdName gives the
  64 '\"     option's name as specified in the class command, dbName gives
  65 '\"     the option's name in the option database, and dbClass gives
  66 '\"     the option's class in the option database.
  67 '\"
  68 '\" .UL arg1 arg2
  69 '\"     Print arg1 underlined, then print arg2 normally.
  70 '\"
  71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  72 '\"
  73 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  74 .if t .wh -1.3i ^B
  75 .nr ^l \n(.l
  76 .ad b
  77 '\"     # Start an argument description
  78 .de AP
  79 .ie !"\\$4"" .TP \\$4
  80 .el \{\
  81 .   ie !"\\$2"" .TP \\n()Cu
  82 .   el          .TP 15
  83 .\}
  84 .ta \\n()Au \\n()Bu
  85 .ie !"\\$3"" \{\
  86 \&\\$1  \\fI\\$2\\fP    (\\$3)
  87 .\".b
  88 .\}
  89 .el \{\
  90 .br
  91 .ie !"\\$2"" \{\
  92 \&\\$1  \\fI\\$2\\fP
  93 .\}
  94 .el \{\
  95 \&\\fI\\$1\\fP
  96 .\}
  97 .\}
  98 ..
  99 '\"     # define tabbing values for .AP
 100 .de AS
 101 .nr )A 10n
 102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 103 .nr )B \\n()Au+15n
 104 .\"
 105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 107 ..
 108 .AS Tcl_Interp Tcl_CreateInterp in/out
 109 '\"     # BS - start boxed text
 110 '\"     # ^y = starting y location
 111 '\"     # ^b = 1
 112 .de BS
 113 .br
 114 .mk ^y
 115 .nr ^b 1u
 116 .if n .nf
 117 .if n .ti 0
 118 .if n \l'\\n(.lu\(ul'
 119 .if n .fi
 120 ..
 121 '\"     # BE - end boxed text (draw box now)
 122 .de BE
 123 .nf
 124 .ti 0
 125 .mk ^t
 126 .ie n \l'\\n(^lu\(ul'
 127 .el \{\
 128 .\"     Draw four-sided box normally, but don't draw top of
 129 .\"     box if the box started on an earlier page.
 130 .ie !\\n(^b-1 \{\
 131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 132 .\}
 133 .el \}\
 134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 135 .\}
 136 .\}
 137 .fi
 138 .br
 139 .nr ^b 0
 140 ..
 141 '\"     # VS - start vertical sidebar
 142 '\"     # ^Y = starting y location
 143 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 144 .de VS
 145 .if !"\\$2"" .br
 146 .mk ^Y
 147 .ie n 'mc \s12\(br\s0
 148 .el .nr ^v 1u
 149 ..
 150 '\"     # VE - end of vertical sidebar
 151 .de VE
 152 .ie n 'mc
 153 .el \{\
 154 .ev 2
 155 .nf
 156 .ti 0
 157 .mk ^t
 158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 159 .sp -1
 160 .fi
 161 .ev
 162 .\}
 163 .nr ^v 0
 164 ..
 165 '\"     # Special macro to handle page bottom:  finish off current
 166 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 167 '\"     # page bottom macro.
 168 .de ^B
 169 .ev 2
 170 'ti 0
 171 'nf
 172 .mk ^t
 173 .if \\n(^b \{\
 174 .\"     Draw three-sided box if this is the box's first page,
 175 .\"     draw two sides but no top otherwise.
 176 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 178 .\}
 179 .if \\n(^v \{\
 180 .nr ^x \\n(^tu+1v-\\n(^Yu
 181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 182 .\}
 183 .bp
 184 'fi
 185 .ev
 186 .if \\n(^b \{\
 187 .mk ^y
 188 .nr ^b 2
 189 .\}
 190 .if \\n(^v \{\
 191 .mk ^Y
 192 .\}
 193 ..
 194 '\"     # DS - begin display
 195 .de DS
 196 .RS
 197 .nf
 198 .sp
 199 ..
 200 '\"     # DE - end display
 201 .de DE
 202 .fi
 203 .RE
 204 .sp
 205 ..
 206 '\"     # SO - start of list of standard options
 207 .de SO
 208 .SH "STANDARD OPTIONS"
 209 .LP
 210 .nf
 211 .ta 5.5c 11c
 212 .ft B
 213 ..
 214 '\"     # SE - end of list of standard options
 215 .de SE
 216 .fi
 217 .ft R
 218 .LP
 219 See the \\fBoptions\\fR manual entry for details on the standard options.
 220 ..
 221 '\"     # OP - start of full description for a single option
 222 .de OP
 223 .LP
 224 .nf
 225 .ta 4c
 226 Command-Line Name:      \\fB\\$1\\fR
 227 Database Name:  \\fB\\$2\\fR
 228 Database Class: \\fB\\$3\\fR
 229 .fi
 230 .IP
 231 ..
 232 '\"     # CS - begin code excerpt
 233 .de CS
 234 .RS
 235 .nf
 236 .ta .25i .5i .75i 1i
 237 ..
 238 '\"     # CE - end code excerpt
 239 .de CE
 240 .fi
 241 .RE
 242 ..
 243 .de UL
 244 \\$1\l'|0\(ul'\\$2
 245 ..
 246 .TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
 247 .BS
 248 .SH NAME
 249 Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
 250 .SH SYNOPSIS
 251 .nf
 252 \fB#include <tcl.h>\fR
 253 .VS
 254 .sp
 255 \fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
 256 .sp
 257 \fBTcl_DeleteFileHandler\fR(\fIfd\fR)
 258 .VE
 259 .SH ARGUMENTS
 260 .AS Tcl_FileProc clientData
 261 .VS
 262 .AP int fd in
 263 Unix file descriptor for an open file or device.
 264 .VE
 265 .AP int mask in
 266 Conditions under which \fIproc\fR should be called:
 267 OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
 268 and \fBTCL_EXCEPTION\fR.  May be set to 0 to temporarily disable
 269 a handler.
 270 .AP Tcl_FileProc *proc in
 271 Procedure to invoke whenever the file or device indicated
 272 by \fIfile\fR meets the conditions specified by \fImask\fR.
 273 .AP ClientData clientData in
 274 Arbitrary one-word value to pass to \fIproc\fR.
 275 .BE
 276
 277 .SH DESCRIPTION
 278 .PP
 279 .VS
 280 \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
 281 invoked in the future whenever I/O becomes possible on a file
 282 or an exceptional condition exists for the file.  The file
 283 is indicated by \fIfd\fR, and the conditions of interest
 284 .VE
 285 are indicated by \fImask\fR.  For example, if \fImask\fR
 286 is \fBTCL_READABLE\fR, \fIproc\fR will be called when
 287 the file is readable.
 288 The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so
 289 \fBTcl_CreateFileHandler\fR is only useful in programs that dispatch
 290 events through \fBTcl_DoOneEvent\fR or through Tcl commands such
 291 as \fBvwait\fR.
 292 .PP
 293 \fIProc\fR should have arguments and result that match the
 294 type \fBTcl_FileProc\fR:
 295 .CS
 296 typedef void Tcl_FileProc(
 297         ClientData \fIclientData\fR,
 298         int \fImask\fR);
 299 .CE
 300 The \fIclientData\fR parameter to \fIproc\fR is a copy
 301 of the \fIclientData\fR
 302 argument given to \fBTcl_CreateFileHandler\fR when the callback
 303 was created.  Typically, \fIclientData\fR points to a data
 304 structure containing application-specific information about
 305 the file.  \fIMask\fR is an integer mask indicating which
 306 of the requested conditions actually exists for the file;  it
 307 will contain a subset of the bits in the \fImask\fR argument
 308 to \fBTcl_CreateFileHandler\fR.
 309 .PP
 310 .PP
 311 There may exist only one handler for a given file at a given time.
 312 If \fBTcl_CreateFileHandler\fR is called when a handler already
 313 exists for \fIfd\fR, then the new callback replaces the information
 314 that was previously recorded.
 315 .PP
 316 \fBTcl_DeleteFileHandler\fR may be called to delete the
 317 file handler for \fIfd\fR;  if no handler exists for the
 318 file given by \fIfd\fR then the procedure has no effect.
 319 .PP
 320 The purpose of file handlers is to enable an application to respond to
 321 events while waiting for files to become ready for I/O.  For this to work
 322 correctly, the application may need to use non-blocking I/O operations on
 323 the files for which handlers are declared.  Otherwise the application may
 324 block if it reads or writes too much data; while waiting for the I/O to
 325 complete the application won't be able to service other events. Use
 326 \fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
 327 blocking or nonblocking mode as required.
 328 .PP
 329 .VS
 330 Note that these interfaces are only supported by the Unix
 331 implementation of the Tcl notifier.
 332 .VE
 333
 334 .SH KEYWORDS
 335 callback, file, handler