2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_OpenFileChannel 3 8.3 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_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
281 \fB#include <tcl.h>\fR
284 \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
287 \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
290 \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
293 \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
296 \fBTcl_GetChannelNames\fR(\fIinterp\fR)
299 \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR)
302 \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
305 \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
308 \fBTcl_DetachChannel\fR(\fIinterp, channel\fR)
311 \fBTcl_IsStandardChannel\fR(\fIchannel\fR)
314 \fBTcl_Close\fR(\fIinterp, channel\fR)
317 \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
320 \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
323 \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
326 \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
329 \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
332 \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
335 \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
338 \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
341 \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
344 \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
347 \fBTcl_Eof\fR(\fIchannel\fR)
350 \fBTcl_Flush\fR(\fIchannel\fR)
353 \fBTcl_InputBlocked\fR(\fIchannel\fR)
356 \fBTcl_InputBuffered\fR(\fIchannel\fR)
359 \fBTcl_OutputBuffered\fR(\fIchannel\fR)
362 \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
365 \fBTcl_Tell\fR(\fIchannel\fR)
368 \fBTcl_TruncateChannel\fR(\fIchannel, length\fR)
371 \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
374 \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
377 .AS Tcl_DString *channelName in/out
378 .AP Tcl_Interp *interp in
379 Used for error reporting and to look up a channel registered in it.
380 .AP "const char" *fileName in
381 The name of a local or network file.
382 .AP "const char" *mode in
383 Specifies how the file is to be accessed. May have any of the values
384 allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
385 .AP int permissions in
386 POSIX-style permission flags such as 0644. If a new file is created, these
387 permissions will be set on the created file.
389 The number of elements in \fIargv\fR.
390 .AP "const char" **argv in
391 Arguments for constructing a command pipeline. These values have the same
392 meaning as the non-switch arguments to the Tcl \fBexec\fR command.
394 Specifies the disposition of the stdio handles in pipeline: OR-ed
395 combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and
396 \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child
397 in the pipe is the pipe channel, otherwise it is the same as the standard
398 input of the invoking process; likewise for \fBTCL_STDOUT\fR and
399 \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can
400 redirect stdio handles to override the stdio handles for which
401 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it
402 is set, then such redirections cause an error.
403 .AP ClientData handle in
404 Operating system specific handle for I/O to a file. For Unix this is a
405 file descriptor, for Windows it is a HANDLE.
406 .AP int readOrWrite in
407 OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
408 what operations are valid on \fIhandle\fR.
409 .AP "const char" *channelName in
410 The name of the channel.
412 Points at an integer variable that will receive an OR-ed combination of
413 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
414 open for reading and writing.
415 .AP "const char" *pattern in
416 The pattern to match on, passed to Tcl_StringMatch, or NULL.
417 .AP Tcl_Channel channel in
418 A Tcl channel for input or output. Must have been the return value
419 from a procedure such as \fBTcl_OpenFileChannel\fR.
420 .AP Tcl_Obj *readObjPtr in/out
421 A pointer to a Tcl value in which to store the characters read from the
423 .AP int charsToRead in
424 The number of characters to read from the channel. If the channel's encoding
425 is \fBbinary\fR, this is equivalent to the number of bytes to read from the
427 .AP int appendFlag in
428 If non-zero, data read from the channel will be appended to the value.
429 Otherwise, the data will replace the existing contents of the value.
430 .AP char *readBuf out
431 A buffer in which to store the bytes read from the channel.
432 .AP int bytesToRead in
433 The number of bytes to read from the channel. The buffer \fIreadBuf\fR must
434 be large enough to hold this many bytes.
435 .AP Tcl_Obj *lineObjPtr in/out
436 A pointer to a Tcl value in which to store the line read from the
437 channel. The line read will be appended to the current value of the
439 .AP Tcl_DString *lineRead in/out
440 A pointer to a Tcl dynamic string in which to store the line read from the
441 channel. Must have been initialized by the caller. The line read will be
442 appended to any data already in the dynamic string.
443 .AP "const char" *input in
444 The input to add to a channel buffer.
448 Flag indicating whether the input should be added to the end or
449 beginning of the channel buffer.
450 .AP Tcl_Obj *writeObjPtr in
451 A pointer to a Tcl value whose contents will be output to the channel.
452 .AP "const char" *charBuf in
453 A buffer containing the characters to output to the channel.
454 .AP "const char" *byteBuf in
455 A buffer containing the bytes to output to the channel.
456 .AP int bytesToWrite in
457 The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
458 output to the channel.
459 .AP Tcl_WideInt offset in
460 How far to move the access point in the channel at which the next input or
461 output operation will be applied, measured in bytes from the position
462 given by \fIseekMode\fR. May be either positive or negative.
464 Relative to which point to seek; used with \fIoffset\fR to calculate the new
465 access point for the channel. Legal values are \fBSEEK_SET\fR,
466 \fBSEEK_CUR\fR, and \fBSEEK_END\fR.
467 .AP Tcl_WideInt length in
468 The (non-negative) length to truncate the channel the channel to.
469 .AP "const char" *optionName in
470 The name of an option applicable to this channel, such as \fB\-blocking\fR.
471 May have any of the values accepted by the \fBfconfigure\fR command.
472 .AP Tcl_DString *optionValue in
473 Where to store the value of an option or a list of all options and their
474 values. Must have been initialized by the caller.
475 .AP "const char" *newValue in
476 New value for the option given by \fIoptionName\fR.
480 The Tcl channel mechanism provides a device-independent and
481 platform-independent mechanism for performing buffered input
482 and output operations on a variety of file, socket, and device
484 The channel mechanism is extensible to new channel types, by
485 providing a low-level channel driver for the new type; the channel driver
486 interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
487 channel mechanism provides a buffering scheme modeled after
488 Unix's standard I/O, and it also allows for nonblocking I/O on
491 The procedures described in this manual entry comprise the C APIs of the
492 generic layer of the channel architecture. For a description of the channel
493 driver architecture and how to implement channel drivers for new types of
494 channels, see the manual entry for \fBTcl_CreateChannel\fR.
495 .SH TCL_OPENFILECHANNEL
497 \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
498 returns a channel handle that can be used to perform input and output on
499 the file. This API is modeled after the \fBfopen\fR procedure of
500 the Unix standard I/O library.
501 The syntax and meaning of all arguments is similar to those
502 given in the Tcl \fBopen\fR command when opening a file.
503 If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
504 returns NULL and records a POSIX error code that can be
505 retrieved with \fBTcl_GetErrno\fR.
506 In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
507 leaves an error message in \fIinterp\fR's result after any error.
508 As of Tcl 8.4, the value-based API \fBTcl_FSOpenFileChannel\fR should
509 be used in preference to \fBTcl_OpenFileChannel\fR wherever possible.
511 The newly created channel is not registered in the supplied interpreter; to
512 register it, use \fBTcl_RegisterChannel\fR, described below.
513 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
514 previously closed, the act of creating the new channel also assigns it as a
515 replacement for the standard channel.
516 .SH TCL_OPENCOMMANDCHANNEL
518 \fBTcl_OpenCommandChannel\fR provides a C-level interface to the
519 functions of the \fBexec\fR and \fBopen\fR commands.
520 It creates a sequence of subprocesses specified
521 by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
522 be used to communicate with these subprocesses.
523 The \fIflags\fR argument indicates what sort of communication will
524 exist with the command pipeline.
526 If the \fBTCL_STDIN\fR flag is set then the standard input for the
527 first subprocess will be tied to the channel: writing to the channel
528 will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
529 then standard input for the first subprocess will be the same as this
530 application's standard input. If \fBTCL_STDOUT\fR is set then
531 standard output from the last subprocess can be read from the channel;
532 otherwise it goes to this application's standard output. If
533 \fBTCL_STDERR\fR is set, standard error output for all subprocesses is
534 returned to the channel and results in an error when the channel is
535 closed; otherwise it goes to this application's standard error. If
536 \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
537 redirect the stdio handles to override \fBTCL_STDIN\fR,
538 \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
539 error for argc and argv to override stdio channels for which
540 \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
542 If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
543 returns NULL and records a POSIX error code that can be retrieved with
545 In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
546 the interpreter's result if \fIinterp\fR is not NULL.
548 The newly created channel is not registered in the supplied interpreter; to
549 register it, use \fBTcl_RegisterChannel\fR, described below.
550 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
551 previously closed, the act of creating the new channel also assigns it as a
552 replacement for the standard channel.
553 .SH TCL_MAKEFILECHANNEL
555 \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
556 platform-specific, file handle.
557 The newly created channel is not registered in the supplied interpreter; to
558 register it, use \fBTcl_RegisterChannel\fR, described below.
559 If one of the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was
560 previously closed, the act of creating the new channel also assigns it as a
561 replacement for the standard channel.
564 \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
565 create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
566 \fIinterp\fR. If a channel by that name is not registered in that interpreter,
567 the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it
568 points at an integer variable that will receive an OR-ed combination of
569 \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
570 open for reading and writing.
572 \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the
573 names of the registered channels to the interpreter's result as a
574 list value. \fBTcl_GetChannelNamesEx\fR will filter these names
575 according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it
576 will not do any filtering. The return value is \fBTCL_OK\fR if no
577 errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR,
578 and the error message is left in the interpreter's result.
579 .SH TCL_REGISTERCHANNEL
581 \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
582 in \fIinterp\fR. After this call, Tcl programs executing in that
583 interpreter can refer to the channel in input or output operations using
584 the name given in the call to \fBTcl_CreateChannel\fR. After this call,
585 the channel becomes the property of the interpreter, and the caller should
586 not call \fBTcl_Close\fR for the channel; the channel will be closed
587 automatically when it is unregistered from the interpreter.
589 Code executing outside of any Tcl interpreter can call
590 \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
591 wishes to hold a reference to this channel. Subsequently, the channel can
592 be registered in a Tcl interpreter and it will only be closed when the
593 matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
594 This allows code executing outside of any interpreter to safely hold a
595 reference to a channel that is also registered in a Tcl interpreter.
597 This procedure interacts with the code managing the standard
598 channels. If no standard channels were initialized before the first
599 call to \fBTcl_RegisterChannel\fR, they will get initialized by that
600 call. See \fBTcl_StandardChannels\fR for a general treatise about
601 standard channels and the behavior of the Tcl library with regard to
603 .SH TCL_UNREGISTERCHANNEL
605 \fBTcl_UnregisterChannel\fR removes a channel from the set of channels
606 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
607 able to use the channel's name to refer to the channel in that interpreter.
608 If this operation removed the last registration of the channel in any
609 interpreter, the channel is also closed and destroyed.
611 Code not associated with a Tcl interpreter can call
612 \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
613 that it no longer holds a reference to that channel. If this is the last
614 reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR
615 is very similar to \fBTcl_DetachChannel\fR except that it will also
616 close the channel if no further references to it exist.
617 .SH TCL_DETACHCHANNEL
619 \fBTcl_DetachChannel\fR removes a channel from the set of channels
620 accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
621 able to use the channel's name to refer to the channel in that interpreter.
622 Beyond that, this command has no further effect. It cannot be used on
623 the standard channels (\fBstdout\fR, \fBstderr\fR, \fBstdin\fR), and will return
624 \fBTCL_ERROR\fR if passed one of those channels.
626 Code not associated with a Tcl interpreter can call
627 \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
628 that it no longer holds a reference to that channel. If this is the last
629 reference to the channel, unlike \fBTcl_UnregisterChannel\fR,
630 it will not be closed.
631 .SH TCL_ISSTANDARDCHANNEL
633 \fBTcl_IsStandardChannel\fR tests whether a channel is one of the
634 three standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR.
635 If so, it returns 1, otherwise 0.
637 No attempt is made to check whether the given channel or the standard
638 channels are initialized or otherwise valid.
641 \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
642 currently open channel. The channel should not be registered in any
643 interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
644 the channel's output device prior to destroying the channel, and any
645 buffered input is discarded. If this is a blocking channel, the call does
646 not return until all buffered data is successfully sent to the channel's
647 output device. If this is a nonblocking channel and there is buffered
648 output that cannot be written without blocking, the call returns
649 immediately; output is flushed in the background and the channel will be
650 closed once all of the buffered data has been output. In this case errors
651 during flushing are not reported.
653 If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
654 If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
655 POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
656 If the channel is being closed synchronously and an error occurs during
657 closing of the channel and \fIinterp\fR is not NULL, an error message is
658 left in the interpreter's result.
660 Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
661 registered using \fBTcl_RegisterChannel\fR; see the documentation for
662 \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever
663 been given as the \fBchan\fR argument in a call to
664 \fBTcl_RegisterChannel\fR, you should instead use
665 \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR
666 when all calls to \fBTcl_RegisterChannel\fR have been matched by
667 corresponding calls to \fBTcl_UnregisterChannel\fR.
668 .SH "TCL_READCHARS AND TCL_READ"
670 \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes
671 to UTF-8 based on the channel's encoding and storing the produced data in
672 \fIreadObjPtr\fR's string representation. The return value of
673 \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR,
674 that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the
675 return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that
676 can be retrieved with \fBTcl_GetErrno\fR.
678 Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read
679 all characters currently available (non-blocking) or everything until
682 The return value may be smaller than the value to read, indicating that less
683 data than requested was available. This is called a \fIshort read\fR. In
684 blocking mode, this can only happen on an end-of-file. In nonblocking mode,
685 a short read can also occur if there is not enough input currently
686 available: \fBTcl_ReadChars\fR returns a short count rather than waiting
689 If the channel is in blocking mode, a return value of zero indicates an
690 end-of-file condition. If the channel is in nonblocking mode, a return
691 value of zero indicates either that no input is currently available or an
692 end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell
693 which of these conditions actually occurred.
695 \fBTcl_ReadChars\fR translates the various end-of-line representations into
696 the canonical \fB\en\fR internal representation according to the current
697 end-of-line recognition mode. End-of-line recognition and the various
698 platform-specific modes are described in the manual entry for the Tcl
699 \fBfconfigure\fR command.
701 As a performance optimization, when reading from a channel with the encoding
702 \fBbinary\fR, the bytes are not converted to UTF-8 as they are read.
703 Instead, they are stored in \fIreadObjPtr\fR's internal representation as a
704 byte-array value. The string representation of this value will only be
705 constructed if it is needed (e.g., because of a call to
706 \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read
707 from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and
708 related functions, and then written to a channel without the expense of ever
709 converting to or from UTF-8.
711 \fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not do
712 encoding conversions, regardless of the channel's encoding. It is deprecated
713 and exists for backwards compatibility with non-internationalized Tcl
714 extensions. It consumes bytes from \fIchannel\fR and stores them in
715 \fIreadBuf\fR, performing end-of-line translations on the way. The return value
716 of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in
717 \fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated.
718 Its contents are valid from the zeroth position up to and excluding the
719 position indicated by the return value.
721 \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not
722 compensate for stacking. While \fBTcl_Read\fR (and the other functions
723 in the API) always get their data from the topmost channel in the
724 stack the supplied channel is part of, \fBTcl_ReadRaw\fR does
725 not. Thus this function is \fBonly\fR usable for transformational
726 channel drivers, i.e. drivers used in the middle of a stack of
727 channels, to move data from the channel below into the transformation.
728 .SH "TCL_GETSOBJ AND TCL_GETS"
730 \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to
731 UTF-8 based on the channel's encoding, until a full line of input has been
732 seen. If the channel's encoding is \fBbinary\fR, each byte read from the
733 channel is treated as an individual Unicode character. All of the
734 characters of the line except for the terminating end-of-line character(s)
735 are appended to \fIlineObjPtr\fR's string representation. The end-of-line
736 character(s) are read and discarded.
738 If a line was successfully read, the return value is greater than or equal
739 to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an
740 error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code
741 that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also
742 returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure
743 can be used to distinguish an error from an end-of-file condition.
745 If the channel is in nonblocking mode, the return value can also be \-1 if
746 no data was available or the data that was available did not contain an
747 end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR
748 procedure may be invoked to determine if the channel is blocked because
749 of input unavailability.
751 \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting
752 characters are appended to the dynamic string given by
753 \fIlineRead\fR rather than a Tcl value.
756 \fBTcl_Ungets\fR is used to add data to the input queue of a channel,
757 at either the head or tail of the queue. The pointer \fIinput\fR points
758 to the data that is to be added. The length of the input to add is given
759 by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the
760 data is to be added at the end of queue; otherwise it will be added at the
761 head of the queue. If \fIchannel\fR has a
763 EOF set, no data will be
764 added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or
765 \-1 if an error occurs.
766 .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE"
768 \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at
769 \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the
770 channel's encoding and queued for output to \fIchannel\fR. If
771 \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR
772 to be null-terminated and it outputs everything up to the null.
774 Data queued for output may not appear on the output device immediately, due
775 to internal buffering. If the data should appear immediately, call
776 \fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the
777 \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data
778 to appear as soon as a complete line is accepted for output, set the
779 \fB\-buffering\fR option on the channel to \fBline\fR mode.
781 The return value of \fBTcl_WriteChars\fR is a count of how many bytes were
782 accepted for output to the channel. This is either greater than zero to
783 indicate success or \-1 to indicate that an error occurred. If an error
784 occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be
785 retrieved with \fBTcl_GetErrno\fR.
787 Newline characters in the output data are translated to platform-specific
788 end-of-line sequences according to the \fB\-translation\fR option for the
789 channel. This is done even if the channel has no encoding.
791 \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it
792 accepts a Tcl value whose contents will be output to the channel. The
793 UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted
794 to the channel's encoding and queued for output to \fIchannel\fR.
795 As a performance optimization, when writing to a channel with the encoding
796 \fBbinary\fR, UTF-8 characters are not converted as they are written.
797 Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a
798 byte-array value are written to the channel. The byte-array representation
799 of the value will be constructed if it is needed. In this way,
800 byte-oriented data can be read from a channel, manipulated by calling
801 \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a
802 channel without the expense of ever converting to or from UTF-8.
804 \fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not do
805 encoding conversions, regardless of the channel's encoding. It is
806 deprecated and exists for backwards compatibility with non-internationalized
807 Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at
808 \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If
809 \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be
810 null-terminated and it outputs everything up to the null.
812 \fBTcl_WriteRaw\fR is the same as \fBTcl_Write\fR but does not
813 compensate for stacking. While \fBTcl_Write\fR (and the other
814 functions in the API) always feed their input to the topmost channel
815 in the stack the supplied channel is part of, \fBTcl_WriteRaw\fR does
816 not. Thus this function is \fBonly\fR usable for transformational
817 channel drivers, i.e. drivers used in the middle of a stack of
818 channels, to move data from the transformation into the channel below
822 \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
823 to be written to its underlying file or device as soon as possible.
824 If the channel is in blocking mode, the call does not return until
825 all the buffered data has been sent to the channel or some error occurred.
826 The call returns immediately if the channel is nonblocking; it starts
827 a background flush that will write the buffered data to the channel
828 eventually, as fast as the channel is able to absorb it.
830 The return value is normally \fBTCL_OK\fR.
831 If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
832 records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
835 \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
836 data will be read or written. Buffered output is flushed to the channel and
837 buffered input is discarded, prior to the seek operation.
839 \fBTcl_Seek\fR normally returns the new access point.
840 If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error
841 code that can be retrieved with \fBTcl_GetErrno\fR.
842 After an error, the access point may or may not have been moved.
845 \fBTcl_Tell\fR returns the current access point for a channel. The returned
846 value is \-1 if the channel does not support seeking.
847 .SH TCL_TRUNCATECHANNEL
849 \fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR
850 to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the
851 operation succeeded, and \fBTCL_ERROR\fR otherwise.
852 .SH TCL_GETCHANNELOPTION
854 \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of
855 the options currently in effect for a channel, or a list of all options and
856 their values. The \fIchannel\fR argument identifies the channel for which
857 to query an option or retrieve all options and their values.
858 If \fIoptionName\fR is not NULL, it is the name of the
859 option to query; the option's value is copied to the Tcl dynamic string
860 denoted by \fIoptionValue\fR. If
861 \fIoptionName\fR is NULL, the function stores an alternating list of option
862 names and their values in \fIoptionValue\fR, using a series of calls to
863 \fBTcl_DStringAppendElement\fR. The various preexisting options and
864 their possible values are described in the manual entry for the Tcl
865 \fBfconfigure\fR command. Other options can be added by each channel type.
866 These channel type specific options are described in the manual entry for
867 the Tcl command that creates a channel of that type; for example, the
868 additional options for TCP based channels are described in the manual entry
869 for the Tcl \fBsocket\fR command.
870 The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
871 \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
873 .SH TCL_SETCHANNELOPTION
875 \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR
876 for an option \fIoptionName\fR on \fIchannel\fR.
877 The procedure normally returns \fBTCL_OK\fR. If an error occurs,
878 it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
879 \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result.
882 \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
883 an end of file during the last input operation.
886 \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
887 nonblocking mode and the last input operation returned less data than
888 requested because there was insufficient data available.
889 The call always returns zero if the channel is in blocking mode.
890 .SH TCL_INPUTBUFFERED
892 \fBTcl_InputBuffered\fR returns the number of bytes of input currently
893 buffered in the internal buffers for a channel. If the channel is not open
894 for reading, this function always returns zero.
895 .SH TCL_OUTPUTBUFFERED
897 \fBTcl_OutputBuffered\fR returns the number of bytes of output
898 currently buffered in the internal buffers for a channel. If the
899 channel is not open for writing, this function always returns zero.
900 .SH "PLATFORM ISSUES"
902 The handles returned from \fBTcl_GetChannelHandle\fR depend on the
903 platform and the channel type. On Unix platforms, the handle is
904 always a Unix file descriptor as returned from the \fBopen\fR system
905 call. On Windows platforms, the handle is a file \fBHANDLE\fR when
906 the channel was created with \fBTcl_OpenFileChannel\fR,
907 \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
908 channel types may return a different type of handle on Windows
911 DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)
913 access point, blocking, buffered I/O, channel, channel driver, end of file,
914 flush, input, nonblocking, output, read, seek, write
OSDN Git Service
