Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: OpenFileChnl.3,v 1.20.2.4 2004/07/16 22:22:15 andreas_kupries Exp $ | |
8 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
9 | '\" manual entries. | |
10 | '\" | |
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) | |
17 | '\" | |
18 | '\" .AS ?type? ?name? | |
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. | |
22 | '\" | |
23 | '\" .BS | |
24 | '\" Start box enclosure. From here until next .BE, everything will be | |
25 | '\" enclosed in one large box. | |
26 | '\" | |
27 | '\" .BE | |
28 | '\" End of box enclosure. | |
29 | '\" | |
30 | '\" .CS | |
31 | '\" Begin code excerpt. | |
32 | '\" | |
33 | '\" .CE | |
34 | '\" End code excerpt. | |
35 | '\" | |
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. | |
42 | '\" | |
43 | '\" .VE | |
44 | '\" End of vertical sidebar. | |
45 | '\" | |
46 | '\" .DS | |
47 | '\" Begin an indented unfilled display. | |
48 | '\" | |
49 | '\" .DE | |
50 | '\" End of indented unfilled display. | |
51 | '\" | |
52 | '\" .SO | |
53 | '\" Start of list of standard options for a Tk widget. The | |
54 | '\" options follow on successive lines, in four columns separated | |
55 | '\" by tabs. | |
56 | '\" | |
57 | '\" .SE | |
58 | '\" End of list of standard options for a Tk widget. | |
59 | '\" | |
60 | '\" .OP cmdName dbName dbClass | |
61 | '\" Start of description of a specific option. cmdName gives the | |
62 | '\" option's name as specified in the class command, dbName gives | |
63 | '\" the option's name in the option database, and dbClass gives | |
64 | '\" the option's class in the option database. | |
65 | '\" | |
66 | '\" .UL arg1 arg2 | |
67 | '\" Print arg1 underlined, then print arg2 normally. | |
68 | '\" | |
69 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
70 | '\" | |
71 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
72 | .if t .wh -1.3i ^B | |
73 | .nr ^l \n(.l | |
74 | .ad b | |
75 | '\" # Start an argument description | |
76 | .de AP | |
77 | .ie !"\\$4"" .TP \\$4 | |
78 | .el \{\ | |
79 | . ie !"\\$2"" .TP \\n()Cu | |
80 | . el .TP 15 | |
81 | .\} | |
82 | .ta \\n()Au \\n()Bu | |
83 | .ie !"\\$3"" \{\ | |
84 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
85 | .\".b | |
86 | .\} | |
87 | .el \{\ | |
88 | .br | |
89 | .ie !"\\$2"" \{\ | |
90 | \&\\$1 \\fI\\$2\\fP | |
91 | .\} | |
92 | .el \{\ | |
93 | \&\\fI\\$1\\fP | |
94 | .\} | |
95 | .\} | |
96 | .. | |
97 | '\" # define tabbing values for .AP | |
98 | .de AS | |
99 | .nr )A 10n | |
100 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
101 | .nr )B \\n()Au+15n | |
102 | .\" | |
103 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
104 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
105 | .. | |
106 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
107 | '\" # BS - start boxed text | |
108 | '\" # ^y = starting y location | |
109 | '\" # ^b = 1 | |
110 | .de BS | |
111 | .br | |
112 | .mk ^y | |
113 | .nr ^b 1u | |
114 | .if n .nf | |
115 | .if n .ti 0 | |
116 | .if n \l'\\n(.lu\(ul' | |
117 | .if n .fi | |
118 | .. | |
119 | '\" # BE - end boxed text (draw box now) | |
120 | .de BE | |
121 | .nf | |
122 | .ti 0 | |
123 | .mk ^t | |
124 | .ie n \l'\\n(^lu\(ul' | |
125 | .el \{\ | |
126 | .\" Draw four-sided box normally, but don't draw top of | |
127 | .\" box if the box started on an earlier page. | |
128 | .ie !\\n(^b-1 \{\ | |
129 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
130 | .\} | |
131 | .el \}\ | |
132 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
133 | .\} | |
134 | .\} | |
135 | .fi | |
136 | .br | |
137 | .nr ^b 0 | |
138 | .. | |
139 | '\" # VS - start vertical sidebar | |
140 | '\" # ^Y = starting y location | |
141 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
142 | .de VS | |
143 | .if !"\\$2"" .br | |
144 | .mk ^Y | |
145 | .ie n 'mc \s12\(br\s0 | |
146 | .el .nr ^v 1u | |
147 | .. | |
148 | '\" # VE - end of vertical sidebar | |
149 | .de VE | |
150 | .ie n 'mc | |
151 | .el \{\ | |
152 | .ev 2 | |
153 | .nf | |
154 | .ti 0 | |
155 | .mk ^t | |
156 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
157 | .sp -1 | |
158 | .fi | |
159 | .ev | |
160 | .\} | |
161 | .nr ^v 0 | |
162 | .. | |
163 | '\" # Special macro to handle page bottom: finish off current | |
164 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
165 | '\" # page bottom macro. | |
166 | .de ^B | |
167 | .ev 2 | |
168 | 'ti 0 | |
169 | 'nf | |
170 | .mk ^t | |
171 | .if \\n(^b \{\ | |
172 | .\" Draw three-sided box if this is the box's first page, | |
173 | .\" draw two sides but no top otherwise. | |
174 | .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 | |
175 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
176 | .\} | |
177 | .if \\n(^v \{\ | |
178 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
179 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
180 | .\} | |
181 | .bp | |
182 | 'fi | |
183 | .ev | |
184 | .if \\n(^b \{\ | |
185 | .mk ^y | |
186 | .nr ^b 2 | |
187 | .\} | |
188 | .if \\n(^v \{\ | |
189 | .mk ^Y | |
190 | .\} | |
191 | .. | |
192 | '\" # DS - begin display | |
193 | .de DS | |
194 | .RS | |
195 | .nf | |
196 | .sp | |
197 | .. | |
198 | '\" # DE - end display | |
199 | .de DE | |
200 | .fi | |
201 | .RE | |
202 | .sp | |
203 | .. | |
204 | '\" # SO - start of list of standard options | |
205 | .de SO | |
206 | .SH "STANDARD OPTIONS" | |
207 | .LP | |
208 | .nf | |
209 | .ta 5.5c 11c | |
210 | .ft B | |
211 | .. | |
212 | '\" # SE - end of list of standard options | |
213 | .de SE | |
214 | .fi | |
215 | .ft R | |
216 | .LP | |
217 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
218 | .. | |
219 | '\" # OP - start of full description for a single option | |
220 | .de OP | |
221 | .LP | |
222 | .nf | |
223 | .ta 4c | |
224 | Command-Line Name: \\fB\\$1\\fR | |
225 | Database Name: \\fB\\$2\\fR | |
226 | Database Class: \\fB\\$3\\fR | |
227 | .fi | |
228 | .IP | |
229 | .. | |
230 | '\" # CS - begin code excerpt | |
231 | .de CS | |
232 | .RS | |
233 | .nf | |
234 | .ta .25i .5i .75i 1i | |
235 | .. | |
236 | '\" # CE - end code excerpt | |
237 | .de CE | |
238 | .fi | |
239 | .RE | |
240 | .. | |
241 | .de UL | |
242 | \\$1\l'|0\(ul'\\$2 | |
243 | .. | |
244 | .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures" | |
245 | .BS | |
246 | '\" Note: do not modify the .SH NAME line immediately below! | |
247 | .SH NAME | |
248 | 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_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels | |
249 | .SH SYNOPSIS | |
250 | .nf | |
251 | \fB#include <tcl.h>\fR | |
252 | .sp | |
253 | Tcl_Channel | |
254 | \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) | |
255 | .sp | |
256 | Tcl_Channel | |
257 | \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) | |
258 | .sp | |
259 | Tcl_Channel | |
260 | \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) | |
261 | .sp | |
262 | Tcl_Channel | |
263 | \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) | |
264 | .VS 8.3 | |
265 | .sp | |
266 | int | |
267 | \fBTcl_GetChannelNames\fR(\fIinterp\fR) | |
268 | .sp | |
269 | int | |
270 | \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR) | |
271 | .VE | |
272 | .sp | |
273 | void | |
274 | \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) | |
275 | .sp | |
276 | int | |
277 | \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) | |
278 | .sp | |
279 | int | |
280 | \fBTcl_DetachChannel\fR(\fIinterp, channel\fR) | |
281 | .sp | |
282 | int | |
283 | \fBTcl_IsStandardChannel\fR(\fIchannel\fR) | |
284 | .sp | |
285 | int | |
286 | \fBTcl_Close\fR(\fIinterp, channel\fR) | |
287 | .sp | |
288 | .VS 8.1 | |
289 | int | |
290 | \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) | |
291 | .sp | |
292 | int | |
293 | \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) | |
294 | .sp | |
295 | int | |
296 | \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) | |
297 | .sp | |
298 | int | |
299 | \fBTcl_Gets\fR(\fIchannel, lineRead\fR) | |
300 | .sp | |
301 | int | |
302 | \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) | |
303 | .sp | |
304 | int | |
305 | \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) | |
306 | .sp | |
307 | int | |
308 | \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) | |
309 | .sp | |
310 | int | |
311 | \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) | |
312 | .VE | |
313 | .VS 8.3.2 | |
314 | .sp | |
315 | int | |
316 | \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) | |
317 | .sp | |
318 | int | |
319 | \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) | |
320 | .VE | |
321 | .sp | |
322 | int | |
323 | \fBTcl_Eof\fR(\fIchannel\fR) | |
324 | .sp | |
325 | int | |
326 | \fBTcl_Flush\fR(\fIchannel\fR) | |
327 | .sp | |
328 | int | |
329 | \fBTcl_InputBlocked\fR(\fIchannel\fR) | |
330 | .sp | |
331 | int | |
332 | \fBTcl_InputBuffered\fR(\fIchannel\fR) | |
333 | .VS 8.4 | |
334 | .sp | |
335 | int | |
336 | \fBTcl_OutputBuffered\fR(\fIchannel\fR) | |
337 | .VE | |
338 | .sp | |
339 | .VS 8.4 | |
340 | Tcl_WideInt | |
341 | \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) | |
342 | .sp | |
343 | Tcl_WideInt | |
344 | \fBTcl_Tell\fR(\fIchannel\fR) | |
345 | .VE 8.4 | |
346 | .sp | |
347 | int | |
348 | \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) | |
349 | .sp | |
350 | int | |
351 | \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) | |
352 | .sp | |
353 | .SH ARGUMENTS | |
354 | .AS Tcl_ChannelType newClientProcPtr in | |
355 | .AP Tcl_Interp *interp in | |
356 | Used for error reporting and to look up a channel registered in it. | |
357 | .AP "CONST char" *fileName in | |
358 | The name of a local or network file. | |
359 | .AP "CONST char" *mode in | |
360 | Specifies how the file is to be accessed. May have any of the values | |
361 | allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. | |
362 | .AP int permissions in | |
363 | POSIX-style permission flags such as 0644. If a new file is created, these | |
364 | permissions will be set on the created file. | |
365 | .AP int argc in | |
366 | The number of elements in \fIargv\fR. | |
367 | .AP "CONST char" **argv in | |
368 | Arguments for constructing a command pipeline. These values have the same | |
369 | meaning as the non-switch arguments to the Tcl \fBexec\fR command. | |
370 | .AP int flags in | |
371 | Specifies the disposition of the stdio handles in pipeline: OR-ed | |
372 | combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and | |
373 | \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child | |
374 | in the pipe is the pipe channel, otherwise it is the same as the standard | |
375 | input of the invoking process; likewise for \fBTCL_STDOUT\fR and | |
376 | \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can | |
377 | redirect stdio handles to override the stdio handles for which | |
378 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it | |
379 | is set, then such redirections cause an error. | |
380 | .AP ClientData handle in | |
381 | Operating system specific handle for I/O to a file. For Unix this is a | |
382 | file descriptor, for Windows it is a HANDLE. | |
383 | .AP int readOrWrite in | |
384 | OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate | |
385 | what operations are valid on \fIhandle\fR. | |
386 | .AP "CONST char" *channelName in | |
387 | The name of the channel. | |
388 | .AP int *modePtr out | |
389 | Points at an integer variable that will receive an OR-ed combination of | |
390 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is | |
391 | open for reading and writing. | |
392 | .VS 8.3 | |
393 | .AP "CONST char" *pattern in | |
394 | The pattern to match on, passed to Tcl_StringMatch, or NULL. | |
395 | .VE | |
396 | .AP Tcl_Channel channel in | |
397 | A Tcl channel for input or output. Must have been the return value | |
398 | from a procedure such as \fBTcl_OpenFileChannel\fR. | |
399 | .VS 8.1 br | |
400 | .AP Tcl_Obj *readObjPtr in/out | |
401 | A pointer to a Tcl Object in which to store the characters read from the | |
402 | channel. | |
403 | .AP int charsToRead in | |
404 | The number of characters to read from the channel. If the channel's encoding | |
405 | is \fBbinary\fR, this is equivalent to the number of bytes to read from the | |
406 | channel. | |
407 | .AP int appendFlag in | |
408 | If non-zero, data read from the channel will be appended to the object. | |
409 | Otherwise, the data will replace the existing contents of the object. | |
410 | .AP char *readBuf out | |
411 | A buffer in which to store the bytes read from the channel. | |
412 | .AP int bytesToRead in | |
413 | The number of bytes to read from the channel. The buffer \fIreadBuf\fR must | |
414 | be large enough to hold this many bytes. | |
415 | .AP Tcl_Obj *lineObjPtr in/out | |
416 | A pointer to a Tcl object in which to store the line read from the | |
417 | channel. The line read will be appended to the current value of the | |
418 | object. | |
419 | .AP Tcl_DString *lineRead in/out | |
420 | A pointer to a Tcl dynamic string in which to store the line read from the | |
421 | channel. Must have been initialized by the caller. The line read will be | |
422 | appended to any data already in the dynamic string. | |
423 | .VS 8.3 | |
424 | .AP "CONST char" *input in | |
425 | The input to add to a channel buffer. | |
426 | .AP int inputLen in | |
427 | Length of the input | |
428 | .AP int addAtEnd in | |
429 | Flag indicating whether the input should be added to the end or | |
430 | beginning of the channel buffer. | |
431 | .VE | |
432 | .AP Tcl_Obj *writeObjPtr in | |
433 | A pointer to a Tcl Object whose contents will be output to the channel. | |
434 | .AP "CONST char" *charBuf in | |
435 | A buffer containing the characters to output to the channel. | |
436 | .AP "CONST char" *byteBuf in | |
437 | A buffer containing the bytes to output to the channel. | |
438 | .AP int bytesToWrite in | |
439 | The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and | |
440 | output to the channel. | |
441 | .VE | |
442 | .AP Tcl_WideInt offset in | |
443 | How far to move the access point in the channel at which the next input or | |
444 | output operation will be applied, measured in bytes from the position | |
445 | given by \fIseekMode\fR. May be either positive or negative. | |
446 | .AP int seekMode in | |
447 | Relative to which point to seek; used with \fIoffset\fR to calculate the new | |
448 | access point for the channel. Legal values are \fBSEEK_SET\fR, | |
449 | \fBSEEK_CUR\fR, and \fBSEEK_END\fR. | |
450 | .AP "CONST char" *optionName in | |
451 | The name of an option applicable to this channel, such as \fB\-blocking\fR. | |
452 | May have any of the values accepted by the \fBfconfigure\fR command. | |
453 | .AP Tcl_DString *optionValue in | |
454 | Where to store the value of an option or a list of all options and their | |
455 | values. Must have been initialized by the caller. | |
456 | .AP "CONST char" *newValue in | |
457 | New value for the option given by \fIoptionName\fR. | |
458 | .BE | |
459 | ||
460 | .SH DESCRIPTION | |
461 | .PP | |
462 | The Tcl channel mechanism provides a device-independent and | |
463 | platform-independent mechanism for performing buffered input | |
464 | and output operations on a variety of file, socket, and device | |
465 | types. | |
466 | The channel mechanism is extensible to new channel types, by | |
467 | providing a low level channel driver for the new type; the channel driver | |
468 | interface is described in the manual entry for \fBTcl_CreateChannel\fR. The | |
469 | channel mechanism provides a buffering scheme modeled after | |
470 | Unix's standard I/O, and it also allows for nonblocking I/O on | |
471 | channels. | |
472 | .PP | |
473 | The procedures described in this manual entry comprise the C APIs of the | |
474 | generic layer of the channel architecture. For a description of the channel | |
475 | driver architecture and how to implement channel drivers for new types of | |
476 | channels, see the manual entry for \fBTcl_CreateChannel\fR. | |
477 | ||
478 | .SH TCL_OPENFILECHANNEL | |
479 | .PP | |
480 | \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and | |
481 | returns a channel handle that can be used to perform input and output on | |
482 | the file. This API is modeled after the \fBfopen\fR procedure of | |
483 | the Unix standard I/O library. | |
484 | The syntax and meaning of all arguments is similar to those | |
485 | given in the Tcl \fBopen\fR command when opening a file. | |
486 | If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR | |
487 | returns NULL and records a POSIX error code that can be | |
488 | retrieved with \fBTcl_GetErrno\fR. | |
489 | In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR | |
490 | leaves an error message in \fIinterp\fR's result after any error. | |
491 | As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should | |
492 | be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. | |
493 | .PP | |
494 | ||
495 | .PP | |
496 | The newly created channel is not registered in the supplied interpreter; to | |
497 | register it, use \fBTcl_RegisterChannel\fR, described below. | |
498 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was | |
499 | previously closed, the act of creating the new channel also assigns it as a | |
500 | replacement for the standard channel. | |
501 | ||
502 | .SH TCL_OPENCOMMANDCHANNEL | |
503 | .PP | |
504 | \fBTcl_OpenCommandChannel\fR provides a C-level interface to the | |
505 | functions of the \fBexec\fR and \fBopen\fR commands. | |
506 | It creates a sequence of subprocesses specified | |
507 | by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can | |
508 | be used to communicate with these subprocesses. | |
509 | The \fIflags\fR argument indicates what sort of communication will | |
510 | exist with the command pipeline. | |
511 | .PP | |
512 | If the \fBTCL_STDIN\fR flag is set then the standard input for the | |
513 | first subprocess will be tied to the channel: writing to the channel | |
514 | will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, | |
515 | then standard input for the first subprocess will be the same as this | |
516 | application's standard input. If \fBTCL_STDOUT\fR is set then | |
517 | standard output from the last subprocess can be read from the channel; | |
518 | otherwise it goes to this application's standard output. If | |
519 | \fBTCL_STDERR\fR is set, standard error output for all subprocesses is | |
520 | returned to the channel and results in an error when the channel is | |
521 | closed; otherwise it goes to this application's standard error. If | |
522 | \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can | |
523 | redirect the stdio handles to override \fBTCL_STDIN\fR, | |
524 | \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an | |
525 | error for argc and argv to override stdio channels for which | |
526 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. | |
527 | .PP | |
528 | If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR | |
529 | returns NULL and records a POSIX error code that can be retrieved with | |
530 | \fBTcl_GetErrno\fR. | |
531 | In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in | |
532 | the interpreter's result if \fIinterp\fR is not NULL. | |
533 | .PP | |
534 | The newly created channel is not registered in the supplied interpreter; to | |
535 | register it, use \fBTcl_RegisterChannel\fR, described below. | |
536 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was | |
537 | previously closed, the act of creating the new channel also assigns it as a | |
538 | replacement for the standard channel. | |
539 | ||
540 | .SH TCL_MAKEFILECHANNEL | |
541 | .PP | |
542 | \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, | |
543 | platform-specific, file handle. | |
544 | The newly created channel is not registered in the supplied interpreter; to | |
545 | register it, use \fBTcl_RegisterChannel\fR, described below. | |
546 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was | |
547 | previously closed, the act of creating the new channel also assigns it as a | |
548 | replacement for the standard channel. | |
549 | ||
550 | .SH TCL_GETCHANNEL | |
551 | .PP | |
552 | \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to | |
553 | create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in | |
554 | \fIinterp\fR. If a channel by that name is not registered in that interpreter, | |
555 | the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it | |
556 | points at an integer variable that will receive an OR-ed combination of | |
557 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is | |
558 | open for reading and writing. | |
559 | .PP | |
560 | \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the | |
561 | names of the registered channels to the interpreter's result as a | |
562 | list object. \fBTcl_GetChannelNamesEx\fR will filter these names | |
563 | according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it | |
564 | will not do any filtering. The return value is \fBTCL_OK\fR if no | |
565 | errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR, | |
566 | and the error message is left in the interpreter's result. | |
567 | ||
568 | .SH TCL_REGISTERCHANNEL | |
569 | .PP | |
570 | \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible | |
571 | in \fIinterp\fR. After this call, Tcl programs executing in that | |
572 | interpreter can refer to the channel in input or output operations using | |
573 | the name given in the call to \fBTcl_CreateChannel\fR. After this call, | |
574 | the channel becomes the property of the interpreter, and the caller should | |
575 | not call \fBTcl_Close\fR for the channel; the channel will be closed | |
576 | automatically when it is unregistered from the interpreter. | |
577 | .PP | |
578 | Code executing outside of any Tcl interpreter can call | |
579 | \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it | |
580 | wishes to hold a reference to this channel. Subsequently, the channel can | |
581 | be registered in a Tcl interpreter and it will only be closed when the | |
582 | matching number of calls to \fBTcl_UnregisterChannel\fR have been made. | |
583 | This allows code executing outside of any interpreter to safely hold a | |
584 | reference to a channel that is also registered in a Tcl interpreter. | |
585 | .PP | |
586 | This procedure interacts with the code managing the standard | |
587 | channels. If no standard channels were initialized before the first | |
588 | call to \fBTcl_RegisterChannel\fR they will get initialized by that | |
589 | call. See \fBTcl_StandardChannels\fR for a general treatise about | |
590 | standard channels and the behaviour of the Tcl library with regard to | |
591 | them. | |
592 | ||
593 | .SH TCL_UNREGISTERCHANNEL | |
594 | .PP | |
595 | \fBTcl_UnregisterChannel\fR removes a channel from the set of channels | |
596 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be | |
597 | able to use the channel's name to refer to the channel in that interpreter. | |
598 | If this operation removed the last registration of the channel in any | |
599 | interpreter, the channel is also closed and destroyed. | |
600 | .PP | |
601 | Code not associated with a Tcl interpreter can call | |
602 | \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl | |
603 | that it no longer holds a reference to that channel. If this is the last | |
604 | reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR | |
605 | is very similar to \fBTcl_DetachChannel\fR except that it will also | |
606 | close the channel if no further references to it exist. | |
607 | ||
608 | .SH TCL_DETACHCHANNEL | |
609 | .PP | |
610 | \fBTcl_DetachChannel\fR removes a channel from the set of channels | |
611 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be | |
612 | able to use the channel's name to refer to the channel in that interpreter. | |
613 | Beyond that, this command has no further effect. It cannot be used on | |
614 | the standard channels (stdout, stderr, stdin), and will return | |
615 | TCL_ERROR if passed one of those channels. | |
616 | .PP | |
617 | Code not associated with a Tcl interpreter can call | |
618 | \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl | |
619 | that it no longer holds a reference to that channel. If this is the last | |
620 | reference to the channel, unlike \fBTcl_UnregisterChannel\fR, | |
621 | it will not be closed. | |
622 | ||
623 | .SH TCL_ISSTANDARDCHANNEL | |
624 | .PP | |
625 | \fBTcl_IsStandardChannel\fR tests whether a channel is one of the | |
626 | three standard channels, stdin, stdout or stderr. If so, it returns | |
627 | 1, otherwise 0. | |
628 | .PP | |
629 | No attempt is made to check whether the given channel or the standard | |
630 | channels are initialized or otherwise valid. | |
631 | ||
632 | .SH TCL_CLOSE | |
633 | .PP | |
634 | \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a | |
635 | currently open channel. The channel should not be registered in any | |
636 | interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to | |
637 | the channel's output device prior to destroying the channel, and any | |
638 | buffered input is discarded. If this is a blocking channel, the call does | |
639 | not return until all buffered data is successfully sent to the channel's | |
640 | output device. If this is a nonblocking channel and there is buffered | |
641 | output that cannot be written without blocking, the call returns | |
642 | immediately; output is flushed in the background and the channel will be | |
643 | closed once all of the buffered data has been output. In this case errors | |
644 | during flushing are not reported. | |
645 | .PP | |
646 | If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR. | |
647 | If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a | |
648 | POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. | |
649 | If the channel is being closed synchronously and an error occurs during | |
650 | closing of the channel and \fIinterp\fR is not NULL, an error message is | |
651 | left in the interpreter's result. | |
652 | .PP | |
653 | Note: it is not safe to call \fBTcl_Close\fR on a channel that has been | |
654 | registered using \fBTcl_RegisterChannel\fR; see the documentation for | |
655 | \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever | |
656 | been given as the \fBchan\fR argument in a call to | |
657 | \fBTcl_RegisterChannel\fR, you should instead use | |
658 | \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR | |
659 | when all calls to \fBTcl_RegisterChannel\fR have been matched by | |
660 | corresponding calls to \fBTcl_UnregisterChannel\fR. | |
661 | ||
662 | .VS 8.1 br | |
663 | .SH "TCL_READCHARS AND TCL_READ" | |
664 | .PP | |
665 | \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes | |
666 | to UTF-8 based on the channel's encoding and storing the produced data in | |
667 | \fIreadObjPtr\fR's string representation. The return value of | |
668 | \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, | |
669 | that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the | |
670 | return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that | |
671 | can be retrieved with \fBTcl_GetErrno\fR. | |
672 | .PP | |
673 | Setting \fIcharsToRead\fR to \fB-1\fR will cause the command to read | |
674 | all characters currently available (non-blocking) or everything until | |
675 | eof (blocking mode). | |
676 | .PP | |
677 | The return value may be smaller than the value to read, indicating that less | |
678 | data than requested was available. This is called a \fIshort read\fR. In | |
679 | blocking mode, this can only happen on an end-of-file. In nonblocking mode, | |
680 | a short read can also occur if there is not enough input currently | |
681 | available: \fBTcl_ReadChars\fR returns a short count rather than waiting | |
682 | for more data. | |
683 | .PP | |
684 | If the channel is in blocking mode, a return value of zero indicates an | |
685 | end-of-file condition. If the channel is in nonblocking mode, a return | |
686 | value of zero indicates either that no input is currently available or an | |
687 | end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell | |
688 | which of these conditions actually occurred. | |
689 | .PP | |
690 | \fBTcl_ReadChars\fR translates the various end-of-line representations into | |
691 | the canonical \fB\en\fR internal representation according to the current | |
692 | end-of-line recognition mode. End-of-line recognition and the various | |
693 | platform-specific modes are described in the manual entry for the Tcl | |
694 | \fBfconfigure\fR command. | |
695 | .PP | |
696 | As a performance optimization, when reading from a channel with the encoding | |
697 | \fBbinary\fR, the bytes are not converted to UTF-8 as they are read. | |
698 | Instead, they are stored in \fIreadObjPtr\fR's internal representation as a | |
699 | byte-array object. The string representation of this object will only be | |
700 | constructed if it is needed (e.g., because of a call to | |
701 | \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read | |
702 | from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and | |
703 | related functions, and then written to a channel without the expense of ever | |
704 | converting to or from UTF-8. | |
705 | .PP | |
706 | \fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it doesn't do | |
707 | encoding conversions, regardless of the channel's encoding. It is deprecated | |
708 | and exists for backwards compatibility with non-internationalized Tcl | |
709 | extensions. It consumes bytes from \fIchannel\fR and stores them in | |
710 | \fIreadBuf\fR, performing end-of-line translations on the way. The return value | |
711 | of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in | |
712 | \fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated. | |
713 | Its contents are valid from the zeroth position up to and excluding the | |
714 | position indicated by the return value. | |
715 | .PP | |
716 | \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not | |
717 | compensate for stacking. While \fBTcl_Read\fR (and the other functions | |
718 | in the API) always get their data from the topmost channel in the | |
719 | stack the supplied channel is part of, \fBTcl_ReadRaw\fR does | |
720 | not. Thus this function is \fBonly\fR usable for transformational | |
721 | channel drivers, i.e. drivers used in the middle of a stack of | |
722 | channels, to move data from the channel below into the transformation. | |
723 | ||
724 | .SH "TCL_GETSOBJ AND TCL_GETS" | |
725 | .PP | |
726 | \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to | |
727 | UTF-8 based on the channel's encoding, until a full line of input has been | |
728 | seen. If the channel's encoding is \fBbinary\fR, each byte read from the | |
729 | channel is treated as an individual Unicode character. All of the | |
730 | characters of the line except for the terminating end-of-line character(s) | |
731 | are appended to \fIlineObjPtr\fR's string representation. The end-of-line | |
732 | character(s) are read and discarded. | |
733 | .PP | |
734 | If a line was successfully read, the return value is greater than or equal | |
735 | to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an | |
736 | error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code | |
737 | that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also | |
738 | returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure | |
739 | can be used to distinguish an error from an end-of-file condition. | |
740 | .PP | |
741 | If the channel is in nonblocking mode, the return value can also be \-1 if | |
742 | no data was available or the data that was available did not contain an | |
743 | end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR | |
744 | procedure may be invoked to determine if the channel is blocked because | |
745 | of input unavailability. | |
746 | .PP | |
747 | \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting | |
748 | characters are appended to the dynamic string given by | |
749 | \fIlineRead\fR rather than a Tcl object. | |
750 | ||
751 | .SH "TCL_UNGETS" | |
752 | .PP | |
753 | \fBTcl_Ungets\fR is used to add data to the input queue of a channel, | |
754 | at either the head or tail of the queue. The pointer \fIinput\fR points | |
755 | to the data that is to be added. The length of the input to add is given | |
756 | by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the | |
757 | data is to be added at the end of queue; otherwise it will be added at the | |
758 | head of the queue. If \fIchannel\fR has a "sticky" EOF set, no data will be | |
759 | added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or | |
760 | -1 if an error occurs. | |
761 | ||
762 | .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" | |
763 | .PP | |
764 | \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at | |
765 | \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the | |
766 | channel's encoding and queued for output to \fIchannel\fR. If | |
767 | \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR | |
768 | to be null-terminated and it outputs everything up to the null. | |
769 | .PP | |
770 | Data queued for output may not appear on the output device immediately, due | |
771 | to internal buffering. If the data should appear immediately, call | |
772 | \fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the | |
773 | \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data | |
774 | to appear as soon as a complete line is accepted for output, set the | |
775 | \fB\-buffering\fR option on the channel to \fBline\fR mode. | |
776 | .PP | |
777 | The return value of \fBTcl_WriteChars\fR is a count of how many bytes were | |
778 | accepted for output to the channel. This is either greater than zero to | |
779 | indicate success or \-1 to indicate that an error occurred. If an error | |
780 | occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be | |
781 | retrieved with \fBTcl_GetErrno\fR. | |
782 | .PP | |
783 | Newline characters in the output data are translated to platform-specific | |
784 | end-of-line sequences according to the \fB\-translation\fR option for the | |
785 | channel. This is done even if the channel has no encoding. | |
786 | .PP | |
787 | \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it | |
788 | accepts a Tcl object whose contents will be output to the channel. The | |
789 | UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted | |
790 | to the channel's encoding and queued for output to \fIchannel\fR. | |
791 | As a performance optimization, when writing to a channel with the encoding | |
792 | \fBbinary\fR, UTF-8 characters are not converted as they are written. | |
793 | Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a | |
794 | byte-array object are written to the channel. The byte-array representation | |
795 | of the object will be constructed if it is needed. In this way, | |
796 | byte-oriented data can be read from a channel, manipulated by calling | |
797 | \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a | |
798 | channel without the expense of ever converting to or from UTF-8. | |
799 | .PP | |
800 | \fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it doesn't do | |
801 | encoding conversions, regardless of the channel's encoding. It is | |
802 | deprecated and exists for backwards compatibility with non-internationalized | |
803 | Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at | |
804 | \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If | |
805 | \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be | |
806 | null-terminated and it outputs everything up to the null. | |
807 | .PP | |
808 | \fBTcl_WriteRaw\fR is the same as \fBTcl_Write\fR but does not | |
809 | compensate for stacking. While \fBTcl_Write\fR (and the other | |
810 | functions in the API) always feed their input to the topmost channel | |
811 | in the stack the supplied channel is part of, \fBTcl_WriteRaw\fR does | |
812 | not. Thus this function is \fBonly\fR usable for transformational | |
813 | channel drivers, i.e. drivers used in the middle of a stack of | |
814 | channels, to move data from the transformation into the channel below | |
815 | it. | |
816 | .VE | |
817 | ||
818 | .SH TCL_FLUSH | |
819 | .PP | |
820 | \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR | |
821 | to be written to its underlying file or device as soon as possible. | |
822 | If the channel is in blocking mode, the call does not return until | |
823 | all the buffered data has been sent to the channel or some error occurred. | |
824 | The call returns immediately if the channel is nonblocking; it starts | |
825 | a background flush that will write the buffered data to the channel | |
826 | eventually, as fast as the channel is able to absorb it. | |
827 | .PP | |
828 | The return value is normally \fBTCL_OK\fR. | |
829 | If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and | |
830 | records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. | |
831 | ||
832 | .SH TCL_SEEK | |
833 | .PP | |
834 | \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent | |
835 | data will be read or written. Buffered output is flushed to the channel and | |
836 | buffered input is discarded, prior to the seek operation. | |
837 | .PP | |
838 | \fBTcl_Seek\fR normally returns the new access point. | |
839 | If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error | |
840 | code that can be retrieved with \fBTcl_GetErrno\fR. | |
841 | After an error, the access point may or may not have been moved. | |
842 | ||
843 | .SH TCL_TELL | |
844 | .PP | |
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 | ||
848 | .SH TCL_GETCHANNELOPTION | |
849 | .PP | |
850 | \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of | |
851 | the options currently in effect for a channel, or a list of all options and | |
852 | their values. The \fIchannel\fR argument identifies the channel for which | |
853 | to query an option or retrieve all options and their values. | |
854 | If \fIoptionName\fR is not NULL, it is the name of the | |
855 | option to query; the option's value is copied to the Tcl dynamic string | |
856 | denoted by \fIoptionValue\fR. If | |
857 | \fIoptionName\fR is NULL, the function stores an alternating list of option | |
858 | names and their values in \fIoptionValue\fR, using a series of calls to | |
859 | \fBTcl_DStringAppendElement\fR. The various preexisting options and | |
860 | their possible values are described in the manual entry for the Tcl | |
861 | \fBfconfigure\fR command. Other options can be added by each channel type. | |
862 | These channel type specific options are described in the manual entry for | |
863 | the Tcl command that creates a channel of that type; for example, the | |
864 | additional options for TCP based channels are described in the manual entry | |
865 | for the Tcl \fBsocket\fR command. | |
866 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns | |
867 | \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX | |
868 | error code. | |
869 | ||
870 | .SH TCL_SETCHANNELOPTION | |
871 | .PP | |
872 | \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR | |
873 | for an option \fIoptionName\fR on \fIchannel\fR. | |
874 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, | |
875 | it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, | |
876 | \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result. | |
877 | ||
878 | .SH TCL_EOF | |
879 | .PP | |
880 | \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered | |
881 | an end of file during the last input operation. | |
882 | ||
883 | .SH TCL_INPUTBLOCKED | |
884 | .PP | |
885 | \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in | |
886 | nonblocking mode and the last input operation returned less data than | |
887 | requested because there was insufficient data available. | |
888 | The call always returns zero if the channel is in blocking mode. | |
889 | ||
890 | .SH TCL_INPUTBUFFERED | |
891 | .PP | |
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 | ||
896 | .SH TCL_OUTPUTBUFFERED | |
897 | .VS 8.4 | |
898 | \fBTcl_OutputBuffered\fR returns the number of bytes of output | |
899 | currently buffered in the internal buffers for a channel. If the | |
900 | channel is not open for writing, this function always returns zero. | |
901 | .VE | |
902 | ||
903 | .SH "PLATFORM ISSUES" | |
904 | .PP | |
905 | The handles returned from \fBTcl_GetChannelHandle\fR depend on the | |
906 | platform and the channel type. On Unix platforms, the handle is | |
907 | always a Unix file descriptor as returned from the \fBopen\fR system | |
908 | call. On Windows platforms, the handle is a file \fBHANDLE\fR when | |
909 | the channel was created with \fBTcl_OpenFileChannel\fR, | |
910 | \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other | |
911 | channel types may return a different type of handle on Windows | |
912 | platforms. On the Macintosh platform, the handle is a file reference | |
913 | number as returned from \fBHOpenDF\fR. | |
914 | ||
915 | .SH "SEE ALSO" | |
916 | DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) | |
917 | ||
918 | .SH KEYWORDS | |
919 | access point, blocking, buffered I/O, channel, channel driver, end of file, | |
920 | flush, input, nonblocking, output, read, seek, write |