2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
3 '\" Copyright (c) 1997-2000 Ajuba Solutions.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .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
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
281 \fB#include <tcl.h>\fR
284 \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
287 \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
289 const Tcl_ChannelType *
290 \fBTcl_GetChannelType\fR(\fIchannel\fR)
293 \fBTcl_GetChannelName\fR(\fIchannel\fR)
296 \fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
299 \fBTcl_GetChannelThread\fR(\fIchannel\fR)
302 \fBTcl_GetChannelMode\fR(\fIchannel\fR)
305 \fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
307 \fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
309 \fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
312 \fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
315 \fBTcl_IsChannelShared\fR(\fIchannel\fR)
318 \fBTcl_IsChannelRegistered\fR(\fIinterp, channel\fR)
321 \fBTcl_IsChannelExisting\fR(\fIchannelName\fR)
324 \fBTcl_CutChannel\fR(\fIchannel\fR)
327 \fBTcl_SpliceChannel\fR(\fIchannel\fR)
330 \fBTcl_ClearChannelHandlers\fR(\fIchannel\fR)
333 \fBTcl_ChannelBuffered\fR(\fIchannel\fR)
336 \fBTcl_ChannelName\fR(\fItypePtr\fR)
338 Tcl_ChannelTypeVersion
339 \fBTcl_ChannelVersion\fR(\fItypePtr\fR)
341 Tcl_DriverBlockModeProc *
342 \fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR)
344 Tcl_DriverCloseProc *
345 \fBTcl_ChannelCloseProc\fR(\fItypePtr\fR)
347 Tcl_DriverClose2Proc *
348 \fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR)
350 Tcl_DriverInputProc *
351 \fBTcl_ChannelInputProc\fR(\fItypePtr\fR)
353 Tcl_DriverOutputProc *
354 \fBTcl_ChannelOutputProc\fR(\fItypePtr\fR)
357 \fBTcl_ChannelSeekProc\fR(\fItypePtr\fR)
359 Tcl_DriverWideSeekProc *
360 \fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR)
362 Tcl_DriverThreadActionProc *
363 \fBTcl_ChannelThreadActionProc\fR(\fItypePtr\fR)
365 Tcl_DriverTruncateProc *
366 \fBTcl_ChannelTruncateProc\fR(\fItypePtr\fR)
368 Tcl_DriverSetOptionProc *
369 \fBTcl_ChannelSetOptionProc\fR(\fItypePtr\fR)
371 Tcl_DriverGetOptionProc *
372 \fBTcl_ChannelGetOptionProc\fR(\fItypePtr\fR)
374 Tcl_DriverWatchProc *
375 \fBTcl_ChannelWatchProc\fR(\fItypePtr\fR)
377 Tcl_DriverGetHandleProc *
378 \fBTcl_ChannelGetHandleProc\fR(\fItypePtr\fR)
380 Tcl_DriverFlushProc *
381 \fBTcl_ChannelFlushProc\fR(\fItypePtr\fR)
383 Tcl_DriverHandlerProc *
384 \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR)
387 .AS "const Tcl_ChannelType" *channelName
388 .AP "const Tcl_ChannelType" *typePtr in
389 Points to a structure containing the addresses of procedures that
390 can be called to perform I/O and other functions on the channel.
391 .AP "const char" *channelName in
392 The name of this channel, such as \fBfile3\fR; must not be in use
393 by any other channel. Can be NULL, in which case the channel is
394 created without a name. If the created channel is assigned to one
395 of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR),
396 the assigned channel name will be the name of the standard channel.
397 .AP ClientData instanceData in
398 Arbitrary one-word value to be associated with this channel. This
399 value is passed to procedures in \fItypePtr\fR when they are invoked.
401 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
402 whether a channel is readable and writable.
403 .AP Tcl_Channel channel in
404 The channel to operate on.
406 \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
407 means the output handle is wanted.
408 .AP ClientData *handlePtr out
409 Points to the location where the desired OS-specific handle should be
412 The size, in bytes, of buffers to allocate in this channel.
414 An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
415 and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
417 .AP Tcl_Interp *interp in
418 Current interpreter. (can be NULL)
419 .AP "const char" *optionName in
420 Name of the invalid option.
421 .AP "const char" *optionList in
422 Specific options list (space separated words, without
424 to append to the standard generic options list.
425 Can be NULL for generic options error message only.
429 Tcl uses a two-layered channel architecture. It provides a generic upper
430 layer to enable C and Tcl programs to perform input and output using the
431 same APIs for a variety of files, devices, sockets etc. The generic C APIs
432 are described in the manual entry for \fBTcl_OpenFileChannel\fR.
434 The lower layer provides type-specific channel drivers for each type
435 of device supported on each platform. This manual entry describes the
436 C APIs used to communicate between the generic layer and the
437 type-specific channel drivers. It also explains how new types of
438 channels can be added by providing new channel drivers.
440 Channel drivers consist of a number of components: First, each channel
441 driver provides a \fBTcl_ChannelType\fR structure containing pointers to
442 functions implementing the various operations used by the generic layer to
443 communicate with the channel driver. The \fBTcl_ChannelType\fR structure
444 and the functions referenced by it are described in the section
445 \fBTCL_CHANNELTYPE\fR, below.
447 Second, channel drivers usually provide a Tcl command to create
448 instances of that type of channel. For example, the Tcl \fBopen\fR
449 command creates channels that use the file and command channel
450 drivers, and the Tcl \fBsocket\fR command creates channels that use
451 TCP sockets for network communication.
453 Third, a channel driver optionally provides a C function to open
454 channel instances of that type. For example, \fBTcl_OpenFileChannel\fR
455 opens a channel that uses the file channel driver, and
456 \fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network
457 protocol. These creation functions typically use
458 \fBTcl_CreateChannel\fR internally to open the channel.
460 To add a new type of channel you must implement a C API or a Tcl command
461 that opens a channel by invoking \fBTcl_CreateChannel\fR.
462 When your driver calls \fBTcl_CreateChannel\fR it passes in
463 a \fBTcl_ChannelType\fR structure describing the driver's I/O
465 The generic layer will then invoke the functions referenced in that
466 structure to perform operations on the channel.
468 \fBTcl_CreateChannel\fR opens a new channel and associates the supplied
469 \fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the
470 mode indicated by \fImask\fR.
471 For a discussion of channel drivers, their operations and the
472 \fBTcl_ChannelType\fR structure, see the section \fBTCL_CHANNELTYPE\fR, below.
474 \fBTcl_CreateChannel\fR interacts with the code managing the standard
475 channels. Once a standard channel was initialized either through a
476 call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
477 closing this standard channel will cause the next call to
478 \fBTcl_CreateChannel\fR to make the new channel the new standard
479 channel too. See \fBTcl_StandardChannels\fR for a general treatise
480 about standard channels and the behavior of the Tcl library with
483 \fBTcl_GetChannelInstanceData\fR returns the instance data associated with
484 the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
485 argument in the call to \fBTcl_CreateChannel\fR that created this channel.
487 \fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR
488 structure used by the channel in the \fIchannel\fR argument. This is
489 the same as the \fItypePtr\fR argument in the call to
490 \fBTcl_CreateChannel\fR that created this channel.
492 \fBTcl_GetChannelName\fR returns a string containing the name associated
493 with the channel, or NULL if the \fIchannelName\fR argument to
494 \fBTcl_CreateChannel\fR was NULL.
496 \fBTcl_GetChannelHandle\fR places the OS-specific device handle
497 associated with \fIchannel\fR for the given \fIdirection\fR in the
498 location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If
499 the channel does not have a device handle for the specified direction,
500 then \fBTCL_ERROR\fR is returned instead. Different channel drivers
501 will return different types of handle. Refer to the manual entries
502 for each driver to determine what type of handle is returned.
504 \fBTcl_GetChannelThread\fR returns the id of the thread currently managing
505 the specified \fIchannel\fR. This allows channel drivers to send their file
506 events to the correct event queue even for a multi-threaded core.
508 \fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
509 and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
512 \fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
513 allocated to store input or output in \fIchannel\fR. If the value was not set
514 by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
515 the default value of 4096 is returned.
517 \fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
518 will be allocated in subsequent operations on the channel to store input or
519 output. The \fIsize\fR argument should be between one and one million,
520 allowing buffers of one byte to one million bytes. If \fIsize\fR is
521 outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
524 \fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
525 the generic layer that the events specified by \fImask\fR have
526 occurred on the channel. Channel drivers are responsible for invoking
527 this function whenever the channel handlers need to be called for the
528 channel. See \fBWATCHPROC\fR below for more details.
530 \fBTcl_BadChannelOption\fR is called from driver specific
531 \fIsetOptionProc\fR or \fIgetOptionProc\fR to generate a complete
534 \fBTcl_ChannelBuffered\fR returns the number of bytes of input
535 currently buffered in the internal buffer (push back area) of the
536 channel itself. It does not report about the data in the overall
537 buffers for the stack of channels the supplied channel is part of.
539 \fBTcl_IsChannelShared\fR checks the refcount of the specified
540 \fIchannel\fR and returns whether the \fIchannel\fR was shared among
541 multiple interpreters (result == 1) or not (result == 0).
543 \fBTcl_IsChannelRegistered\fR checks whether the specified \fIchannel\fR is
544 registered in the given \fIinterp\fRreter (result == 1) or not
547 \fBTcl_IsChannelExisting\fR checks whether a channel with the specified
548 name is registered in the (thread)-global list of all channels (result
549 == 1) or not (result == 0).
551 \fBTcl_CutChannel\fR removes the specified \fIchannel\fR from the
552 (thread)global list of all channels (of the current thread).
553 Application to a channel still registered in some interpreter
555 Also notifies the driver if the \fBTcl_ChannelType\fR version is
556 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
557 \fBTcl_DriverThreadActionProc\fR is defined for it.
559 \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the
560 (thread)global list of all channels (of the current thread).
561 Application to a channel registered in some interpreter is not allowed.
562 Also notifies the driver if the \fBTcl_ChannelType\fR version is
563 \fBTCL_CHANNEL_VERSION_4\fR (or higher), and
564 \fBTcl_DriverThreadActionProc\fR is defined for it.
566 \fBTcl_ClearChannelHandlers\fR removes all channel handlers and event
567 scripts associated with the specified \fIchannel\fR, thus shutting
568 down all event processing for this channel.
571 A channel driver provides a \fBTcl_ChannelType\fR structure that contains
572 pointers to functions that implement the various operations on a channel;
573 these operations are invoked as needed by the generic layer. The structure
574 was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked
575 channel drivers. See the \fBOLD CHANNEL TYPES\fR section below for
576 details about the old structure.
578 The \fBTcl_ChannelType\fR structure contains the following fields:
581 typedef struct Tcl_ChannelType {
582 const char *\fItypeName\fR;
583 Tcl_ChannelTypeVersion \fIversion\fR;
584 Tcl_DriverCloseProc *\fIcloseProc\fR;
585 Tcl_DriverInputProc *\fIinputProc\fR;
586 Tcl_DriverOutputProc *\fIoutputProc\fR;
587 Tcl_DriverSeekProc *\fIseekProc\fR;
588 Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
589 Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
590 Tcl_DriverWatchProc *\fIwatchProc\fR;
591 Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
592 Tcl_DriverClose2Proc *\fIclose2Proc\fR;
593 Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
594 Tcl_DriverFlushProc *\fIflushProc\fR;
595 Tcl_DriverHandlerProc *\fIhandlerProc\fR;
596 Tcl_DriverWideSeekProc *\fIwideSeekProc\fR;
597 Tcl_DriverThreadActionProc *\fIthreadActionProc\fR;
598 Tcl_DriverTruncateProc *\fItruncateProc\fR;
599 } \fBTcl_ChannelType\fR;
602 It is not necessary to provide implementations for all channel
603 operations. Those which are not necessary may be set to NULL in the
604 struct: \fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR,
605 \fIgetOptionProc\fR, \fIgetHandleProc\fR, and \fIclose2Proc\fR, in addition to
606 \fIflushProc\fR, \fIhandlerProc\fR, \fIthreadActionProc\fR, and
607 \fItruncateProc\fR. Other functions that cannot be implemented in a
608 meaningful way should return \fBEINVAL\fR when called, to indicate
609 that the operations they represent are not available. Also note that
610 \fIwideSeekProc\fR can be NULL if \fIseekProc\fR is.
612 The user should only use the above structure for \fBTcl_ChannelType\fR
613 instantiation. When referencing fields in a \fBTcl_ChannelType\fR
614 structure, the following functions should be used to obtain the values:
615 \fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR,
616 \fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR,
617 \fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR,
618 \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR,
619 \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR,
620 \fBTcl_ChannelTruncateProc\fR,
621 \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR,
622 \fBTcl_ChannelWatchProc\fR, \fBTcl_ChannelGetHandleProc\fR,
623 \fBTcl_ChannelFlushProc\fR, or \fBTcl_ChannelHandlerProc\fR.
625 The change to the structures was made in such a way that standard channel
626 types are binary compatible. However, channel types that use stacked
627 channels (i.e. TLS, Trf) have new versions to correspond to the above change
628 since the previous code for stacked channels had problems.
631 The \fItypeName\fR field contains a null-terminated string that
632 identifies the type of the device implemented by this driver, e.g.
633 \fBfile\fR or \fBsocket\fR.
635 This value can be retrieved with \fBTcl_ChannelName\fR, which returns
636 a pointer to the string.
640 The \fIversion\fR field should be set to the version of the structure
641 that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended.
642 \fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member.
643 \fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member
644 (includes \fIwideSeekProc\fR).
645 \fBTCL_CHANNEL_VERSION_5\fR must be set to specify the
646 \fItruncateProc\fR members (includes
647 \fIwideSeekProc\fR and \fIthreadActionProc\fR).
648 If it is not set to any of these, then this
649 \fBTcl_ChannelType\fR is assumed to have the original structure. See
650 \fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize
651 and function with either structures, stacked channels must be of at
652 least \fBTCL_CHANNEL_VERSION_2\fR to function correctly.
654 This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns
656 \fBTCL_CHANNEL_VERSION_5\fR,
657 \fBTCL_CHANNEL_VERSION_4\fR,
658 \fBTCL_CHANNEL_VERSION_3\fR,
659 \fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR.
662 The \fIblockModeProc\fR field contains the address of a function called by
663 the generic layer to set blocking and nonblocking mode on the device.
664 \fIBlockModeProc\fR should match the following prototype:
667 typedef int \fBTcl_DriverBlockModeProc\fR(
668 ClientData \fIinstanceData\fR,
672 The \fIinstanceData\fR is the same as the value passed to
673 \fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR
674 argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to
675 set the device into blocking or nonblocking mode. The function should
676 return zero if the operation was successful, or a nonzero POSIX error code
677 if the operation failed.
679 If the operation is successful, the function can modify the supplied
680 \fIinstanceData\fR to record that the channel entered blocking or
681 nonblocking mode and to implement the blocking or nonblocking behavior.
682 For some device types, the blocking and nonblocking behavior can be
683 implemented by the underlying operating system; for other device types, the
684 behavior must be emulated in the channel driver.
686 This value can be retrieved with \fBTcl_ChannelBlockModeProc\fR, which returns
687 a pointer to the function.
689 A channel driver \fBnot\fR supplying a \fIblockModeProc\fR has to be
690 very, very careful. It has to tell the generic layer exactly which
691 blocking mode is acceptable to it, and should this also document for
692 the user so that the blocking mode of the channel is not changed to an
693 unacceptable value. Any confusion here may lead the interpreter into a
694 (spurious and difficult to find) deadlock.
695 .SS "CLOSEPROC AND CLOSE2PROC"
697 The \fIcloseProc\fR field contains the address of a function called by the
698 generic layer to clean up driver-related information when the channel is
699 closed. \fICloseProc\fR must match the following prototype:
702 typedef int \fBTcl_DriverCloseProc\fR(
703 ClientData \fIinstanceData\fR,
704 Tcl_Interp *\fIinterp\fR);
707 The \fIinstanceData\fR argument is the same as the value provided to
708 \fBTcl_CreateChannel\fR when the channel was created. The function should
709 release any storage maintained by the channel driver for this channel, and
710 close the input and output devices encapsulated by this channel. All queued
711 output will have been flushed to the device before this function is called,
712 and no further driver operations will be invoked on this instance after
713 calling the \fIcloseProc\fR. If the close operation is successful, the
714 procedure should return zero; otherwise it should return a nonzero POSIX
715 error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
716 the procedure should store an error message in the interpreter's result.
718 Alternatively, channels that support closing the read and write sides
719 independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
720 \fIclose2Proc\fR to the address of a function that matches the
724 typedef int \fBTcl_DriverClose2Proc\fR(
725 ClientData \fIinstanceData\fR,
726 Tcl_Interp *\fIinterp\fR,
730 The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
731 combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to
732 indicate that the driver should close the read and/or write side of
733 the channel. The channel driver may be invoked to perform
734 additional operations on the channel after \fIclose2Proc\fR is
735 called to close one or both sides of the channel. If \fIflags\fR is
736 \fB0\fR (zero), the driver should close the channel in the manner
737 described above for \fIcloseProc\fR. No further operations will be
738 invoked on this instance after \fIclose2Proc\fR is called with all
739 flags cleared. In all cases, the \fIclose2Proc\fR function should
740 return zero if the close operation was successful; otherwise it should
741 return a nonzero POSIX error code. In addition, if an error occurs and
742 \fIinterp\fR is not NULL, the procedure should store an error message
743 in the interpreter's result.
745 The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with
746 \fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which
747 return a pointer to the respective function.
750 The \fIinputProc\fR field contains the address of a function called by the
751 generic layer to read data from the file or device and store it in an
752 internal buffer. \fIInputProc\fR must match the following prototype:
755 typedef int \fBTcl_DriverInputProc\fR(
756 ClientData \fIinstanceData\fR,
759 int *\fIerrorCodePtr\fR);
762 \fIInstanceData\fR is the same as the value passed to
763 \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
764 argument points to an array of bytes in which to store input from the
765 device, and the \fIbufSize\fR argument indicates how many bytes are
766 available at \fIbuf\fR.
768 The \fIerrorCodePtr\fR argument points to an integer variable provided by
769 the generic layer. If an error occurs, the function should set the variable
770 to a POSIX error code that identifies the error that occurred.
772 The function should read data from the input device encapsulated by the
773 channel and store it at \fIbuf\fR. On success, the function should return
774 a nonnegative integer indicating how many bytes were read from the input
775 device and stored at \fIbuf\fR. On error, the function should return -1. If
776 an error occurs after some data has been read from the device, that data is
779 If \fIinputProc\fR can determine that the input device has some data
780 available but less than requested by the \fIbufSize\fR argument, the
781 function should only attempt to read as much data as is available and
782 return without blocking. If the input device has no data available
783 whatsoever and the channel is in nonblocking mode, the function should
784 return an \fBEAGAIN\fR error. If the input device has no data available
785 whatsoever and the channel is in blocking mode, the function should block
786 for the shortest possible time until at least one byte of data can be read
787 from the device; then, it should return as much data as it can read without
790 This value can be retrieved with \fBTcl_ChannelInputProc\fR, which returns
791 a pointer to the function.
794 The \fIoutputProc\fR field contains the address of a function called by the
795 generic layer to transfer data from an internal buffer to the output device.
796 \fIOutputProc\fR must match the following prototype:
799 typedef int \fBTcl_DriverOutputProc\fR(
800 ClientData \fIinstanceData\fR,
801 const char *\fIbuf\fR,
803 int *\fIerrorCodePtr\fR);
806 \fIInstanceData\fR is the same as the value passed to
807 \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
808 argument contains an array of bytes to be written to the device, and the
809 \fItoWrite\fR argument indicates how many bytes are to be written from the
812 The \fIerrorCodePtr\fR argument points to an integer variable provided by
813 the generic layer. If an error occurs, the function should set this
814 variable to a POSIX error code that identifies the error.
816 The function should write the data at \fIbuf\fR to the output device
817 encapsulated by the channel. On success, the function should return a
818 nonnegative integer indicating how many bytes were written to the output
819 device. The return value is normally the same as \fItoWrite\fR, but may be
820 less in some cases such as if the output operation is interrupted by a
821 signal. If an error occurs the function should return -1. In case of
822 error, some data may have been written to the device.
824 If the channel is nonblocking and the output device is unable to absorb any
825 data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
826 without writing any data.
828 This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns
829 a pointer to the function.
830 .SS "SEEKPROC AND WIDESEEKPROC"
832 The \fIseekProc\fR field contains the address of a function called by the
833 generic layer to move the access point at which subsequent input or output
834 operations will be applied. \fISeekProc\fR must match the following
838 typedef int \fBTcl_DriverSeekProc\fR(
839 ClientData \fIinstanceData\fR,
842 int *\fIerrorCodePtr\fR);
845 The \fIinstanceData\fR argument is the same as the value given to
846 \fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and
847 \fIseekMode\fR have the same meaning as for the \fBTcl_Seek\fR
848 procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR).
850 The \fIerrorCodePtr\fR argument points to an integer variable provided by
851 the generic layer for returning \fBerrno\fR values from the function. The
852 function should set this variable to a POSIX error code if an error occurs.
853 The function should store an \fBEINVAL\fR error code if the channel type
854 does not implement seeking.
856 The return value is the new access point or -1 in case of error. If an
857 error occurred, the function should not move the access point.
859 If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR
860 field may contain the address of an alternative function to use which
861 handles wide (i.e. larger than 32-bit) offsets, so allowing seeks
862 within files larger than 2GB. The \fIwideSeekProc\fR will be called
863 in preference to the \fIseekProc\fR, but both must be defined if the
864 \fIwideSeekProc\fR is defined. \fIWideSeekProc\fR must match the
868 typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
869 ClientData \fIinstanceData\fR,
870 Tcl_WideInt \fIoffset\fR,
872 int *\fIerrorCodePtr\fR);
875 The arguments and return values mean the same thing as with
876 \fIseekProc\fR above, except that the type of offsets and the return
879 The \fIseekProc\fR value can be retrieved with
880 \fBTcl_ChannelSeekProc\fR, which returns a pointer to the function,
881 and similarly the \fIwideSeekProc\fR can be retrieved with
882 \fBTcl_ChannelWideSeekProc\fR.
885 The \fIsetOptionProc\fR field contains the address of a function called by
886 the generic layer to set a channel type specific option on a channel.
887 \fIsetOptionProc\fR must match the following prototype:
890 typedef int \fBTcl_DriverSetOptionProc\fR(
891 ClientData \fIinstanceData\fR,
892 Tcl_Interp *\fIinterp\fR,
893 const char *\fIoptionName\fR,
894 const char *\fInewValue\fR);
897 \fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
898 the new value for that option, as a string. The \fIinstanceData\fR is the
899 same as the value given to \fBTcl_CreateChannel\fR when this channel was
900 created. The function should do whatever channel type specific action is
901 required to implement the new value of the option.
903 Some options are handled by the generic code and this function is never
904 called to set them, e.g. \fB\-blockmode\fR. Other options are specific to
905 each channel type and the \fIsetOptionProc\fR procedure of the channel
906 driver will get called to implement them. The \fIsetOptionProc\fR field can
907 be NULL, which indicates that this channel type supports no type specific
910 If the option value is successfully modified to the new value, the function
911 returns \fBTCL_OK\fR.
912 It should call \fBTcl_BadChannelOption\fR which itself returns
913 \fBTCL_ERROR\fR if the \fIoptionName\fR is
915 If \fInewValue\fR specifies a value for the option that
916 is not supported or if a system call error occurs,
917 the function should leave an error message in the
918 \fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
919 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
922 This value can be retrieved with \fBTcl_ChannelSetOptionProc\fR, which returns
923 a pointer to the function.
926 The \fIgetOptionProc\fR field contains the address of a function called by
927 the generic layer to get the value of a channel type specific option on a
928 channel. \fIgetOptionProc\fR must match the following prototype:
931 typedef int \fBTcl_DriverGetOptionProc\fR(
932 ClientData \fIinstanceData\fR,
933 Tcl_Interp *\fIinterp\fR,
934 const char *\fIoptionName\fR,
935 Tcl_DString *\fIoptionValue\fR);
938 \fIOptionName\fR is the name of an option supported by this type of
939 channel. If the option name is not NULL, the function stores its current
940 value, as a string, in the Tcl dynamic string \fIoptionValue\fR.
941 If \fIoptionName\fR is NULL, the function stores in \fIoptionValue\fR an
942 alternating list of all supported options and their current values.
943 On success, the function returns \fBTCL_OK\fR.
944 It should call \fBTcl_BadChannelOption\fR which itself returns
945 \fBTCL_ERROR\fR if the \fIoptionName\fR is
946 unrecognized. If a system call error occurs,
947 the function should leave an error message in the
948 result of \fIinterp\fR if \fIinterp\fR is not NULL. The
949 function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
952 Some options are handled by the generic code and this function is never
953 called to retrieve their value, e.g. \fB\-blockmode\fR. Other options are
954 specific to each channel type and the \fIgetOptionProc\fR procedure of the
955 channel driver will get called to implement them. The \fIgetOptionProc\fR
956 field can be NULL, which indicates that this channel type supports no type
959 This value can be retrieved with \fBTcl_ChannelGetOptionProc\fR, which returns
960 a pointer to the function.
963 The \fIwatchProc\fR field contains the address of a function called
964 by the generic layer to initialize the event notification mechanism to
965 notice events of interest on this channel.
966 \fIWatchProc\fR should match the following prototype:
969 typedef void \fBTcl_DriverWatchProc\fR(
970 ClientData \fIinstanceData\fR,
974 The \fIinstanceData\fR is the same as the value passed to
975 \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
976 argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
977 and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
978 noticing on this channel.
980 The function should initialize device type specific mechanisms to
981 notice when an event of interest is present on the channel. When one
982 or more of the designated events occurs on the channel, the channel
983 driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
984 the generic channel module. The driver should take care not to starve
985 other channel drivers or sources of callbacks by invoking
986 Tcl_NotifyChannel too frequently. Fairness can be insured by using
987 the Tcl event queue to allow the channel event to be scheduled in sequence
988 with other events. See the description of \fBTcl_QueueEvent\fR for
989 details on how to queue an event.
991 This value can be retrieved with \fBTcl_ChannelWatchProc\fR, which returns
992 a pointer to the function.
995 The \fIgetHandleProc\fR field contains the address of a function called by
996 the generic layer to retrieve a device-specific handle from the channel.
997 \fIGetHandleProc\fR should match the following prototype:
1000 typedef int \fBTcl_DriverGetHandleProc\fR(
1001 ClientData \fIinstanceData\fR,
1002 int \fIdirection\fR,
1003 ClientData *\fIhandlePtr\fR);
1006 \fIInstanceData\fR is the same as the value passed to
1007 \fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
1008 argument is either \fBTCL_READABLE\fR to retrieve the handle used
1009 for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
1012 If the channel implementation has device-specific handles, the
1013 function should retrieve the appropriate handle associated with the
1014 channel, according the \fIdirection\fR argument. The handle should be
1015 stored in the location referred to by \fIhandlePtr\fR, and
1016 \fBTCL_OK\fR should be returned. If the channel is not open for the
1017 specified direction, or if the channel implementation does not use
1018 device handles, the function should return \fBTCL_ERROR\fR.
1020 This value can be retrieved with \fBTcl_ChannelGetHandleProc\fR, which returns
1021 a pointer to the function.
1024 The \fIflushProc\fR field is currently reserved for future use.
1025 It should be set to NULL.
1026 \fIFlushProc\fR should match the following prototype:
1029 typedef int \fBTcl_DriverFlushProc\fR(
1030 ClientData \fIinstanceData\fR);
1033 This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
1034 a pointer to the function.
1037 The \fIhandlerProc\fR field contains the address of a function called by
1038 the generic layer to notify the channel that an event occurred. It should
1039 be defined for stacked channel drivers that wish to be notified of events
1040 that occur on the underlying (stacked) channel.
1041 \fIHandlerProc\fR should match the following prototype:
1044 typedef int \fBTcl_DriverHandlerProc\fR(
1045 ClientData \fIinstanceData\fR,
1046 int \fIinterestMask\fR);
1049 \fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
1050 when this channel was created. The \fIinterestMask\fR is an OR-ed
1051 combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what
1052 type of event occurred on this channel.
1054 This value can be retrieved with \fBTcl_ChannelHandlerProc\fR, which returns
1055 a pointer to the function.
1057 .SS "THREADACTIONPROC"
1059 The \fIthreadActionProc\fR field contains the address of the function
1060 called by the generic layer when a channel is created, closed, or
1061 going to move to a different thread, i.e. whenever thread-specific
1062 driver state might have to initialized or updated. It can be NULL.
1063 The action \fITCL_CHANNEL_THREAD_REMOVE\fR is used to notify the
1064 driver that it should update or remove any thread-specific data it
1065 might be maintaining for the channel.
1067 The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the
1068 driver that it should update or initialize any thread-specific data it
1069 might be maintaining using the calling thread as the associate. See
1070 \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail.
1073 typedef void \fBTcl_DriverThreadActionProc\fR(
1074 ClientData \fIinstanceData\fR,
1078 \fIInstanceData\fR is the same as the value passed to
1079 \fBTcl_CreateChannel\fR when this channel was created.
1081 These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
1082 which returns a pointer to the function.
1085 The \fItruncateProc\fR field contains the address of the function
1086 called by the generic layer when a channel is truncated to some
1087 length. It can be NULL.
1090 typedef int \fBTcl_DriverTruncateProc\fR(
1091 ClientData \fIinstanceData\fR,
1092 Tcl_WideInt \fIlength\fR);
1095 \fIInstanceData\fR is the same as the value passed to
1096 \fBTcl_CreateChannel\fR when this channel was created, and
1097 \fIlength\fR is the new length of the underlying file, which should
1098 not be negative. The result should be 0 on success or an errno code
1099 (suitable for use with \fBTcl_SetErrno\fR) on failure.
1101 These values can be retrieved with \fBTcl_ChannelTruncateProc\fR,
1102 which returns a pointer to the function.
1103 .SH TCL_BADCHANNELOPTION
1105 This procedure generates a
1108 (optional) interpreter. It is used by channel drivers when
1109 an invalid Set/Get option is requested. Its purpose is to concatenate
1110 the generic options list to the specific ones and factorize
1111 the generic options error message string.
1113 It always returns \fBTCL_ERROR\fR
1115 An error message is generated in \fIinterp\fR's result value to
1116 indicate that a command was invoked with a bad option.
1117 The message has the form
1119 bad option "blah": should be one of
1120 <...generic options...>+<...specific options...>
1122 so you get for instance:
1124 bad option "-blah": should be one of -blocking,
1125 -buffering, -buffersize, -eofchar, -translation,
1126 -peername, or -sockname
1128 when called with \fIoptionList\fR equal to
1129 .QW "peername sockname"
1132 is the \fIoptionName\fR argument and
1133 .QW "<specific options>"
1134 is a space separated list of specific option words.
1135 The function takes good care of inserting minus signs before
1136 each option, commas after, and an
1138 before the last option.
1139 .SH "OLD CHANNEL TYPES"
1140 The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
1141 the following fields:
1144 typedef struct Tcl_ChannelType {
1145 const char *\fItypeName\fR;
1146 Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
1147 Tcl_DriverCloseProc *\fIcloseProc\fR;
1148 Tcl_DriverInputProc *\fIinputProc\fR;
1149 Tcl_DriverOutputProc *\fIoutputProc\fR;
1150 Tcl_DriverSeekProc *\fIseekProc\fR;
1151 Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
1152 Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
1153 Tcl_DriverWatchProc *\fIwatchProc\fR;
1154 Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
1155 Tcl_DriverClose2Proc *\fIclose2Proc\fR;
1156 } \fBTcl_ChannelType\fR;
1159 It is still possible to create channel with the above structure. The
1160 internal channel code will determine the version. It is imperative to use
1161 the new \fBTcl_ChannelType\fR structure if you are creating a stacked
1162 channel driver, due to problems with the earlier stacked channel
1163 implementation (in 8.2.0 to 8.3.1).
1165 Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part
1166 of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure
1167 contained the following fields:
1170 typedef struct Tcl_ChannelType {
1171 const char *\fItypeName\fR;
1172 Tcl_ChannelTypeVersion \fIversion\fR;
1173 Tcl_DriverCloseProc *\fIcloseProc\fR;
1174 Tcl_DriverInputProc *\fIinputProc\fR;
1175 Tcl_DriverOutputProc *\fIoutputProc\fR;
1176 Tcl_DriverSeekProc *\fIseekProc\fR;
1177 Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
1178 Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
1179 Tcl_DriverWatchProc *\fIwatchProc\fR;
1180 Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
1181 Tcl_DriverClose2Proc *\fIclose2Proc\fR;
1182 Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
1183 Tcl_DriverFlushProc *\fIflushProc\fR;
1184 Tcl_DriverHandlerProc *\fIhandlerProc\fR;
1185 Tcl_DriverTruncateProc *\fItruncateProc\fR;
1186 } \fBTcl_ChannelType\fR;
1189 When the above structure is registered as a channel type, the
1190 \fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR.
1192 Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
1194 blocking, channel driver, channel registration, channel type, nonblocking
OSDN Git Service
